In a world increasingly connected by APIs, the role of identity has never been more important. There are different ways that API providers can grant access to data for applications on behalf of users, and one way that has become almost ubiquitous is OAuth 2.0. For example, when you are asked to share your data with a mobile app that allows you to in-game tweet your best score on Wordscapes, OAuth 2.0 is powering the integration that lets this happen.

However, OAuth 2.0 has its limitations, most importantly in proving the fact that the human being actually authenticated when they permitted access to their data. This fault is something application developers and API providers can tolerate for sending a tweet. However, it’s not so good if the API is sending a payment on behalf of the user, or sharing sensitive data like health or insurance records.

This is where OpenID Connect steps in. In this post, we go back to basics and take a look at what OpenID Connect is designed to solve and how it accomplishes it.

What Does OpenID Connect Solve?

It’s important to put OpenID Connect in the right context by looking at what came before. The core OpenID Connect specification is described as “a simple identity layer on top of the OAuth 2.0 protocol”. As we said in the introduction, safely allowing an application to access your data via APIs without giving up your credentials is part of what OAuth 2.0 is all about. Why is OpenID Connect needed as well?

The reason is OAuth 2.0 only provides authorization; OpenID Connect is required to prove the identity of the requesting party. Consider the Wordscapes example. Wordscapes accesses the Twitter API on your behalf using an Access Token dedicated to you; Wordscapes only knows it was authorized to access your data. It knows nothing about the authentication event that took place and Twitter’s version of what it considers to be you. It cannot:

• Tell it was definitely you that authenticated.
• Know how you authenticated.
• Glean any useful information that may help provide a better experience to you as a customer.

Providing information like this, including the authentication event itself and who the End User was, is precisely what OpenID Connect achieves. It allows the application — the Relying Party — to access cryptographically-signed proofs of identity. The benefits include:

• It assures the Client application that authentication actually took place through the use of an ID Token, which is a means of carrying identity attributes using a signed-JSON Web Token (JWS) that can be verified using public-key cryptography. This ensures that delegation of access by an End User is backed by a cryptographically-verifiable assertion.
• It also allows the Client application to know “something” about the End User identity, which is essential for the federation of user identity. Federation is handy for Client applications, in that it effectively allows them to outsource many aspects of the user identity to a provider it trusts without sacrificing security and access.
• Having some proof-of-authentication can help application developers create much more seamless authentication experiences. They can (where supported by an identity provider) use an existing, valid ID Token to prove the identity of the End User to the Authorization Server. In such scenarios, the Authorization Server may not prompt the user to authenticate, resulting in a much smoother experience when using an application that takes advantage of this feature.

The ID Token is the defining characteristic of the OpenID Connect core protocol. Its primary role is to convey information about the identity of the user that was authenticated. This is manifested in a series of Claims encoded in the token, examples of which include:

• The Subject: A unique identifier that represents the End User as the identity provider knows them.
• The Issuer and Audience: The identity provider that issued the token and which Client application it was intended for.
• Issued at and expiry times.

This list is not exhaustive, and other Standard Claims can be included with additional scope to include custom Claims where required.

The ID Token can, therefore, carry significant metadata about the End User. This can provide greater levels of assurance that the End User is who they say they are. It also delivers reference points for the Client application when they incorporate one of the flows provided by the identity provider.

Flows

The flows offered in OpenID Connect are how a Client application interacts with the identity provider to ensure the End User is authenticated and the Client application is authorized to act on the End User’s behalf. The flows, generally speaking, reflect what are called Authorization Grants in the underlying OAuth 2.0 RFC and are:

• Authorization Code.
• Implicit.
• Hybrid.

An application developer will incorporate a given flow when they create their software, using the response_type parameter to indicate which flow is required. The possible combinations are shown in the standard and in the table below:

Each flow has it’s pros and cons, which are important to understand (especially where a provider offers more than one).

Authorization Code

There are no prizes for guessing that Authorization Code Flow largely maps onto the Authorization Code Grant from OAuth 2.0, where the End User is redirected to authenticate themselves. Given its similarities to OAuth 2.0, Authorization Code represents the most straightforward route to upgrading to OpenID Connect. The flow remains largely consistent with the underlying protocol:

• The Client application sends the End User (their customer) to the identity provider’s Authorization Server, setting the response_type parameter to code.
• The End User authenticates themselves and authorizes access to the Client application.
• The Authorization Server provides an Authorization Code as proof-of-authorization.
• The Client application cashes in the Authorization Code for an Access Token that allows them to call one or more APIs on behalf of the End User.

There are, of course, several differences between OAuth and OpenID Connect in this context. Yet, the most important difference is that the Client application obtains an ID Token when they visit the Token endpoint. This may seem counterintuitive given that the response_type does not contain the id_token value, but the reason for this will become more obvious as we discuss the other flows.

Implicit

Like Authorization Code Flow, Implicit overlays the Implicit Authorization Grant from OAuth 2.0, with the same use cases and security considerations, namely:

• The flow is intended for use in the browser.
• The Client application is not authenticated and relies on the End User authenticating themselves successfully.
• All tokens are returned from the Authorization Endpoint, with the Token Endpoint being unused.
• The ID Token and Access Token are exposed to the browser, making them more susceptible to stealing through man-in-the-browser style attacks.

Implicit flow has its place and still provides the benefits of proof-of-authentication. Implicit flow may have practical applications within “walled garden” deployments, such as within corporate infrastructure with a bound set of internal credentials. However, even here, serious consideration must be given before implementing it.

Hybrid

The final OpenID Connect flow is Hybrid flow. Hybrid flow is a meld of Authorization Code and Implicit flow. Some tokens are returned by the Authorization Endpoint, while others are returned from the Token Endpoint.

The returning of tokens at the Authorization Endpoint is not just for fun, however. It’s intended as a way of adding additional protection to the Client application where it’s needed — most notably in protecting the leg of the trip from the Authorization Endpoint to Token Endpoint from attack.

As an example, if a Client application requests response_type of code id_token (the underlying definition can be found here) it is expecting two specific attributes to be returned from the Authorization Endpoint:

• An Authorization Code: As with Authorization Code flow, the Client application can cash this in at the Token Endpoint for an Access Token.
• An ID Token: The ID Token, in this case, contains the c_hash Claim, which is a specifically constructed hash of the Authorization Code.

Because it is a JWS, the ID Token provides the means to protect the Authorization Code from tampering, providing an opportunity to the Client application to ensure its value is valid. The Client application will also receive an ID Token from the Token Endpoint and can check the Claims returned at both Endpoints match. Hybrid flow, whether overlaying Authorization Code or Implicit flow, can add significant benefits for the Client application and their trust of the authentication event.

Final Thoughts

The core benefit of the OpenID Connect standard is that it provides proof-of-authentication to Client applications. It is, however, only one part of the overall OpenID puzzle. The OpenID Foundation orchestrates the creation of many standards, some an enhancement on Core, others engineered for specific industries and use cases. Examples include:

• Discovery, a mechanism for Clients to ingest the metadata for a given identity provider in order to access their services dynamically.
• Dynamic Client Registration, which provides a means for a software application to automatically register at a given identity provider.
• Financial-grade API standards, a suite of standards on which to build financial services APIs.
• Health Relationship Trust (HEART), a profile that allows patients to delegate access to their clinical data.

These additional standards all rely on OpenID Connect at their heart. This, and the increasing number of significant identity providers that support OpenID Connect (most recently Apple), indicate that the protocol is becoming an increasingly important and fundamental building block of the API Economy.