Using OpenID Connect to Extend OAuth 2.0

An Identity Token is an integrity-secured, self-contained token (in JSON Web Token (JWT) format) that's defined in the OpenID Connect standard containing claims about the end user. The Identity Token is the primary extension that OpenID Connect makes to OAuth 2.0 to enable authentication in an identity domain.

The Identity Token JWT consists of three components, a header, a payload, and the digital signature. Following the JWT standard, these three sections are Base64URL encoded and separated by periods.

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows an IAM identity domain client application (registered as an OAuth 2 client with client ID and client secret) to verify the identity of the end user based on the authentication performed by an Authorization Server (AS), and to obtain basic profile information about the end user in an interoperable, REST-like manner. OpenID Connect allows clients of all types, including web-based, mobile, and JavaScript clients to request and receive information about authenticated sessions and end users. See OpenID Connect for more information.

Why do we validate tokens? When your web application checks credentials directly, it verifies that the username and password that are presented correspond to what you maintain. When using claims-based identity, you're outsourcing that job to an identity provider.

The responsibility shifts from verifying raw credentials to verifying that the requester went through your preferred identity provider and successfully authenticated. The identity provider represents successful authentication by issuing a token. Before you can use the information or rely on it as an assertion that the user has authenticated, you must validate it.

OpenID Discovery Document

The OpenID Connect 1.0 protocol is a simple identity layer on top of the OAuth 2.0 protocol that requires the use of multiple endpoints for authenticating users and for requesting resources that include user information, tokens, and public keys. To help with discovering what these endpoints are that you need to use, OpenID Connect allows you to use a discovery document, which is a JSON document found at a well-known location. This discovery document contains key/value pairs that provide details about the OpenID Connect provider's configuration, including the URIs of the authorization, token, userinfo, and public keys endpoints. You can retrieve the discovery document for the IAM identity domain OpenID Connect service from: https://<domainURL>/.well-known/openid-configuration.

The OpenID Connect UserInfo endpoint is used by an application to retrieve profile information about the identity that authenticated. Applications can use this endpoint to retrieve profile information, preferences, and other user-specific information.

The OpenID Connect profile consists of two components:

• Claims describing the user

• UserInfo endpoint providing a mechanism to retrieve these claims

  Note
  
  User claims can also be presented inside the ID Token to eliminate a callback during authentication time.

User Profile Claims

The UserInfo endpoint provides a set of claims based on the OAuth2 scopes presented in the authentication request. OpenID Connect defines five scope values that map to a specific set of default claims:

The client needs to present its credentials and an access token. The access token presented needs to contain the openid scope.

