Identity Cloud

Identity Cloud as OIDC 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, Identity Cloud returns ID tokens to relying parties. Because OIDC extends OAuth 2.0, when Identity Cloud is configured as an OP it can also return access and refresh tokens to relying parties.

Before configuring OIDC on your tenant, ensure you are familiar with the OAuth 2.0 standards and the Identity Cloud 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 protocol flow
Figure 1. OIDC protocol 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, Identity Cloud 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.

Table 1. Comparison between OAuth 2.0 and OIDC functionality
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 print scope might allow a photo print service to access photos but not to edit them.

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, Identity Cloud maps the profile scope to a series of user profile attributes. Because different identity managers can present information in different attributes, profile attributes are mapped to OIDC claims.

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

For more information about how Identity Cloud maps user profile attributes to claims, refer to Claims.

Table 2. Comparison between OAuth 2.0 and OIDC actors
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.

Identity Cloud can act as the OP to authenticate end users and provide RPs with information about the users in the form of an OIDC token.

Identity Cloud and OIDC

This section describes Identity Cloud’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 OIDC grant flows.

Standards

This section lists supported OIDC 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.

Identity Cloud can also send logout tokens to relying parties when end user sessions linked to ID tokens become invalid. For details, refer to 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, Identity Cloud 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.

Identity Cloud 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.

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:

  1. Under Native Consoles > Access Management, 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 these steps in other realms, as required.

Security considerations

Identity Cloud 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 additional information, refer to the OAuth 2.0 Security considerations.

Token storage location

OIDC and OAuth 2.0-related services are stateless in Identity Cloud, 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.

Copyright © 2010-2024 ForgeRock, all rights reserved.