OpenID Connect

OpenID Connect is a simple identity protocol and open standard that is built on the OAuth 2.0 protocol that enables client applications to rely on authentication that is performed by an OpenID Connect Provider to verify the identity of a user.

OpenID Connect uses OAuth 2.0 for authentication and authorization and then builds identities that uniquely identify users. Client applications can also obtain basic profile information about a user in an interoperable and REST-like manner from OpenID Connect Providers.

Liberty supports OpenID Connect 1.0 and plays a role as a Client, or Relying Party, and as a Provider in web single sign-on. The following OpenID Connect specification is supported:

OpenID Connect Core 1.0: Liberty servers configured as OpenID Connect Providers or Relying Parties support authentication by using the Authorization Code Flow and the Implicit Flow.

For those using a Liberty server as a Web-based Relying Party, the OpenID Connect Basic Client Implementer's Guide 1.0 is a subset of the OpenID Connect Core specification that is easier to read and provides details for Web-based Relying Parties that use the Authorization Code Flow.

Access Token: A credential that is used to access protected resources. An access token is a string that represents an authorization that is issued to the client.

Authorization Endpoint: A resource on an OpenID Provider that accepts an authorization request from a client to perform authentication and authorization of a user. The authorization endpoint returns an authorization grant, or code, to the client in the Authorization Code Flow. In the Implicit Flow, the authorization endpoint returns an ID token and access token to the client.

Authorization Grant: A credential that represents a user's authorization to access resources, and is used by a client to obtain an access token.

Claim: Information asserted about an entity. Examples of a claim include phone number, first name, last name, and others.

ID Token: JSON Web Token (JWT) that contains claims about the authenticated user.

Introspection Endpoint: A resource on an OpenID Provider that enables a client that is holding an access token to retrieve information that was used to create the access token, such as the user name, granted scopes, client ID, or other information.

OpenID Connect Provider (OP): An OAuth 2.0 authorization server that is capable of providing claims to a client, or Relying Party (RP).

Refresh Token: Issued to the client by the OP and is used to obtain a new access token when the current access token expires, or to obtain more access tokens.

Relying Party (RP): Either a Liberty server configured as an OpenID Connect Client, or a client application that requires claims from an OpenID Provider (OP).

Scope: Privilege or permission that is allowed to access resources of a third party.

Token Endpoint: A resource on an OP that accepts an authorization grant, or code, from a client in exchange for an access token, ID token, and refresh token.

The Liberty server as an OpenID Connect Client

You can configure Liberty to function as an OpenID Connect Client. This setup enables the Liberty server to rely on another Liberty server that is acting as an OP for user authentication and authorization.

A Liberty server that is configured to act as an OpenID Connect Client supports the Authorization Code Flow of the OpenID Connect 1.0 standard.

In the Authorization Code Flow, all token exchanges are handled by using the token endpoint of the OpenID Connect Provider. First, the client submits an authorization request to the authorization endpoint of the OP. Upon successful authentication and authorization with the OP, the client receives an authorization grant, or code, from the OP. This authorization code can then be sent in a request to the token endpoint of the OP. The client receives an ID token, an access token, and a refresh token in the response from the token endpoint. The client then validates the ID token and retrieves the subject identifier of the user. This profile flow is intended for clients that can securely maintain a client secret between themselves and the OP. This flow also allows clients to obtain a refresh token.

For configuring a Liberty server as an OpenID Connect Client, see Configuring an OpenID Connect Client in Liberty

The Liberty server as an OpenID Connect Provider

You can configure Liberty to function as an OpenID Connect Provider. This setup enables the Liberty server to act as an authorization server that can be used by OpenID Connect Clients.

A Liberty server that is configured to act as an OpenID Connect Provider supports the Authorization Code Flow and Implicit Flow of the OpenID Connect 1.0 standard. Each flow determines how the ID token, access token, and refresh token are returned to the client.

The Authorization Code Flow handles all token exchanges by using the token endpoint of the OpenID Connect Provider. An OpenID Connect Provider accepts an authorization request from a client at the OP's authorization endpoint. If authentication is necessary, the OpenID Connect Provider performs the appropriate authentication. The OpenID Connect Provider also obtains any required consent or authorization from the user, for example by prompting the user in a browser for permission to grant access to certain scopes. If successful, or if no authentication was required, the OpenID Provider sends back an authorization grant, or code, to the client. The OpenID Connect Provider then accepts a request that is submitted to its token endpoint by the client that includes the authorization code. The request that includes the authorization code is validated by the OpenID Provider. Upon successful validation, the OpenID Connect Provider returns a response to the client that includes an ID token and an access token.

In the Implicit Flow, unlike the Authorization Code Flow, all tokens are returned from the authorization endpoint; the token endpoint of the OP is not used. First, a client prepares and sends an authentication request to the authorization endpoint of the OP. The OpenID Connect Provider then performs any necessary authentication and also obtains any required consent or authorization from the user. For example, the OpenID Connect Provider prompts the user in a browser for permission to grant access to certain scopes. Upon successful authentication and authorization, the OpenID Connect Provider sends back an ID token and an access token to the client. The client then validates the ID token and retrieves the subject identifier of the user. This profile flow is intended for clients that cannot securely maintain a client secret between themselves and the OP, such as native applications.

For configuring a Liberty server as an OpenID Connect Provider, see Configuring an OpenID Connect Provider in Liberty.

Authorization Code Flow

A typical OpenID Connect Authorization Code Flow is described as follows:

A user accesses an application on the RP.
The RP prepares an authentication request and redirects the user to the OP.
The OP authenticates the user, for example by prompting the user for credentials. The user authorizes the RP to access the information that is required by the application. The OP generates a one-time use authorization code for the RP.
The OP redirects the user back to the RP with the authorization code.
The RP calls the token endpoint of the OP to exchange the authorization code for an access token, ID token, and a refresh token.
The RP uses the ID token to authorize the user.

Implicit Flow

The Implicit Flow is only supported by Liberty servers that are acting as an OpenID Connect Provider. A typical OpenID Connect Implicit Flow is described as follows:

A user accesses an application on the RP.
The RP prepares an authentication request and redirects the user to the OP.
The OP authenticates the user, for example by prompting the user for credentials. The user authorizes the RP to access the information that is required by the application.
The OP redirects the user back to the RP with an ID token and an access token.
The RP uses the ID token to authorize the user.