Understanding OpenIDConnect

A Brief Introduction

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

OpenID Connect is build on top of OAuth 2.0. OAuth 2.0 is mainly used for Authorization where OpenID Connect is used for authentication. OpenID Connect is an identity layer on top of the OAuth 2.0 protocol to make OAuth suitable for the authentication use cases. We will have a basic understanding about OAuth 2.0 protocol before going into OpenID Connect.

Fig 1 — Basic OAuth Flow

The participants of basic OAuth access token flow are:

Resource Owner: Owns some resource in resource server.

Client Application: Access the resource on the behalf of resource owner.

Authentication Server: Authenticate the resource owner based on credentials (eg: Facebook, Google)

Resource Server: Stores the resources.

When the resource owner wants the client application to access the resource on his/her behalf, the client application will redirect the user to the Authorization Server. After authenticating the resource owner, the authorization server will send the access token to the client application. Then, the client application will request the resource server with the access token. The resource owner will validate the access token with the authorization server. Finally, the application can access the resources 😀!

Please refer OAuth 2.0 to understand the more about OAuth 2.0.

OpenID Connect

In the above flow, the Authorization server returns the access token to the client application. Does it provide any client related information? No, the client application cannot get any user related information. How can we solve this? Then, the OpenID Connect come to play. It is an identity layer on top of OAuth 2.0 which provides client related information.

Fig 2 — OpenID Connect Flow

How does this achieved? This is achieved by providing openid as scope when sending the authorization request to the Authorization Server. If openid is not provided in scope, but response_type=code is given, an ID token won't be issued. The application gain authentication information via IDToken and other additional claims of the user by OpenID Connect.

OIDC uses JSON web tokens (JWTs), which you can obtain using flows conforming to the OAuth 2.0 specifications. This IDToken is an encoded token with three parts: header, payload, and signature. The client will decode the token to get the information.

Sample decoded payload is given below:

{
  "at_hash": "JrZY9MtYVEIIJUx-DDBmww",
  "sub": "admin",
  "aud": [
    "nczbg5m5xxt6tP4UMZwB6PtQoQoa"
  ],
  "azp": "nczbg5m5xxt6tP4UMZwB6PtQoQoa",
  "iss": "https://localhost:9443/oauth2/token",
  "exp": 1510831010,
  "nonce": "asd",
  "iat": 1510831007
}

Claims

The fields in the payload is known as claim. Some of the basic claims are:

• iss token issuer.
• sub subject identifier.
• aud audience(s) that this ID Token is intended for.
• exp token expiration time.
• iat token issued time.

Are they only claims? No, the claims are not limited to these. If additional information are needed, OpenID Connect scopes can be specified to inform the Authorization server to provide required information.

We can obtain client information with the help of three common widely used OpenID flows.

Authorization Code Flow

Fig 3 — Authorization Code Flow

1. The client specify the authentication request (response_type as code and scope as openid) and send it to Authorization server.
2. Authorization server will validate the request and authenticate the user.
3. If the authentication is success, the Authorization server will respond with a Authorization code.
4. Client will send the authorization code to the token endpoint and request IDToken, access token and optionally refresh token.
5. The Authorization server will validate the code and send back the IDToken along with the access Token.

The IDToken contains the user information.

Implicit Flow

response_type=id_token

Fig 4 — Implicit Flow with “id_token” as response type

response_type=code id_token token

Fig 5 — Implicit Flow with “id_token token” as response type

In this flow, the access token will be assigned from authorization endpoint. Therefore, authorization code will not be generated.

1. Client sends the authorization request to the Authorization Server.
2. Authorization server will authenticate the user.
3. If the authentication is success, the authorization server will send IDToken and access Token based on the response type.

Only IDToken will be send if the response type is id_token. But IDToken will be send along with the access token if the response type is id_token token.

Hybrid Flow

This is a combination of both Authorization code and implicit flows.

response_type=code id_token

Fig 6 — Hybrid flow with “code id_token” as response type

In this flow, authorization code will be send along with IDToken from authorization endpoint. And an access token and IDToken will be send from token endpoint. Are these both IDTokens are same?. Not exactly…

Both the authorization endpoint and the token endpoint issue an ID token, but the contents of the ID tokens are not always the same.

response_type=code token

Fig 7 — Hybrid flow with “code token” as response type

In this flow, authorization code will be send along with an access token from the authorization endpoint. Access token along with IDToken (if openid is included in the scope) will be send from token endpoint.

response_type=code id_token token

Fig 8 — Hybrid flow with “code id_token token” as response type

In this flow, an authorization code, an access token and an ID token will be send from the authorization endpoint. And an access token and an ID token will be send from the token endpoint.

Happy Learning !!!

References

1. https://docs.wso2.com/display/IS530/OpenID+Connect
2. https://is.docs.wso2.com/en/latest/learn/oauth2-openid-connect-overview/