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 Section 3.8.1, 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.

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 Section 3.5, Validating Tokens.

Getting an Authorization Code

The 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 be used only once. This code can be used 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 the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used to prevent cross- site forgery requests.
prompt	Optional	none login consent	none: No user interface will be shown to the user if the user is not already authenticated. If not authenticated, an error message in one of "login_required", "interaction_required", or other will be sent to the client application. This is useful if the client wants to detect whether the user has an existing session with Identity Server and has necessary consents. login: Identity Server will prompt for re-authentication. consent: Identity Server will prompt for consent even if consent is already given.
max_age	Optional	300	Maximum authentication age at Identity Server in seconds. If the user has not logged in within this elapsed time, the user will be re-prompted for authentication
acr_values	Optional	/name/password/uri	If client request contains acr_values parameter, Identity Server maps the value to configured contracts in Identity Server and prompts the user with the contract if the user is not already authenticated with the contract. The contract is not sent in ID token in this release.
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 the requested redirect_uri in the 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

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