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.
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 field as
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.
User Authenticates and Authorizes the Client Application
Access Manager Identity Server prompts the user to log in if not already logged in. After a successful login, the user is redirected to the consent screen to authorize the application. The consent screen can include permissions that require user authorization.
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. NOTE:The resource owner credential flow and client credential flow does not return 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. NOTE:The resource owner credential flow and client credential flow does not return id_token. |
|
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 Developer Resources.
2.3.2 Authorization Code with PKCE
Register the Client Application
If not registered, register the client application. The grant type must be authorization code.
Using user portal page: Set field as
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
The client sends the code challenge as part of the OAuth 2.0 Authorization request with the following additional parameters:
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. |
This table lists the minimal set of parameters. For the complete list, see Authorization Endpoint.
User Authenticates and Authorizes the Client Application
Access Manager Identity Server prompts the user to log in if not already logged in. After a successful login, the user is redirected to the consent screen to authorize the application. The consent screen can include permissions that require user authorization.
Client Receives the Authorization Code
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, Identity Server redirects 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 are 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. NOTE:The resource owner credential flow and client credential flow does not return 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 |
This 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. NOTE:The resource owner credential flow and client credential flow does not return id_token. |
|
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 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 field as
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.
User Authenticates and Authorizes Application
Access Manager Identity Server prompts the user to log in if not already logged in. After a successful login, the user is redirected to the consent screen to authorize the application. The consent screen can include permissions that require user authorization.
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 Developer Resources.
2.3.4 Resource Owner
Register the Client Application
If not registered, register the client application. The grant type must be resource owner credentials.
Using user portal page: Set field as
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).
-
The authentication contracts for Resource Owner Credential can be specified in the acr_values request parameter. The value of acr_values must be URI encoded and match exactly with the Access Manager Authentication contract URI. If no acr_values and no global RO authentication contracts are configured, only the Identity Server's default authentication contract is executed. For more information, see in Defining Global Settings.
|
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 field as
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 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 OIDC Front-Channel Logout
Access Manager supports OIDC front-channel logout and is implemented as per OIDC specification. This feature enables the following two forms of logout request:
-
Identity Provider initiated logout request: Allows a user to log out from all the client applications when the user logs out at Identity Server.
-
Relying Party (client application) initiated logout request: When a user initiates logout from one client application, the user can authorize to log out from Identify Server and other logged-in applications. For more information, see OIDC RP-Initiated Logout.
Consider a scenario where multiple employees share a single device. A user named Alice logs in to the User Portal, and then accesses five client applications. At the end of her shift, she needs to log out of these applications so that Bob, another employee, can use the same device. Instead of logging out from each application individually, she can log out from the user portal. This logs her out from all five applications.
Alternatively, when she initiates logout from one client application, the client application initiates logout from Identity Server. Identity Server then triggers logout for the remaining four applications. A consent message is displayed to verify if she wants to log out from all applications. When she authorizes, she is logged out of Identify Server and the active applications.
The consent message is displayed when the administrator enables the option in . By default, this option is enabled.
As a client application developer, you must register the logout_redirect_uri parameter for OIDC logout to enable this feature.
You must also have the details of the following endpoints. In the Administration Console Dashboard, click > > > > to view the details of the endpoints.
-
Logout EndPoint
-
OpenID Metadata EndPoint
To configure the front-channel logout option, see Step 5 of Registering OAuth Client Applications.
To enable logout from multiple browsers, you must enable the option under > > > > > .
You can also revoke the refresh tokens issued during the front-channel logout for the user session using the option. By default, this option is disabled. For more information, see Defining Global Settings.
The following diagram illustrates the workflow of the Identity Provider initiated logout request:
Figure 2-1 Identity Provider Initiated Logout Request
-
A user initiates logout at the Identity Server User portal.
-
The user agent sends the logout request to Identity Server.
-
Identity Server returns the logout response. The response contains iframes (logout URLs) for each relying party (RP1, RP2, and RP3). The relying party can be OAuth 2.0 or OIDC client application or SAML2 client application.
-
The browser agent generates responses and makes calls to each relying party’s logout URL.
The following diagram illustrates the workflow of the Relying Party (client application) initiated logout request:
Figure 2-2 Relying Party Initiated Logout Request
-
A user initiates logout at the client application.
-
The user agent sends the logout request to the client application.
-
The client application redirects the user’s browser agent for Identity Server logout.
-
The browser agent sends the logout request to Identity Server.
-
After the user grants consent, Identity Server terminates the user session, sends logout requests to other client applications (OAuth 2.0 or OIDC client application or SAML2 client application), and optionally redirects to the client application’s post-logout page.
Try Now
To view how the OIDC front-channel logout works, you can use the Access Manager OAuth sample scripts. For more information about the sample scripts, see Developer Resources.
2.3.7 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 not registered, register the client application and the grant type must be SAML 2.0 assertion.
Using user portal page: Set field as
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
SAML 2.0 assertions can be exchanged for access token. The consent page is 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”.