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 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 | 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 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 Claims are returned as part of the ID token.
In some circumstances, additional claims can be requested in a call to the For more information about how AM maps user profile attributes to claims, see 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:
| 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
-
Backchannel 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 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.
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.
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:
-
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 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 information about protecting traffic to and from the web container in which AM runs, see Secrets, certificates, and keys.
For additional security considerations related to the use of OAuth 2.0, see Security Considerations.
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 Token storage location in the OAuth 2.0 guide.