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:
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.
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.
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.
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.
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.
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. |
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.
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.
{"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.
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.
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.
Client sends the code challenge as part of the OAuth 2.0 Authorization request with 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. |
The preceding table lists the minimal set of parameters. For the complete list of parameters, see Section 4.3, Authorization Endpoint.
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.
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.
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. |
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.
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.
{"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.
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.
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.
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.
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.
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.
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.
The Authorization Endpoint sends an HTTP 302 redirect response with token and/or id_token as a fragment to the registered redirect_uri.
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.
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.
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.
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.
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.
{ "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”.
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.
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.
To get access token make an HTTPS POST request to Token endpoint.
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. |
{"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.
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.
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.
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.
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.
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 + |
{ "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”.