2.3 Building an OAuth Client

The OAuth client uses APIs to retrieve, manage and use the access tokens for accessing the OAuth protected resource. The steps for these operations may vary depending on the selected OAuth authorization grant type.

This section includes steps for implementing the following OAuth flows:

2.3.1 Authorization Code

Register the Client Application

If you have not registered the client application, register it and ensure that the grant type is authorization code.

Using user portal page: Set Grants Required field as Authorization Code

Using REST API: Specify the value of grant_types parameter as authorization_code

After registering the client application you must save the client ID and the secret securely.

Request for Authorization Code

To get the authorization code, send an HTTPS GET request to the Authorization Endpoint with the appropriate query parameters.

NOTE:HTTP connections are denied. Therefore, use HTTPS.

Sample request:

https://<idphost:port>/nidp/oauth/nam/authz?response_type=code&client_id=bb775b12-bbd4-423b-83d9-647aeb98608d&redirect_uri=https://client.oauth.com/callback&scope=profile+email&nonce=ab8932b6&state=AB32623HS

Request Parameter

Description

client_id

Client application ID obtained during client registration.

response_type

Set it to "code", to indicate Authorization Code flow. OpenID Connect Hybrid flow is supported. The supported response_type values are “none”, "code", "code id_token", "code token" and "code id_token token".

redirect_uri

Access Manager will redirect with the authorization code only to URIs specified during registration. Specify this parameter if you have pre-registered multiple redirect URIs and want to select the specific one to redirect to. Ensure that this exactly matches one of the pre-registered URI.

If not specified, it defaults to any one of the registered URIs.

nonce

String value used to associate a Client session with an ID Token, and to mitigate replay attacks.

This is required when you have specified the response_type as id_token or you have sent the request with the token and id_token along with the code.

The preceding table lists the minimal set of parameters. For the complete list of parameters, see Section 4.3, Authorization Endpoint.

NOTE:The authorization code flow does not support the basic authorization header in an authorization request. However, this flow supports the basic authorization header in an access token request.

Client Receives the Authorization Code

The Identity Server responds with an HTTP 302 redirect message leading to the redirect_uri specified in the authorization request. If the request does not contain the redirect_uri parameter, Identity Server will redirect to one of the registered redirect_uri.

Sample Response

Response HTTP/1.1 302 Found Cache-Control: no-cache, no-store, no-transform Location: https://client.oauth.com/callback? code=eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0Niwi......&scope=email

NOTE:If response_type=code id_token token, access token and ID token will be included in the response.

Response Data

Description

code

An opaque JWT token. Variable length field. Application should not assume the size of the code and should allocate sufficient space for reading the code.

state

Contains the state parameter sent in the authentication request above

id_token

Based on response_type sent in the request. If the response_type value is either “code id_token”, “ code id_token token” then authorization server sends id_token.

access_token

Based on response_type sent in the request. If the response_type value is either “code token” or “code id_token token” then authorization server sends access token.

expires_in

Based on response_type sent in the request. Expiration time of the code in seconds since the response was generated.

Get Access Token

The code can be exchanged for tokens by sending an HTTPS POST request to the Token Endpoint with the required parameters. The only supported web protocol is HTTPS.

NOTE:You can exchange an authorization code only once.

Sample Request

curl --request POST \--url https://<idphost:port> /nidp/oauth/nam/token \--header 'content-type: application/x-www-form-urlencoded' \--data 'grant_type=authorization_code&client_id=b017c96c-b16a-4d80-a5fa-68f5050abc58&client_secret=ZDDwbuuWPdV_e5quAf7f0Jkg_iJJ7g&redirect_uri=https://client.oauth.com/callback&code=eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwi.......' 

Request Parameter

Description

grant_type

Set to "authorization_code"

client_id

Client ID of the registered client

client_secret

Client Secret of the registered client. It is optional for native applications and is mandatory for web applications.

code

Code received in the Authorization code flow

redirect_uri

This should be same as the one sent during the authorization code request

The preceding table lists the minimal set of parameters. For the complete list of parameters, see Section 4.4, Token Endpoint.

Sample Response

{"access_token": 
"eyJhbGciOiJSU0ExXzU......",
"token_type": "bearer","expires_in": 179,
"refresh_token": "eyJhbGcidHlwIjoiSldUIiwiemlwjo..........",
"scope": "email"}

Response Parameter

Description

token_type

Authorization server currently supports only "Bearer" token type

access_token

Access token that can be used to invoke resource server APIs

id_token

When invoking authorization code request, if the client has sent OpenID in scope parameter, this response object will contain an ID Token. IDToken is signed and encrypted based on the client's registration.

Scope

