Diagrams of All The OpenID Connect Flows

Introduction

OpenID Connect has been developed by extending OAuth 2.0.

OAuth 2.0 is a specification as to how to issue access tokens. It is defined in RFC 6749 (The OAuth 2.0 Authorization Framework). (c.f. The Simplest Guide To OAuth 2.0)

OpenID Connect is a specification as to how to issue ID tokens. The main part is defined in OpenID Connect Core 1.0.

RFC 6749 includes the definition of a Web API called “authorization endpoint”. The API requires as a mandatory request parameter. OpenID Connect has defined flows to issue ID tokens by extending the specification of the request parameter.

In RFC 6749, the value of is either or . OpenID Connect has added a new value, , and allowed any combination of , and . A special value, , has been added, too. As a result, now can take any one of the following values.

Note that a request for an ID token has to include in the request parameter. Especially, if is not included in , the case of is regarded as the original authorization code flow defined in RFC 6749 and an ID token won't be issued. The same is true of the case of , too.

1. response_type=code

When the value of is , but if is not included in the request parameter, the request is just an authorization code flow which is defined in RFC 6749. On the other hand, if is included in the request parameter, an ID token is issued from the token endpoint in addition to an access token.

if is included

if is not included (authorization code flow defined in RFC 6749)

2. response_type=token

When the value of is , the request is an implicit flow defined in RFC 6749. Even if is included in the request parameter, an ID token is not issued. This flow uses the authorization endpoint but does not use the token endpoint.

At the end of 3. Authentication, OpenID Connect Core 1.0 explicitly states that OpenID Connect does not use as follows:

NOTE: While OAuth 2.0 also defines the Response Type value for the Implicit Flow, OpenID Connect does not use this Response Type, since no ID Token would be returned.

3. response_type=id_token

When the value of is , an ID token is issued from the authorization endpoint. This flow does not use the token endpoint.

4. response_type=id_token token

When the value of is , an ID token and an access token are issued from the authorization endpoint. This flow does not use the token endpoint.

When an access token is issued together with an ID token from the authorization endpoint, the hash value of the access token calculated in a certain way has to be embedded in the ID token. So, be careful when you implement this flow. 3.2.2.10 ID Token in OpenID Connect Core 1.0 says as follows:

at_hash

Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the value, where the hash algorithm used is the hash algorithm used in the Header Parameter of the ID Token's JOSE Header. For instance, if the is , hash the value with SHA-256, then take the left-most 128 bits and base64url encode them. The value is a case sensitive string.

If the ID Token is issued from the Authorization Endpoint with an value, which is the case for the value , this is REQUIRED; it MAY NOT be used when no Access Token is issued, which is the case for the value .

5. response_type=code id_token

When the value of is , an authorization code and an ID token are issued from the authorization endpoint, and an access token and an ID token are issued from the token endpoint.

Both the authorization endpoint and the token endpoint issue an ID token, but the contents of the ID tokens are not always the same. Regarding this, 3.3.3.6 ID Token in OpenID Connect Core 1.0 says as follows:

If an ID Token is returned from both the Authorization Endpoint and from the Token Endpoint, which is the case for the values and , the and Claim Values MUST be identical in both ID Tokens. All Claims about the Authentication event present in either SHOULD be present in both. If either ID Token contains Claims about the End-User, any that are present in both SHOULD have the same values in both. Note that the OP MAY choose to return fewer Claims about the End-User from the Authorization Endpoint, for instance, for privacy reasons. The and Claims MAY be omitted from the ID Token returned from the Token Endpoint even when these Claims are present in the ID Token returned from the Authorization Endpoint, because the ID Token and Access Token values returned from the Token Endpoint are already cryptographically bound together by the TLS encryption performed by the Token Endpoint.

When an authorization code is issued together with an ID token from the authorization endpoint, the hash value of the authorization code calculated in a certain way has to be embedded in the ID token. So, be careful when you implement this flow. 3.3.2.11. ID Token in OpenID Connect Core 1.0 says as follows:

c_hash

Code hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the value, where the hash algorithm used is the hash algorithm used in the Header Parameter of the ID Token's JOSE Header. For instance, if the is , hash the value with SHA-512, then take the left-most 256 bits and base64url encode them. The value is a case sensitive string.

If the ID Token is issued from the Authorization Endpoint with a , which is the case for the values and , this is REQUIRED; otherwise, its inclusion is OPTIONAL.

6. response_type=code token

When the value of is , an authorization code and an access token are issued from the authorization endpoint, and an access token is issued from the token endpoint. In addition, if is included in the request parameter, an ID token is issued from the token endpoint, too.

if is included

if is not included

Both the authorization endpoint and the token endpoint issue an access token, but the contents of the access tokens are not always the same. Regarding this, 3.3.3.8. Access Token in OpenID Connect Core 1.0 says as follows:

If an Access Token is returned from both the Authorization Endpoint and from the Token Endpoint, which is the case for the values and , their values MAY be the same or they MAY be different. Note that different Access Tokens might be returned be due to the different security characteristics of the two endpoints and the lifetimes and the access to resources granted by them might also be different.

7. response_type=code id_token token

When the value of is , an authorization code, an access token and an ID token are issued from the authorization endpoint, and an access token and an ID token are issued from the token endpoint.

Both the authorization endpoint and the token endpoint issue an access token, but the contents of the access tokens are not always the same, likewise “6. response_type=code token”. As for the specification, please refer to 3.3.3.8. Access Token in OpenID Connect Core 1.0.

When an ID token is issued from the authorization endpoint, the hash value of the access token has to be embedded in the ID token if an access token is also issued, and the hash value of the authorization code has to be embedded in the ID token if an authorization code is also issued, likewise “4. response_type=id_token token” and “5. response_type=code id_token”. As for the specification, please refer to 3.3.2.11. ID Token in OpenID Connect Core 1.0.

8. response_type=none

When the value of is , nothing is issued from the authorization endpoint. This flow does not use the token endpoint.

The definition of is in 4. None Response Type in OAuth 2.0 Multiple Response Type Encoding Practices.

9. Support

Software claiming OpenID Connect support does not always support all the flows described above. Even among the implementations that have OpenID Certification, about the half don't cover Hybrid OP Profile (= don't support hybrid flows).

Financial API Working Group of OpenID Foundation is discussing and defining Financial API (FAPI). When a client application complying with the FAPI specification makes a request for an access token for write operations, the value of of the request must be either or . 5.2.2. Authorization Server in Financial Services - Financial API - Part 2: Read and Write API Security Profile says as follows:

shall require the values or ;

That is, if you are planning to comply with Financial API, you have to use an authorization server which supports hybrid flows. Be careful when you select an authorization server because there exist implementations which support only but claim they support OpenID Connect.

Finally

If you feel the flows are too complicated to implement, please consider Authlete. Read New Architecture of OAuth 2.0 and OpenID Connect implementation, and you will love the architecture of Authlete 😉

Co-founder and representative director of Authlete, Inc., working as a software engineer since 1997. https://www.authlete.com/