GET /oauth/auz/authorize

Starts the authentication of the resource owner. On success, the user sees a login page based on the resource owner domain configured by the OAuth provider, so the user can complete authentication. Similar functionality to SSO Login in the Login service. Uses HTTP GET.

Note: there is a corresponding operation that performs the same action using HTTP POST: POST /oauth/auz/authorize. For information on why you might choose one or the other, see OAuth Operations: GET or POST? In general, GET is more popular for this operation.

Authorization Roles/Permissions: Anyone can run this operation.

This topic includes the following sections:

HTTP Method

GET

URL

https://{oauth-provider-url}/oauth/auz/authorize

Sample Request

The example below shows an authorization request.

Request URL #1

https://{oauth-provider-url}/oauth/auz/authorize?response_type=code&state=
&client_id=smoke-7kkCMrRcgpdhKNBTF7tbcM7dTlieLwPRQo1E8Rb4&scope=scope
&redirect_uri=http%3A%2F%2Fsmokecloud-ubuntu1664-mysql57.aws.akana.roguewave.com%3A7900%2F
&code_challenge=Fo9h7PBBSXlHHfHmICjVNVlj36PrntQ1wOZpG99iuAM&code_challenge_method=plain

Request URL #2

OAuth 1.0a authorization request.

https://{oauth-provider-url}/oauth/auz/authorize?oauth_token=45c8npv52e48

Request URL #3 (PKCE)

OAuth2.0 authorization request with PKCE support enabled (2020.2.0 and later). The two PKCE values are provided: code_challenge is included and code_challenge_method is plain. If successful, the server presents the authorization page. Line breaks have been added. For the response, see Sample response example #2 (PKCE) below.

https://{oauth-provider-url}/oauth/auz/authorize?response_type=code&state=
&client_id=smoke-7kkCMrRcgpdhKNBTF7tbcM7dTlieLwPRQo1E8Rb4&scope=scope
&redirect_uri=http%3A%2F%2Fsmokecloud-ubuntu1664-mysql57.aws.akana.roguewave.com%3A7900%2F
&code_challenge=Fo9h7PBBSXlHHfHmICjVNVlj36PrntQ1wOZpG99iuAM&code_challenge_method=plain HTTP/1.1

Sample request headers

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Sample request body

Not applicable.

Sample request #4

In the example below, each parameter is shown on a different line, for clarity.

https://op.example.com/authorize?
response_type=code
&client_id=client
&redirect_uri=[https://client.example.com|https://client.example.com/]
&scope=openid
&claims=\{"userinfo" : {"access_group": { "value" : "e70bb324-e2fa-4b09-a490-2116dfb80d49"}} , "id_token" : {" access_group":
{ "value" : "e70bb324-e2fa-4b09-a490-2116dfb80d49" }
}}

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header Description
Accept None required; however, the response is an HTML page.

Request Parameters

Note: the query parameters for the GET operation are form parameters for the POST operation.

Parameter Parm Type Data Type Required Description
oauth_token Query String Optional The OAuth 1.0 token; could be a GrantID.
oauth_verifier Query String Optional The OAuth 1.0 verifier; an internal value used as a temporary authorization code for the grant.
response_type Query String Required

OAuth 2.0: standard response_type parameter.

The response type value is derived based on the grant types.

client_id Query String Required OAuth 2.0: standard client_id parameter. The client identifier.
redirect_uri Query String Required OAuth 2.0: standard redirect_uri parameter. The redirect URI configured by the app. For more information, see OAuth Parameters.
scope Query String Optional OAuth 2.0: standard scope parameter. One or more scopes configured in the OAuth provider. Space separator for multiple scopes.
state Query String   OAuth 2.0: standard state parameter.
nonce Query String Optional

Used in the OpenID Connect implicit flow. Based on the response type, nonce might be required.

A nonce value for the openid request—a random string that is uniquely generated for each request.

response_mode Query String Optional The response will be returned based on the response_mode value. Supported values for the platform's OpenID Connect Relying Party domain: form_post, query, or fragment (see OpenID Connect Relying Party Response Mode values).
claims Query String Optional

Used to request that specific Claims be returned. The value is a JSON object listing the requested Claims, as covered by the OpenID Connect specification: https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter.

OAuth 2.0 only.

code_challenge Query String Optional Used for PKCE support, when using Authorization Code grant type with PKCE, to send the code challenge value to the authorization endpoint. For more information on PKCE, see PKCE support with the Authorization Code grant type.
code_challenge_method Query String Optional Used for PKCE support, when using Authorization Code grant type with PKCE, to send the code challenge method to the authorization endpoint. For the API call to be successful, the value much match the value specified in the OAuth Provider configuration. Possible values: plain, S256. For more information on PKCE, see PKCE support with the Authorization Code grant type.

Response

If successful, this operation returns HTTP status code 200, with a grant that is created and returned as a path parameter. A successful response redirects the resource owner to the login page for authenticating and then authorizing scopes.

Sample Response

The sample response below shows successful completion of this operation. The grant ID is returned in the Location header.

Sample response headers

HTTP/1.1 302 Found
Expires: Thu, 09 Jul 2015 13:57:23 GMT
Location: http://{oauth-provider-hostname}/oauthauz/#/grant/viit0bmhe2vl/authenticate

Sample response body

The response is a redirect back to the client URL as specified in the Location header, for client authorization.

None.

Sample response example #2 (PKCE)

The image below shows a successful request and response with PKCE enabled. The response is a 302 redirect to the URL specified in the Location header.

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header Description
Location

The URL to which the resource owner is redirected after authentication is successful. The redirect URL, previously provided by the client to the identity provider and/or specified in the redirect_uri request parameter, is provided as the value for the Location header.

The GrantID is included in the Location header.

Response Body

None. The response is a redirect of the user back to the client app's redirect_uri.

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item Value
200

Client id null.

Invalid_request. The request is missing a required parameter or includes an invalid parameter.

200 Invalid response type. The response type is not supported.
200

Nonce (required for hybrid grant types).

Nonce is a mandatory parameter for OpenID Connect implicit flow authentication requests.

200

Client ID not valid.

The client is not authorized to request an authorization code.

200

Scope not valid (if openid scope not present and corresponding response types are present).

The response type is not supported.

200

Scope not valid (if the scope configured is not present in the request).

The requested scope is invalid or missing.

302 Invalid redirect_uri.
500 An error occurred processing the call.

More information about Akana OAuth API error messages.