The list of scopes that user has authorized. Hence this may not contain all the scopes that the client requested.

State

If the "state" parameter was present in the client authorization request, the same state value is sent in response.

NOTE:If there are validation errors, the JSON response returns HTTP Status 400 with additional fields error and error_description.

Try Now

To view how the authorization code flow works, you can use the Access Manager OAuth sample scripts. For more information about the sample scripts, see Section 5.0, Developer Resources.

2.3.2 Authorization Code with PKCE

Register the Client Application

If you have not registered the client application, register it and the grant type must be authorization code.

Using user portal page: Set Grants Required field as Authorization Code

Using REST API: Specify the value of grant_types parameter as authorization_code

After registering the client application you must save the client ID and the secret securely.

Request for Authorization Code with PKCE

Client sends the code challenge as part of the OAuth 2.0 Authorization request with following additional parameters:

Sample request:

https://<<IDP>>:8443/nidp/oauth/nam/authz?code_challenge=WsEH2Rr4lWdciBEb
CuHVlH_UIBUGFPRbDXcPsbPl74&code_challenge_method=S256&scope=profile&response_type=code&redirect_uri=<<Redirect_URI>>&client_id=484fd33f-12b0-44c4-bbf5-82bae803b71d 

Request Parameter

Description

code_challenge

Specify the code challenge parameter to initiate the PKCE flow.

code_challenge_method

This is an optional parameter. The default value is plain.

You can specify the value as plain or S256.

The preceding table lists the minimal set of parameters. For the complete list of parameters, see Section 4.3, Authorization Endpoint.

Client Receives the Authorization Code

The Identity Server responds with an HTTP 302 redirect message to the redirect_uri specified in the Authorization request. If the request does not contain redirect_uri parameter, the Identity Server will redirect to one of the registered redirect_uri.

Sample Response

Response HTTP/1.1 302 Found Cache-Control: no-cache, no-store, no-transform Location: https://client.oauth.com/callback? code=eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0Niwi......&scope=email

NOTE:If you specify response_type=code id_token token, access token and ID token will be included in the response.

Response Parameter

Description

code

An opaque binary token. Variable length field. Application should not assume the size of the code and should allocate sufficient space for reading the code.

state

Contains the state parameter sent in the authentication request above

id_token

Based on response_type sent in the request. If the response_type value is either code id_token, code id_token token then authorization server sends ID token.

access_token

Based on response_type sent in the request. If the response_type value is either code id_token, code id_token token, then authorization server sends access token.

expires_in

Based on response_type sent in the request. Expiration time of the access token in seconds since the response was generated.

Get Access Token

The code can be exchanged for tokens by sending an HTTPS POST request to Token Endpoint with the required parameters. The token request must contain the code_verifier parameter. The only supported web protocol is HTTPS.

NOTE:You can exchange an authorization code only once.

Sample Request

curl --request POST \--url https://<idphost:port> /nidp/oauth/nam/token \--header 'content-type: application/x-www-form-urlencoded' \--data 'grant_type=authorization_code&redirect_uri=<Redirect_URI>&client_id=484fd33f-12b0-44c4-bbf5-
82bae803b71d&code_verifier=0ak1mD3loHOy1ZksmyoO1fQEhRBEuzGYbkQqKFe1N
y0' 

Request Parameter

Description

grant_type

Set to "authorization_code"

client_id

Client ID of the registered client

client_secret

Client Secret of the registered client. It is optional for native applications and is mandatory for web applications.

code

Code received in the Authorization code flow

redirect_uri

This should be same as the one sent during the authorization code request

code_verifier

Code verifier parameter is required if authorization code is requested using the PKCE flow.

The server verifies code_verifier before returning the token.

The preceding table lists the minimal set of parameters. For information about the complete list of parameters, see Section 4.4, Token Endpoint.

Sample Response

{"access_token": 
"eyJhbGciOiJSU0ExXzU......",
"token_type": "bearer","expires_in": 179,
"refresh_token": "eyJhbGcidHlwIjoiSldUIiwiemlwjo..........",
"scope": "email"}

Response Parameter

Description

token_type

Authorization server currently supports only "Bearer" token type.

access_token

Access token that can be used to invoke resource server APIs.

id_token

When invoking authorization code request, if the client has sent OpenID in scope parameter, this response object will contain an ID Token. IDToken is signed and encrypted based on the client's registration.

Scope

The list of scopes that user has authorized. Hence this may not contain all the scopes that the client requested.

State

If the "state" parameter was present in the client authorization request, the same state value sends in response.

NOTE:If validation errors occurred, HTTP Status 400 is returned with additional fields "error" and "error_description" in the JSON response.

Try Now

