The application can request an authentication service from Access Manager by using one of the supported OAuth 2.0 authorization grant flows. Access Manager implements OpenID Connect 1.0 specification on top of these flows. Therefore, the application can get more information about authentication and it can verify the issued identity tokens.
The result of authentication exchange is an identity token called as ID token. This token is in the JSON Web Token (JWT) format. This token is signed by public signing certificate of Identity Server. The client application needs to verify the signature of the token and token is issued by the trusted Identity Server.
The authentication service assures the application that the user has an active session at Identity Server with requested or default assurance level. The flows requiring active user session involves a browser redirect, therefore the authorization grant flows in this section talks about authorization Code Grant flow and Implicit Grant flow. The authentication service can use advanced authentication methods configured in Identity Server. This does not require the application to know the password of the user. If your application does not depend on a browser interface or handles username and password directly, see Resource Owner Credential Grant.
You can use any one of the following flows to get an identity token:
Authorization code grant flow
Implicit Flow
Hybrid Flow
The authorization code grant flow is a two-step process.
Get a short lived authorization code from Identity Server.
Exchange this authorization code with ID token.
The application can also request for an access token for authorization if the application makes REST API calls to resource servers.
The application can also specify minimum assurance level for the authentication method from Identity Server by using the following request parameter.
Identity Server ensures that the user is authenticated with the requested level of authentication before sending the identity token.
An identity token is a signed JSON Web Token (JWT). Signing is optional, but recommended. The token is signed when the client is configured with ID Token Signing Algorithm during the client registration process.
The application verifies the returned identity token as mentioned in Validating Tokens.
A client can get an authorization code in by redirecting the browser to the authorization endpoint with the required query string values. See Request Parameters.
The response is a short life-time authorization code and must used only once. You can use this code to exchange identity tokens from Identity Server through the token endpoint only once by sending the necessary request parameter. See Exchanging the Authorization Code with Identity Tokens.
Multiple attempts of exchanging code for token revokes tokens that are issued earlier. The authorization code is sent through a browser redirect to a registered redirect_uri. The client should handle this request to the redirect_uri. This involves exchanging the code with an access token.
To get an authorization code, the client should invoke a request to Identity Server's authorization endpoint with the following request query string parameters:
|
Parameter |
Required/Optional |
Value |
Description |
|---|---|---|---|
|
client_id |
Required |
Client application ID, which is obtained at the time of the client application registration process. |
|
|
response_type |
Required |
code |
code |
|
redirect_uri |
Optional |
If provided, the value of this must exactly match to one of the registered URIs during the application registration process. If not provided, the browser is redirected to any of the registered redirect URIs registered during application registration. |
|
|
scope |
Required |
OpenID |
The list of scopes the application requires. It should contain OpenID". You can get all "scopes_supported" at the authorization server's OpenID Metadata Endpoint. Scope values must be space separated %20 or +. |
|
resourceServer |
Optional |
Specify the registered resource server name. If this parameter is available, the authorization server uses the respective configured method to encrypt the access token. |
|
|
state |
Recommended |
An opaque value used by a client to maintain state between request and callback. The authorization server includes this value when redirecting a user-agent back to a client. This parameter is used to prevent cross- site forgery requests. |
|
|
prompt |
Optional |
none login consent |
none: No user interface is shown to a user if the user is not already authenticated. If not authenticated, an error message in one of "login_required", "interaction_required", or other is sent to the client application. This is useful if a client wants to detect whether the user has an existing session with Identity Server and has necessary consents. login: Identity Server asks for re-authentication. consent: Identity Server asks for consent even if the consent is already given. |
|
max_age |
Optional |
300 |
Maximum authentication age at Identity Server in seconds. If a user does not log in within this time, the user is re-prompted for authentication |
|
acr_values |
Optional |
/name/password/uri |
If a client request contains acr_values, Identity Server maps the value to configured contracts in Identity Server and prompts the user with the contract if the user is not authenticated with the contract. The contract is not sent in ID token. |
|
device_id |
Optional |
Specify the device ID that token to be associated with device. |
Identity Server responds with a HTTP 302 redirect message to requested redirect_uri in an authorization request. If the request does not contain the redirect_uri param, Identity Server redirects to one of the registered redirect_uri. The redirect response contains the following parameters:
|
Parameter |
Description |
|---|---|
|
code |
An opaque binary token. Variable length field. Application should not assume the size of the code and allocate sufficient space for reading the code. |
|
state |
Contains the state parameter sent in the authentication request above |
A sample request with whitespace for readability:
HTTP/1.1 GET /nidp/oauth/nam/authz? &response_type=code &client_id=bb775b12-bbd4-423b-83d9-647aeb98608d &redirect_uri=https://www.oauthapp.com/oauth.php &scope=email &nonce=ab8932b6 &state=AB32623HS User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36 Host: www.idp.com:8443 Accept: / Cookie: JSESSIONID=188BAEB80B063C852D2CC82FDBD15A43 Response HTTP/1.1 302 Found Cache-Control: no-cache, no-store, no-transform Location: https://www.oauthapp.com/oauth.php? code=/wEBAAY..........Ws1gQ~~ &scope=email Content-Length: 0 Date: Tue, 03 Mar 2015 18:12:55 GMT
The client, listening for the authorization code in the registered redirect_uri, can use the requests explained in next section to exchange the authorization code with an access token. The authorization code is allowed for exchange only once. The request should be sent to the token endpoint.
The response is sent in the JSON format and contains both access_token and id_token. Access tokens are used for authorization and typically sent to an API server. The client when invoking any other API service has to include this access token. The API server validates this access token and authorize the incoming API requests based on the scopes embedded in the access token.
The ID token contains the authentication information, such as the issuer of the token, its validity, and when the user was authenticated. The client needs to verify the signature of the ID token if available and check the issuer.
Specify the following parameters in the token request:
|
Parameter |
Required/Optional |
Description |
|---|---|---|
|
resourceServer |
Optional |
Registered resource server name. If this parameter is available, the authorization server uses the respective configured way to encrypt the access token. |
|
grant_type |
Required |
authorization_code |
|
client_id |
Required |
Client ID of the registered client. |
|
client_secret |
Optional |
Client secret of the registered client. It is optional for a native application and mandatory for a web application. |
|
code |
Required |
Code received in the authorization code flow. |
|
redirect_uri |
Required |
This must be same as the one sent during the authorization code request. |
|
device_id |
Optional |
Specify the device ID that token to be associated with device. |
A successful request contains a JSON object with the following values:
|
Parameter |
Required/Optional |
Description |
|---|---|---|
|
token_type |
Required |
The type of the token. The authorization server supports only the Bearer type. |
|
access_token |
Required |
An access token that can be used to invoke resource server APIs. |
|
id_token |
Optional if scope contains "OpenID" |
When invoking authorization code request, if the client has sent OpenID, this response object contains an ID token. |
|
scope |
Optional |
The list of scopes that a user has authorized. This can contain all scopes the client requested. |
|
state |
Optional |
if the state parameter was available in the client authorization request, the same state value is sent in the response. |
NOTE:Ensure that you do not use the Expect: 100-Continue header in the request when using a multi-node Identity Server cluster setup. If the request contains this header, you may experience HTTP 400 Bad Request.
If you are using CURL, use "-H 'Expect:'" or do not include IDP cookies.
POST /nidp/oauth/nam/token HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/41.0.2228.0 Safari/537.36
Host: www.idp.com:8443
Accept: /
Content-Length: 695
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=b017c96c-b16a-4d80-a5fa-68f5050abc58
&client_secret=ZDDwbuuWPdV_e5quAf7f0Jkg_iJJ7g
&redirect_uri=https://www.client.com/oauth_callback.php
&code=/wEBAAk...................................
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 916
Date: Thu, 19 Mar 2015 14:14:57 GMT
Connection: close
{
"access_token":"/wEBAAQEACA......",
"token_type":"bearer", "expires_in":179, "refresh_token":"/wEBAAQEACA9lN8bgv..........",
"scope":"email"
}
Get an access token and ID token by sending an HTTPS GET or POST request with the appropriate URI parameters to the authorization endpoint base URI. The ID token issued only if the scope is having OpenID param value. The ID token can be signed and encrypted based on the client's registration. To access any of the user's attribute or getting permissions to access user's resource pages, you can include the request in the scope parameter.
For example, if you want a user's email address and profile, set the scope parameter accordingly. If any of this scope requires approval from the user, the consent screen includes a request to provide the user's email address and profile to your application.
Sample implicit request/response: https://example.netiq.com/nidp/oauth/nam/authz?response_type=token+id_token&client_id=4e4ae330-1215-4fc8-9aa7-79df8325451c&redirect_uri=https://client.example.com/callback&scope=email+OpenID&state=s1234&nonce=n123
In this case, the authorization server validates all request parameters and checks whether the user is authenticated. If the user is not authenticated, then it sends the login page to user. After the user is authenticated, it takes the consent from the user for the requested scopes and sends the response to the client.
The authorization server sends the following response for the request:
https://client.example.com/callback#token_type=bearer&access_token=/wEBAAUFACAjDfPtn d/zlOWPpN/kV1Jtt3nxCPtzHyUH~&expires_in=3600&id_token=eyJhbGciOiJSUzI1NiJ9.eyJp c3MiOiJo&scope=email&state=s1234
The token request needs to include the following query parameters and the request needs to be sent to the authorization endpoint:
|
Parameter |
Required/Optional |
Description |
|---|---|---|
|
response_type |
Required |
The possible values are token, id_token, and token id_token. The id_token is issued only if the scope contains the OpenID value. If the value is sent as token, then the authorization server issues only an access token to the client. If the value is id_token, then authorization server issues only id_token in the response. If the value is token id_token, then authorization server issues both access token and ID token in the response. |
|
resourceServer |
Optional |
Specify the registered resource server’s name. If this parameter is available, the authorization server uses the respective configured way to encrypt the access token. |
|
client_id |
Required |
Client application ID that is obtained at the time of the client application registration process. |
|
redirect_uri |
Optional |
If provided, the value of this parameter must exactly match to one of URIs of the registered application. |
|
scope |
Optional |
Scopes supported by the authorization server. You can get scopes_supported at authorization server's OpenID Metadata endpoint. For the ID token, OpenID needs to be available in the scope. Specify multiple scope values separated with space %20. |
|
state |
Required |
An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when the response is sent to the client. The parameter prevents cross-site forgery requests. |
|
nonce |
Required |
String value used to associate a client session with an ID token, and to mitigate replay attacks. |
|
prompt |
Optional |
A space delimited, case-sensitive list of ASCII string values that specifies whether the authorization server prompts the end user for re-authentication and consent. The following are defined values:
|
|
max_age |
Optional |
Maximum authentication age. Specifies the allowable elapsed time in seconds since the last time the user was authenticated by the OP. |
|
device_id |
Optional |
The device ID of the device with which the token will be associated. |
The authorization endpoint sends an HTTP 302 Redirect response with the following http fragment values in the Location header. The browser redirects the request to the returned Location header without exposing the fragment values. The Location header is the redirect_uri parameter sent in the request. Only the browser can read the fragment values and these are never sent to redirect_uri.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
|
token |
Required |
The type of the token. The authorization server supports only bearer. |
|
Access_token |
Based on the response type value |
If the response type value is token or token id_token, the authorization server sends an access token. |
|
id_token |
Based on the response type value |
If the response type value is id_token or token id_token, the authorization server sends an ID token. |
|
scope |
Optional |
The user given consent scope names. |
|
state |
Optional |
If the state parameter was available in the client authorization request, the same state value is sent in the response. |
Get a combination of tokens or code, such as access token, ID token, or authorization code, based on the response_type parameter by sending an HTTPS GET or POST request with the appropriate URI parameters to the authorization endpoint base URI. The hybrid flow works and the ID token is issued only if the scope contains the OpenID param value. An ID token can be signed and encrypted based on the client's registration. To access any of the user's attributes or getting permissions to access the user's resource pages, you can include the request in the scope parameter.
For example, if you want a user's email address and profile, set the scope parameter accordingly. If any of this scopes requires approval from the user, the consent screen includes a request to provide the user's email address and profile to your application.
Response types that are allowed in hybrid flows, in any combination, are as follows:
|
response_type |
Token Generated |
|---|---|
|
code id_token |
Authorization code and ID token |
|
code token |
Authorization code and access token |
|
code id_token token |
Authorization code, ID token, and access token |
Sample hybrid flow request/response: https://example.netiq.com/nidp/oauth/nam/authz?
response_type=code id_token&client_id=4e4ae330-1215-4fc8-9aa7- 79df8325451c&redirect_uri=https://client.example.com/callback&scope=email+openid&state=s1234&nonce=n123
In this case, the authorization server validates all request parameters and checks whether the user is authenticated. If the user is not authenticated, it sends the login page to user. After the user is authenticated, it takes the consent from the user for the requested scopes and sends the response to the client.
The authorization server sends the following response for the this request:
https://client.example.com/callback#code=ey2hgwshg223jdsw&id_token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJo&scope=email&state=s1234
The token request should have the following query parameters and the request should be sent to the authorization endpoint:
|
Parameter |
Required/Optional |
Description |
|---|---|---|
|
response_type |
Required |
The possible values are code token, code token id_token, code id_token, and other combinations of the three values. It should be space separated. |
|
resourceServer |
Optional |
Specify the name of the registered resource server. If this parameter is available, the authorization server uses the respective configured way to encrypt the access token. |
|
client_id |
Required |
The client application ID that is obtained at the time of the client application registration process. |
|
redirect_uri |
Required |
The value of this must parameter must exactly match with one of URIs of the registered application. |
|
scope |
Required |
Scopes supported by the authorization server. Get scopes_supported at authorization server's OpenID Metadata Endpoint. It must contain the openid scope value. You can add multiple space separated scope values. |
|
state |
Optional |
An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when the response is sent to the client. The parameter prevents cross-site forgery requests. |
|
nonce |
Required |
A string value used to associate a client session with an ID Token, and to mitigate replay attacks. |
|
prompt |
Optional |
A space delimited, case-sensitive list of ASCII string values that specifies whether the authorization server prompts the end user for re-authentication and consent. The following are defined values:
|
|
max_age |
Optional |
Maximum authentication age. Specify the allowable elapsed time in seconds since the last time the user was authenticated by the OP. |
|
device_id |
Optional |
Specify the device ID of the device that token has to be associated with. |
The authorization endpoint sends an HTTP 302 Redirect response with the following http fragment values in the Location header. The browser redirects the request to the returned Location header without exposing the fragment values. The Location header is the redirect_uri parameter sent in the request. The fragment values can only be read by the browser and never sent to redirect_uri.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
|
token_type |
Based on response type value |
The type of the token. The authorization server supports only bearer. |
|
access_token |
Based on response type value |
If the response type value is code token, code id_token token, or its combination, the authorization server sends an access token. |
|
id_token |
Based on response type value |
If the response type value is code id_token, code id_token token, or its combination, the authorization server sends an ID token. |
|
scope |
Optional |
The user given consent scope names. |
|
state |
Optional |
if the state parameter was available in the client authorization request, the same state value is sent in the response. |
|
expires_in |
Based on response type value |
Expiration time of the access token in seconds since the response was generated. |
|
code |
Required |
Authorization code |