3.3 Authentication

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.

Getting Identity Tokens

You can use any one of the following flows to get an identity token:

  • Authorization code grant flow

  • Implicit Flow

  • Hybrid Flow

3.3.1 Authorization Code Grant Flow

The authorization code grant flow is a two-step process.

  1. Get a short lived authorization code from Identity Server.

  2. 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.

Getting an Authorization Code

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.

Request Parameters

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.

Response Values

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

Sample Request and Response

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

Exchanging the Authorization Code with Identity Tokens

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.

Request Parameters

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.

Response Values

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.

Sample Request and Response
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"
}

3.3.2 Implicit Grant

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
Token Request URI Parameters

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:

  • none: The authorization server does not display any authentication or consent user interface pages. An error is returned if an end user is not authenticated or the client does not have preconfigured consent for the requested claims, or does not fulfill other conditions for processing the request.

  • Login: The authorization server prompts the end user for re-authentication. If it cannot re-authenticate the end user, it returns an error to the client.

  • Consent: The authorization server prompts the end user for consent before returning information to the client. If it cannot obtain consent, it returns an error, typically consent_required.

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.

Response Values

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.

3.3.3 Hybrid Flow

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
Token Request URI Parameters

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:

  • none: The authorization server must not display any authentication or consent user interface pages. An error is returned if an end user is not authenticated or the client does not have preconfigured consent for the requested claims or does not fulfill other conditions for processing the request.

  • login: The authorization server should prompt the end user for re-authentication. If it cannot re-authenticate the end user, it must return an error to the client.

  • consent: The authorization server should prompt the end user for consent before returning the information to the client. If it cannot obtain consent, it must return an error, typically consent_required.

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.

Response Values

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