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.

Related Topics