AM as OpenID provider
An OAuth 2.0 authentication server that implements OpenID Connect (OIDC) is referred to as an OpenID provider (OP). An OAuth 2.0 client that uses OIDC is also referred to as a relying party (RP).
In its role as an OP, AM returns ID tokens to relying parties. Because OIDC extends OAuth 2.0, when AM is configured as an OP it can also return access and refresh tokens to relying parties.
|
Before configuring OIDC in your environment, ensure you are familiar with the OAuth 2.0 standards and the AM implementation of OAuth 2.0. |
OIDC concepts
OIDC is an identity layer built on top of OAuth 2.0. It lets clients verify the identity of a user based on the authentication performed by OAuth 2.0 authorization servers. It also lets clients obtain profile information about the user over REST.
The following sequence diagram demonstrates the basic OIDC flow:
OIDC clients can register with the OP and manage their client data dynamically.
To let clients discover an end user’s OP, its endpoints and how to interact with it, AM supports the OpenID Connect Discovery 1.0 specification.
OAuth 2.0 or OIDC?
The OAuth 2.0 and OIDC standards were both created for users who need to interact with a third party service; however, they aim to solve different problems. This topic compares OAuth 2.0 and OIDC functionality and the actors in the implementation of both standards.
| OAuth 2.0 | OIDC | |
|---|---|---|
Purpose |
Gives users a way 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 terms and conditions; for example, how long the service has access to their data and what the data is used for. |
Gives users a way to authenticate to a service by providing it with a subset of their data in a secure way. Because OIDC extends OAuth 2.0, users can authorize a relying party to collect a subset of their data (usually information stored in the user’s profile) from a third party. The service then uses this data to authenticate the user and provide its services. The user can therefore use the relying party’s services even if they have never created an account with the relying party. |
Use cases |
Use cases are generic and can be tailored to many needs. A common 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 |
Role of scopes |
Scopes limit the information that can be shared with the service or what the service can do with the data.
For example, the OAuth 2.0 scopes are not data and are not related to user data in any way. |
Scopes can be mapped to specific user data.
For example, AM maps the Claims are returned as part of the ID token.
In some cases, additional claims can be requested in a call to the For more information about how AM maps user profile attributes to claims, see Claims. |
| 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 who wants to use an application through an 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. OIDC defines unique identification for an account (subject identifier + issuer identifier). The RP can use this identification as a key to the user profile. In the case of an online mail application, the key could be used to access the user’s mailboxes and related account information. In the case of an online shopping site, the key could be used to access personalized offerings, account, shopping cart, and so on. The key makes it possible to serve users as if they had local accounts. AM can act as the OP to authenticate end users and provide RPs with information about the users in the form of an OIDC token. |
AM and OIDC
This section describes AM’s implementation of OIDC, including the supported grant types and standards.
Grant types
-
Authorization code
-
Authorization code with PKCE
-
Backchannel request
-
Implicit
-
Hybrid
-
Hybrid with PKCE
For details, refer to OpenID Connect grant flows.
Standards
This section lists the OIDC standards that AM supports. For more information, refer to the complete list of supported OIDC and OAuth 2.0 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 OIDC user sessions.
Discovery and dynamic client registration
OIDC defines how a relying party can discover the OP and the corresponding OIDC 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 details, refer to OIDC discovery and Dynamic client registration.
Mobile Connect
Mobile Connect extends OIDC to let mobile phones be used as authentication devices. This allows mobile network operators to act as identity providers.
For details, refer to GSMA Mobile Connect.
OIDC discovery
To let relying parties (or clients) discover the OP for an end user, AM supports the OpenID Connect Discovery 1.0 specification. In addition to discovering the OP for an end user, the relying party can request the OP configuration.
AM exposes the following REST endpoints for discovering the URL of the OP and its configuration:
Discovery relies on the WebFinger 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 OIDC discovery.
Relying parties need to find the right host:port/deployment-uri combination to locate the well-known endpoints.
You must manage the redirection to AM using your proxies, load balancers, and others,
such that a request to http://www.example.com/.well-known/webfinger reaches,
for example, https://openam.example.com:8443/openam/.well-known/webfinger.
When the relying party has discovered the URL of the OP, it can register with the OP dynamically. For test purposes, or if it suits your environment better, you can also register clients manually.
The /.well-known/webfinger endpoint is disabled by default. To enable it, follow these steps:
-
In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > OpenID Connect.
-
Enable OIDC Provider Discovery.
-
Save your changes.
The discovery endpoint now allows searches for users within this realm only. Repeat these steps in other realms, as required.
Security considerations
AM provides the following security mechanisms to ensure that OIDC ID tokens are properly protected against malicious attackers:
-
TLS
-
Digital signatures
-
Token encryption
When you are designing a security mechanism, take into account the points developed in the section on Security considerations in the OpenID Connect Core 1.0 incorporating errata set 1 specification.
OIDC requires that network messages are protected with Transport Layer Security (TLS).
For information about protecting traffic to and from the web container in which AM runs, refer to Secrets, certificates, and keys.
For additional information, refer to the OAuth 2.0 Security considerations.
Token storage location
OIDC and OAuth 2.0-related services are stateless in AM, unless otherwise indicated; they do not hold any token information locally.
Access and refresh tokens can be stored in the CTS token store or presented to clients as JWTs; however, OIDC tokens and session information are managed in the following way:
-
ID tokens are always presented as JWTs.
-
OIDC sessions are always stored in the CTS token store.
For more information about how to configure access and refresh token storage, refer to Token storage location.