If a scope is omitted (for example, the email scope isn't used), the claim (email) won't be present in the returned claims.

Sample UserInfo Endpoint Request Example

After the client application has authenticated a user and has the access token, the client can then make a request to the UserInfo endpoint to retrieve the requested attributes about a user. The following example shows a request example.

   curl -i
   -H 'Content-Type: application/x-www-form-urlencoded'
   -H 'Authorization: Bearer eyJ4NXQjUzI1....rtApFw'-H 'Accept: */*'
   -H 'Content_Language: en-US'--request GET https://<domainURL>/oauth2/v1/userinfo

Response Example

A successful response returns an HTTP 200 OK response and the user's claims in JSON format:

{
"birthdate":"",
"email":"user@example.com",
"email_verified":false,
"family_name":"user",
"gender":"",
"given_name":"user",
"appRoles":[],
"name":"alice alice",
"preferred_username":"user@example.com",
"sub":"user@example.com",
"updated_at":1495136783,"website":""
}

Before the client application can trust the values returned from the UserInfo endpoint (for example, as a check for token substitution attack), the client must verify that the sub claim returned from the UserInfo endpoint request matches the subject from the ID Token.

Use the Authorization Code flow when you have clients that can securely maintain a client secret between themselves and the Authorization Server. The Authorization Code flow returns an Authorization Code to the client, which can then exchange the code for an ID Token and an Access Token directly.

This provides you with the benefit of not exposing any tokens to the user agent (such as a web browser) and possibly other malicious applications with access to the user agent. The Authorization Server can also authenticate the client before exchanging the Authorization Code for an Access Token. The Authorization Code flow works with both Confidential Clients and Public Clients.

Confidential Clients

Public Clients

Public clients don't have credentials, rather they have a client identifier. There are two steps in the Authorization Code flow. The requests involve a browser-based GET request, and then a back-channel POST request to get the Access Token.

1. Request the Authorization Code.

   Request Example

   GET https://<domainURL>/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=openid&nonce=<nonce-value>&state=1234

   Response Example

   Note
   
   These request and response examples are similar to the Confidential Client request and responses discussed previously.

   https://<domainURL>/?code=AQIDBAXv9lZQ....F9NCA=

2. Request the Token.

   Request Example

   Note
   
   This request is different from the Confidential Client request where the client id and client secret are specified in the Basic Authentication header. In the public client flow, there's no Basic Authentication header. The client id is specified as part of the request payload.

      curl -i
      -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'   
      --request POST https://<domainURL>/oauth2/v1/token 
      -d 'grant_type=authorization_code&code=<authz-code>&reidrect_uri=<client-redirect-uri>&client_id=<client-id>'

   Response Example

   {
   "access_token":"eyJ4NXQjUzI1???.xhtnbw",
   "token_type":"Bearer",
   "expires_in":27261,
   "id_token":"eyJ4NXQjUzI1???.._XLqUw"
   }
   

Use the Implicit flow when you have implemented a browser-based client using a scripting language such as JavaScript. The Access Token and the ID Token are returned directly to the Client, which may expose these tokens to the user and applications that have access to the user's user agent (such as a web browser).

The following response_type values are supported with the Implicit flow:

Obtaining an ID Token

Obtaining an Access Token

There are three steps in the Implicit flow to obtain an Access Token:

1. Request the Access Token.

   Request Example

   https://<domainURL>/oauth2/v1/authorize?client_id=<client_id>&response_type=token&redirect_uri=<client_redirect_uri>&scope=address+openid+profile

2. User logs in and gives consent (based on the requested scopes).

3. Response with Access Token

   Response Example

   Note
   
   All response parameters are added to the fragment component of the redirection URI.

   https://<domainURL>/#access_token=eyJ4NXQjUzI1...4WGvJQ&token_type=Bearer&expires_in=3600

Obtaining an ID Token and an Access Token

Use the Hybrid flow when you want to obtain tokens separately from both the front channel and the back channel. For example, you have a browser component like JavaScript and a backend server component such as Node.js. The browser component obtains the Authorization Code and the ID Token and can then personalize the UI content. The backend component obtains the Access Token to perform business API calls.

Clients need to support both browser-based requests and responses and programmatic/back-channel requests and responses to use the Hybrid flow. The Hybrid flow works with both Confidential Clients and Public Clients. The following response_type values are supported with the Hybrid flow:

Obtaining an ID Token

Obtaining an Access Token

There are four steps in the Hybrid flow to obtain the Authorization Code and the Access Token:

1. Request the Authorization Code and the Access Token.

   Request Example

   https://<domainURL>/oauth2/v1/authorize?client_id=<client_id>&response_type=code token&redirect_uri=<client_redirect_uri>&scope=http://<domainURL>/test

2. User logs in and gives consent (based on the requested scopes).

3. Response with ID Token and Authorization Code.

   Response Example

   Note
   
   All response parameters are added to the fragment component of the redirection URI.

   https://<domainURL>/#access_token=eyJ4NXQjUzI1....Pudw9A&code=AQIDBAU6d6Ae....F9NCA=&token_type=Bearer&expires_in=3600

4. The client application makes use of the Authorization Code and makes a back channel request to obtain a new Access Token.

   Request Example

      curl -i
     -H 'Authorization: Basic YjA3NTZkNDc5M2QwNDZjNjhjZWVmY2UxZjE4ZGUwMWM6NGYzZjJjN2EtZTBjZC00NzcyLWE5MTYtNjI3ZmExNzA2NWE5'
      -H 'Accept: */*''
      --request POST 'https://<domainURL>/oauth2/v1/token' -d 'grant_type=authorization_code&code=AQIDBAU6d6Ae...NCA%3D'

   Response Example

   {
   "access_token":"eyJ4NXQjUzI1....Tgs9LA",
   "token_type":"Bearer",
   "expires_in":3600
   }

Obtaining an ID Token and an Access Token

You can use OpenID Connect for browser-based logout requests.

There are two ways that you can request a logout using OpenID Connect: