OpenId Connect Standard Claims

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0, designed to provide user authentication and authorization capabilities for applications. One of the key components of OIDC is the concept of tokens. Tokens carry information about the authentication and authorization context and are used to make secure and authorized requests. In this blog post, we will explore the different types of claims found in OIDC tokens and understand their significance in the authentication process.

Access Token Claims

Access tokens in OIDC are used to authorize access to protected resources on behalf of a user. They contain a set of claims that convey information about the user. As OpenID Connect is based on top of OAuth 2.0, you should have a look at the list in our other post talking about OAuth 2 Access Token Claims.

ID Token Claims

The ID token is a JSON Web Token (JWT) that contains claims about the authentication event and the user. It is used to authenticate the user and provide information about the user's identity. The ID token is typically consumed by the client application to verify the user's identity and obtain user information. Here are some of the standard claims found in the ID token:

• iss: The issuer claim represents the issuer of the token.
• sub: The subject claim represents the subject of the token, which is typically the user ID.
• aud: The audience claim represents the audience for which the token is intended.
• exp: The expiration time claim denotes the time when the token expires.
• iat: The issued at claim represents the time when the token was issued.
• auth_time: The authentication time claim denotes the time when the user authenticated.
• nonce: The nonce claim is used to prevent replay attacks.
• acr: The authentication context class reference claim represents the authentication context class reference.
• amr: The authentication methods references claim contains the authentication methods used.
• azp: The authorized party claim represents the authorized party for which the token is intended.

Focus on the amr Claim

The amr claim is used to convey information about the authentication methods used to authenticate the user. It provides details about the authentication methods and mechanisms used during the authentication process. The amr claim can contain one or more values representing the authentication methods used, such as password, OTP, or biometric authentication.

Example of an ID token payload containing the amr claim:

{
  "iss": "https://auth.example.com",
  "sub": "1234567890",
  "aud": "https://api.example.com",
  "exp": 1635200000,
  "iat": 1635196400,
  "amr": ["pwd", "otp"]
}

The different available values are defined in the Authentication Method Reference Values RFC 8176.

Focus on the acr Claim

The acr claim is used to convey information about the authentication context class reference. It represents the level of assurance or confidence in the authentication process. The acr claim provides details about the authentication context and the strength of the authentication mechanisms used during the authentication process.

Example of an ID token payload containing the acr claim:

{
  "iss": "https://auth.example.com",
  "sub": "1234567890",
  "aud": "https://api.example.com",
  "exp": 1635200000,
  "iat": 1635196400,
  "acr": "http://schemas.openid.net/pape/policies/2007/06/multi-factor"
}

In this example, the acr claim indicates that the authentication process involved multi-factor authentication. The value of the acr claim can vary depending on the authentication context and the level of assurance provided by the authentication mechanisms.

Some of the common values for the acr claim include:

• http://schemas.openid.net/pape/policies/2007/06/multi-factor: Indicates multi-factor authentication.
• http://schemas.openid.net/pape/policies/2007/06/phishing-resistant: Indicates phishing-resistant authentication.
• http://schemas.openid.net/pape/policies/2007/06/multi-factor-physical: Indicates physical multi-factor authentication.

Focus on the azp Claim

The azp claim is used to convey information about the authorized party for which the token is intended. It represents the client ID of the authorized party that is allowed to use the token. The azp claim is typically used in scenarios where the ID token is intended for a specific client application.

Example of an ID token payload containing the azp claim:

{
  "iss": "https://auth.example.com",
  "sub": "1234567890",
  "aud": "https://api.example.com",
  "exp": 1635200000,
  "iat": 1635196400,
  "azp": "client_id"
}

In this example, the azp claim indicates that the token is intended for the client application with the client ID client_id. The azp claim helps ensure that the token is only used by the authorized party for which it is intended.

Standard Identity Claims

In addition to the OAuth 2.0 claims, there are standard identity claims that provide specific information about the user's profile and attributes. These claims offer a standardized way of conveying essential identity-related data. Let's explore some of the commonly used standard identity claims:

• name: The name claim represents the user's full name.
• given_name: This claim contains the user's given or first name.
• family_name: The family name claim represents the user's last or family name.
• middle_name: The middle name claim carries the user's middle name, if applicable.
• nickname: The nickname claim contains a short name or alias used by the user.
• preferred_username: This claim represents the user's preferred username or handle.
• profile: The profile claim points to a URL that provides additional profile information about the user.
• picture: The picture claim provides a URL to the user's profile picture or avatar.
• website: This claim contains the URL of the user's website or homepage.
• email: The email claim represents the user's email address.
• email_verified: The email verified claim indicates whether the user's email address has been verified.
• gender: This claim specifies the gender or sex of the user.
• birthdate: The birthdate claim denotes the user's date of birth.
• zoneinfo: This claim represents the user's time zone or geographical region.
• locale: The locale claim indicates the user's preferred language and cultural preferences.
• phone_number: The phone number claim contains the user's phone number.
• phone_number_verified: The phone number verified claim indicates whether the user's phone number has been verified.
• address: This claim carries the user's postal address or parts of it.
• updated_at: The updated at claim represents the time when the user's information was last updated.

An exhaustive list of those claims is available in the OpenID Connect Specs. If you want to know more about the existing claims for JWT more generally, you can check the IANA JWT Claims Registry.

These standard identity claims provide a standardized way of conveying important user attributes in OpenID Connect tokens. However, it's important to note that the availability and inclusion of these claims may vary depending on the identity provider and the user's consent and privacy settings. Additionally, custom claims can be defined to include domain-specific identity information as needed.