For example, you could have your application (custom-built), forum software like Discourse (open source), Oracle (COTS), and Zendesk all delegate authentication to your OIDC-compliant user identity datastore. You can support both employees and customers using such a solution. Because many customer applications are web apps, OIDC is a perfect fit for a customer identity and access management (CIAM) system.
As mentioned above, OIDC is built on top of OAuth2. It extends OAuth2 to include a new token type, the Id token, and standardizes the meaning of certain scopes. OIDC also leverages existing OAuth2 grants such as the Authorization Code grant and the Implicit grant. However, OIDC calls them flows.
Both OAuth2 grants and OIDC flows specify how data flows between various components of an authorization or authentication workflow, respectively. Just like grant and flow mean pretty much the same thing, OAuth2 and OIDC use different terms to represent other similar concepts.
The component which… | OAuth2 Term | OIDC Term |
---|---|---|
Wants to know about the user | Resource Server | Relying Party |
Checks the user is who they say they are | Authorization Server | OpenID Provider |
Starts the grant or flow | Client | Client |
Because OIDC is built on OAuth2, a successful OIDC flow:
In addition, OAuth2’s error messages and transport protocols are used in OIDC flows. OIDC also re-uses the idea of the OAuth’s non-interactive refresh of tokens. Below, we’ll discuss tokens in more detail.
Using OIDC instead of another OpenID compatible authentication system allows you to leverage OAuth’s widespread libraries and developer’s understanding. Getting the access token during the OIDC flow can also be helpful. A client can present the token to other components of your system to gain access to data or functionality.
Similar to other single sign-on software, using OIDC has the following benefits:
OIDC is unique because:
Let’s dive into some of the major pieces of OIDC.
OIDC has a few important components:
An example of an OP is FusionAuth. Examples of RPs include:
Here’s an example OIDC flow, using the authorization code flow.
For the RP, the end result of an interaction with the OP is a set of tokens that contain information about the user. Let’s look at those next.
Because OIDC is built on top of OAuth, an access token is always returned, but an Id token and possibly a refresh token are returned as well. The Id token is the star of the OIDC show, because it contains authentication information, so that’s what this article will focus on.
The Id token looks like this:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImd0eSI6WyJhdXRob3JpemF0aW9uX2NvZGUiXSwia2lkIjoiWG9xN2tLM2VJWHJ5WW1pNTBaT3ZnMmJjY2VNIn0.eyJhdWQiOiJlOWZkYjk4NS05MTczLTRlMDEtOWQ3My1hYzJkNjBkMWRjOGUiLCJleHAiOjE3MDMwMzcxODAsImlhdCI6MTcwMzAzMzU4MCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0xMTExMTExMTExMTEiLCJqdGkiOiIyOWVkMjA5NC1jOWIxLTRmMGQtODc4Mi00YTc2NWI4YTZmOTIiLCJhdXRoZW50aWNhdGlvblR5cGUiOiJQQVNTV09SRCIsImVtYWlsIjoicmljaGFyZEBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJhdF9oYXNoIjoiZmtqUzc4YjhCbXRlM2lRRVBIRUk2ZyIsImNfaGFzaCI6ImlrT3lkdmljUHRqNU9HMm5zcExtOFEiLCJzY29wZSI6Im9mZmxpbmVfYWNjZXNzIHByb2ZpbGUgb3BlbmlkIiwic2lkIjoiNjlhOTQ4OTYtNjg3ZS00MDQ5LTkwZGItMTY0ZDYwYWVmN2I2IiwiYXV0aF90aW1lIjoxNzAzMDMzNTgwLCJ0aWQiOiJkN2QwOTUxMy1hM2Y1LTQwMWMtOTY4NS0zNGFiNmM1NTI0NTMifQ.rT7Q39-RFT63aw996v0zu2vwS-RIYRvTccmEi_rGV19aKnRnlZD7Bx_dJaaoZxyvD3xfO1wVA2aO_nHQmKhwLuFIt4Jae0Z4a3nlJLKaumCxh4yB4vjAvKAwvhClwWYhx1LbbMl0lvVy-qvs-niVTgPLTVMYnSFXnfTuN8LMDCf7keP3SjS1MTyEeG2WtZzvPd6j2zu66rl5y3uCfpqaLbR0URDsJjQE4GbUMf7UODhZ1_ztGXg_-vGKvpomGB0-0vUmcrqXENtXRFy9hPYHXGp4T-uAy93DUo7AvsrECAHryWq6wzbLIXXeMcCpjWl87Cqb0TwMyM5D30VH2crlLQ
The Id token is a signed JWT and must be validated. Like any signed JWT, it contains three parts, a header specifying metadata, a payload containing claims and data, and a signature, used to verify the integrity of the JWT.
The claims inside the token, in the payload, can be examined by the RP to determine the identity of the user who went through the flow.
A claim is a fancy term for a key/value pair in the JSON object which is the payload of the JWT. Learn more about JWTs.
There are several standard claims defined by the OIDC standard. Some reflect the authentication event and details about the OP. These include but are not limited to:
iss
, the identifier of the issuer of the Id token. It’s a URL like https://example.com
.aud
, the identifier of the RP. Per the specification, it must be at least the client_id
of the RP, but can include other identifiers.exp
, the expiration time of the Id token.iat
, the time at which the Id token was issued.auth_time
, the time the authentication event occurred.There are also user profile claims. Here’s an incomplete list:
sub
, an identifier for the end user at the OP.name
, the full name, in a format displayable to humans.preferred_username
, a preferred username for the RP to use. This is not guaranteed to be unique.email
, the user’s preferred email address. Again, this is not guaranteed to be unique.email_verified
which is true
if the email address has been verified to be controlled by the end user, as defined by the OP.locale
, the end user’s locale, like en-US
or fr-CA
.phone_number
, the user’s preferred telephone number.updated_at
, the time the user’s information was last updated.All times are numbers representing the number of seconds since the UNIX epoch. The iss
, sub
, aud
, exp
, and iat
claims are required and will be present in every Id token. Every other claim is optional, though some are required if the RP requests them or the OP is configured in certain ways.
You can see that an RP can get a decent amount of information about a user and the authentication from the OP. It’s all transmitted in the Id token, which must be validated to ensure that there’s no funny business going on.
As an RP, you must validate the Id token you receive to ensure that the authentication event occurred at the correct OP, in the correct manner. This is a multi-step process:
iss
claim matches the expected OP Issuer value.aud
claim contains the RP client_id
.exp
claim is in the future.Because of the flexibility of OIDC, there will be other validation steps depending on what data is requested.
The combination of the iss
and sub
claims is guaranteed by OIDC to be unique and stable. If you are building an application and need a unique identifier for a user, make sure you use the combination of these.
The sub
claim is guaranteed to be unique within any OP and never reassigned or changed.
After validation, the RP can use the claims from the Id token. It might use these in many different ways:
auth_time
claimThe RP can request specific profile data. OIDC typically uses scopes to determine which user profile data claims to return. The following scopes are outlined by the specification:
profile
which requests access to the users default profile claims. These are: name
, family_name
, given_name
, middle_name
, nickname
, preferred_username
, profile
, picture
, website
, gender
, birthdate
, zoneinfo
, locale
, and updated_at
.email
which requests access to the email
and email_verified
claims.address
which requests access to the address
claim.phone
which requests access to the phone_number
and phone_number_verified
claims.An OP may support zero, one or more of these scopes. These scopes are sent on the initial authorization request, just like any other OAuth scopes. So an RP can ask for just the email
and profile
scopes. Since the user has to consent to any information shared, requesting the minimum amount of profile data to fulfill the RP’s needs is good practice.
OIDC supports a number of response types, which determine access to the tokens and whether a refresh token can be requested. In general, however, using the code
response type, which maps to the OAuth authorization code grant, is a good starting point.
OIDC specifies how the RP can delegate authentication to the OP. But there are no guarantees in the specification or in practice about how the user is authenticated. It may be authenticated with strong methods such as passkeys or weaker methods such as cookies. From the specification:
The methods used by the Authorization Server [OP] to Authenticate the End-User (e.g., username and password, session cookies, etc.) are beyond the scope of this specification.
The actual methods of authentication are defined and managed by the OP.
In addition, verification of emails or phone numbers, which are critical to ensure the security of your users, are handled by the OP. They are also not defined by the specification, so make sure to check your OP’s documentation to understand what verification methods they use.
As mentioned above, OIDC works well with CIAM systems, such as FusionAuth.
OIDC is useful when you are trying to standardize the authentication process across many applications. Because it is a standard, many applications are RPs which support OIDC. This is just as true for applications which customers use as those that employees use.
Leveraging OIDC simplifies the authentication experience for your customers and also gives you a single view into their activities.
Here are additional resources: