AM as the OpenID Provider

In its role as OpenID provider, AM returns ID tokens to relying parties. Since OpenID Connect builds on top of OAuth 2.0, when AM is configured as an OpenID provider it can also return access and refresh tokens to the relying parties, if needed.

Before configuring OpenID Connect in your environment, ensure you are familiar with the OAuth 2.0 standards and AM’s implementation of OAuth 2.0.

OpenID Connect Concepts

OpenID Connect 1.0 is an identity layer built on OAuth 2.0. It enables clients to verify the identity of users based on the authentication performed by OAuth 2.0 authorization servers, as well as to obtain profile information about the user using REST.

The following sequence diagram demonstrates the basic OpenID Connect flow:

OpenID Connect 1.0 Protocol Flow
Figure 1. OpenID Connect 1.0 Protocol Flow

OpenID Connect clients can register with the provider and manage their client data dynamically.

To let clients discover the end user’s OpenID Connect provider, its endpoints, and how to interact with it, AM supports OpenID Connect Discovery 1.0.

OAuth 2.0 or OpenID Connect?

Both standards were created under the premise of users having the need to interact with a third party service, but aim to solve different problems:

OAuth 2.0 and OpenID Connect Comparison
OAuth 2.0 OpenID Connect

Purpose

To provide users with a mechanism to authorize a service to access and use a subset of their data on their behalf, in a secure way.

Users must agree to provide access under the service’s term and conditions (for example, for how long the service has access to their data, and the purpose that data would be used for).

To provide users with a mechanism to authenticate to a service by providing it with a subset of their data in a secure way.

Since OpenID Connect builds on top of OAuth 2.0, users authorize a relying party to collect a subset of their data (usually information stored in the end user’s profile) from a third party. The service then uses this data to authenticate the user and provide its services.

This way, the user can employ the relying party’s services even if they have never created an account on it.

Use Cases

Use-cases are generic and can be tailored to many needs, but an example is a user allowing a photo print service access to a third-party server hosting their pictures, so the photo print service can print them.

The most common scenario is using social media credentials to log in to a third-party service provider.

Tokens

Access and refresh tokens

ID tokens

Regarding Scopes

Concept to limit the information to share with service or the actions the service can do with the data. For example, the print scope may allow a photo print service to access photos, but not to edit them.

Scopes are not data, nor are related to user data in any way.

Concept that can be mapped to specific user data. For example, AM maps the profile scope to a series of user profile attributes. Since different identity managers may present the information in different attributes, the profile attributes are mapped to OpenID Connect claims.

Claims are returned as part of the ID token. In some circumstances, additional claims can be requested in a call to the oauth2/userinfo endpoint.

For more information about how AM maps user profile attributes to claims, see About Claims.

Another difference between the standards is the name of the actors. The names of the actors in OpenID Connect 1.0 relate to those used in OAuth 2.0 as follows:

OAuth 2.0 and OpenID Connect Actors Comparison
OIDC Actor OAuth 2.0 Actor Description

End User

Resource Owner (RO)

The owner of the information the application needs to access.

The end user that wants to use an application through existing identity provider account without signing up to and creating credentials for yet another web service.

Relying Party (RP)

Client

The third-party that needs to know the identity of the end user to provide their services. For example, a delivery company or a shopping site.

OpenID Provider (OP)

Authorization Server (AS)

Resource Server (RS)

A service that has the end user’s consent to provide the RP with access to some of its user information. As OpenID Connect 1.0 defines unique identification for an account (subject identifier + issuer identifier), the RP can use this as a key to its own user profile.

In the case of an online mail application, this key could be used to access the mailboxes and related account information. In the case of an online shopping site, this key could be used to access the offerings, account, shopping cart and so forth. The key makes it possible to serve users as if they had local accounts.

AM can act as the OpenID Connect provider to authenticate end users and provide RPs with information about the users in the form of an OpenID Connect ID token.

AM supports the following OpenID Connect grant types and standards:

Grant Types
  • Authorization Code

  • Authorization Code with PKCE

  • Back Channel Request

  • Implicit

  • Hybrid

  • Hybrid with PKCE

    For more information, see OpenID Connect Grant Flows.

Standards
  • Session Management and Logout

    Relying parties can:

    • Track whether end users are logged in at the provider using an invisible iframe and the HTML 5 postMessage API.

    • Initiate end user logout at the provider using an endpoint.

    AM can also send logout tokens to relying parties when end user sessions linked to ID tokens become invalid. For more information, see Managing OpenID Connect User Sessions.

  • Discovery and Dynamic Client Registration

    OpenID Connect defines how a relying party can discover the OpenID Provider and corresponding OpenID Connect configuration for an end user. The discovery mechanism relies on WebFinger to get the information based on the end user’s identifier. The server returns the information in JSON Resource Descriptor (JRD) format.

    For more information, see OpenID Connect Discovery and Dynamic Client Registration.

  • Mobile Connect

    Mobile Connect builds on top of OpenID Connect to facilitate the use of mobile phones as authentication devices, offering a way for mobile network operators to act as identity providers.

    For more information, see GSMA Mobile Connect.

See the complete list of supported OpenID Connect and OAuth 2.0 standards.

OpenID Connect Discovery

In order to let relying parties (or clients) discover the OpenID Connect Provider for an end user, AM supports OpenID Connect Discovery 1.0. In addition to discovering the OpenID Provider for an end user, the relying party can also request the OpenID Provider configuration.

AM exposes the following REST endpoints for discovering the URL of the provider and its configuration:

Discovery relies on WebFinger, a protocol to discover information about people and other entities using standard HTTP methods. WebFinger uses Well-Known URIs, which defines the path prefix /.well-known/ for the URLs defined by OpenID Connect Discovery.

Once the relying party has discovered the URL of the provider, it can register with it dynamically. For test purposes, or if it suits your environment better, you can also register them manually.

The /.well-known/webfinger endpoint is disabled by default. To enable it, perform the following steps:

  1. In the AM Admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > OpenID Connect.

  2. Enable OIDC Provider Discovery.

  3. Save your changes.

    The discovery endpoint now allows searches for users within this realm only. Repeat this procedure in as many realms as necessary.

Security Considerations

AM provides security mechanisms to ensure that OpenID Connect 1.0 ID tokens are properly protected against malicious attackers: TLS, digital signatures, and token encryption.

While designing a security mechanism, you can also take into account the points developed in the section on Security Considerations in the OpenID Connect Core 1.0 incorporating errata set 1 specification.

OpenID Connect 1.0 requires the protection of network messages with Transport Layer Security (TLS).

For additional security considerations related to the use of OAuth 2.0, see Security Considerations.

About Token Storage Location

AM OpenID Connect and OAuth 2.0-related services are stateless unless otherwise indicated; they do not hold any token information local to the AM instances.

Access and refresh tokens can be stored in the CTS token store or presented to the clients as JWTs. However, OpenID Connect tokens and session information are managed in the following way:

  • ID tokens are always presented as JWTs.

  • OpenID Connect sessions are always stored in the CTS token store.

For more information about how to configure access and refresh token storage, see About Token Storage Location in the OAuth 2.0 Guide.