To view how the authorization code with PKCE flow works, you can use the Access Manager OAuth sample script. For more information about the OAuth samples, see Section 5.0, Developer Resources.

2.3.3 Implicit

The implicit flow is the simplest to integrate but it is also considered as insecure because the access token is sent in the browser request. To secure this token, Access Manager sends these tokens in the fragment mode.

Register the Client Application

If you have not registered the client application, register it and the grant type must be implicit.

Using user portal page: Set Grants Required field as Implicit

Using REST API: Specify the value of grant_types parameter as implicit

After registering the client application you must save the client ID and the secret securely.

Application sends Implicit token request

To initiate the Implicit Grant flow, make an HTTPS GET request to the Authorization endpoint with required parameters. The only supported web protocol is HTTPS.

Sample Request

https://<idphost:port>/nidp/oauth/nam/authz?response_type=token+id_token&client_id=4e4ae330-1215-4fc8-9aa7-79df8325451c&redirect_uri=https://client.oauth.com/callback&scope=profile+email+OpenID&state=s1234&nonce=n123

Request Parameter

Description

client_id

Client application ID obtained during client registration

response_type

Set to 'token''. OpenID Connect Hybrid flow is supported. The supported response_type are “none”, "token", "id_token", and "token id_token".

redirect_uri

If provided, the value of this must exactly match one of URIs of the registered application.

state

An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when the response sends to the client. The parameter is used to prevent cross-site forgery requests.

nonce

String value used to associate a Client session with an ID Token. It is used to mitigate replay attacks.

This is a mandatory parameter when the response_type includes id_token.

The preceding table lists the minimal set of parameters. For the complete list of parameters see, Section 4.3.1, Request Parameters.

NOTE:The Basic Authorization header is not supported for the implicit flow.

Application receives token response

The Authorization Endpoint sends an HTTP 302 redirect response with token and/or id_token as a fragment to the registered redirect_uri.

Sample Response

https://client.oauth.com/callback#token_type=bearer&access_token=eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1O......&expires_in=3600&id_token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJo&scope=email&state=s1234

Response Parameter

Description

token_type

The type of the token. Authorization server currently supports only Bearer type

access_token

Based on response_type value sent in the request. If the response_type value is either "token" or "token id_token" then authorization server returns access token

id_token

Based on response_type sent in the request. If the response_type value is either "id_token" or "token id_token" then authorization server returns id_token.

scope

The list of scopes that user has authorized. This can contain all the scopes the client requested or lesser.

state

if the "state" parameter was present in the client authorization request, the same state value sends in response.

NOTE:If validation errors occurred, HTTP Status 400 is returned with additional fields "error" and "error_description" in the JSON response.

Try Now

To view how the implicit flow works, you can use the Access Manager OAuth samples. For more information about the samples, see Section 5.0, Developer Resources.

2.3.4 Resource Owner

Register the Client Application

If you have not registered the client application, register it and the grant type must be resource owner credentials.

Using user portal page: Set Grants Required field as Resource Owner Credentials

Using REST API: Specify the value of grant_types parameter as password

After registering the client application you must save the client ID and the secret securely.

Application Requests for Access Token

The client application should collect the user credentials and make HTTPS POST request to the token endpoint for an access token.

NOTE:The HTTP connections are refused, use HTTPS.

Sample CURL request

curl --request POST \
 --url https://<idphost:port>/nidp/oauth/nam/token \
 --header 'content-type: application/x-www-form-urlencoded' \
 --data 'grant_type=password&client_id=bb775b12-bbd4-423b-83d9-647aeb98608d&client_secret=bBbE-4mNO_kWWAnEeOL1CLTyuPhNLhHkTThArEckyrdLmRLn3GhnxjsKI2mEijCSlPjftxHod05dp-uGs6wA&username=user1&password=pass@123&scope=email%20profile'

NOTE:The authentication is done by using client_id and client_secret in the request body parameters (as mentioned in the preceding curl request), or send client credentials in basic authorization header (as mentioned in RFC 6749).

Request Parameter

Description

grant_type

Value should be “password”

client_id

Client ID of the registered client

client_secret

Client Secret of the registered client. It is optional for native application, for web application secret is mandatory.

username

The user login name

password

The user login password

The preceding table lists the minimal set of parameters. For the complete list of parameters see, Section 4.4.1, Request Parameters.

Application Receives Access Token

Sample token response

{
"access_token": "eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyODYwNzYyODAzMzEyNjI1MjUzMDQyMTk0NDMiLCJ0.....",
"token_type" : "bearer",
"expires_in" : 3599,
"scope" : "profile email"
}

Response Parameter

Description

token_type

The type of the token. Authorization server currently supports only Bearer type

access_token

Access token that can be used to invoke resource server APIs

expires_in

The remaining lifetime of the access token.

scope

Scopes requested.

NOTE:If validation errors are occurred, HTTP Status 400 returned with the JSON response contains “error” and “error_description”.

Try Now

To view how resource owner flow works, you can use the Access Manager OAuth samples. For more information about the samples, see Section 5.0, Developer Resources.

2.3.5 Client Credentials

Register the Client Application

If you have not registered the client application, register it and the grant type must be client credentials.

Using user portal page: Set Grants Required field as Client Credentials

Using REST API: Specify the value of grant_types parameter as client_credentials

After registering the client application you must save the client ID and the secret securely.

Get Access Token

To get access token make an HTTPS POST request to Token endpoint.

Sample Request

curl --request POST \
--url https://<idphost:port>/nidp/oauth/nam/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials&client_id=bb775b12-bbd4-423b-83d9-647aeb98608d&client_secret=bBbE-4mNO_kWWAnEeOL1CLTyuPhNLhHkTThArEckyrdLmRLn3GhnxjsKI2mEijCSlPjftxHod05dp-uGs6wA&scope=read%20write'

NOTE:The authentication is done by using client_id and client_secret in the request body parameters (as mentioned in the preceding curl request), or send client credentials in basic authorization header (as mentioned in RFC 6749).

Request Parameter

Description

grant_type

Set to "client_credentials'"

client_id

Client ID of the registered client

client_secret

Client Secret of the registered client. It is optional for native application and is mandatory for web applications.

scope

List of scopes the application requires. The scope read and write are custom scopes, For creating custom scopes, see Section 3.3, Creating Custom OAuth2 Scope.

Sample Response

{"access_token": "eyJraWQiOiI0MjgzNzQyNDYxDYwNzYyODAzMz ........","token_type" : "bearer","expires_in" : 3599,"scope" : "read write"}

Response Parameter

Description

token_type

Authorization server currently supports only "Bearer" token type

access_token

Access token that can be used to invoke resource server APIs

expires_in

The remaining lifetime of the access token.

scope

Scopes requested.

NOTE:If validation errors occurred, HTTP Status 400 is returned with additional fields "error" and "error_description" in the JSON response.

Try Now

To view how the client credentials flow works, you can use the Access Manager OAuth samples. For more information about the samples, see Section 5.0, Developer Resources.

2.3.6 Security Assertion Markup Language (SAML) 2.0 Bearer Grant

This flow requires trust relationship between Identity Providers and Service Provider. The Access Manager administrator needs to configure the assertion issuer details in Administration Console.

Register the Client Application

If you have not registered the client application, register it and the grant type must be SAML 2.0 assertion.

Using user portal page: Set Grants Required field as SAML 2.0 Assertion

Using REST API: Specify the value of grant_types parameter as saml2_assertion

After registering the client application you must save the client ID and the secret securely.

Exchange SAML 2.0 Assertion for Access Token

The SAML 2.0 assertions can be exchanged for access token. The consent page will not be displayed to the user for authorizing scopes. The access token will have only the scopes that are previously approved by the user.

To get access token send an HTTPS POST request to the token endpoint.

NOTE:The HTTP connections are denied, use HTTPS.

Sample CURL request

curl --request POST \
 --url https://<idphost:port>/nidp/oauth/nam/token \
 --header 'content-type: application/x-www-form-urlencoded' \
 --data 'grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&client_id=bb775b12-bbd4-423b-83d9-647aeb98608d&assertion=MPHnbWxv01….SY2&scope=email%20profile'

NOTE:The authentication is done by using client_id and client_secret in the request body parameters (as mentioned in the preceding curl request), or send client credentials in basic authorization header (as mentioned in RFC 6749).

Request Parameter

Description

grant_type

Value should be "urn:ietf:params:oauth:grant-type:saml2-bearer’"

client_id

Client ID of the registered client

assertion

A single base64url encoded SAML2.0 Assertion as value for this parameter.

client_secret

Optional. The client secret value

scope

List of scopes the application requires. Scope values should be space separated with %20 or +

Application Receives Access Token

Sample token response

{
"access_token": "eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyODYwNzYyODAzMzEyNjI1MjUzMDQyMTk0NDMiLCJ0.....",
"token_type" : "bearer",
"expires_in" : 3599,
"scope" : "profile email"
}

Response Parameter

Description

access_token

Access token that can be used to invoke resource server APIs

scope

Requested scopes that are pre-approved by the user.

expires_in

The remaining lifetime of the access token.

token_type

The type of the token. Authorization server currently supports only Bearer type

NOTE:If validation errors are occurred, HTTP Status 400 returned with the JSON response contains “error” and “error_description”.