Skip to content

Custom Claims

OpenID Connect (OIDC) relies on claims to convey user and resource-specific information. Claims are categorized into standard (registered) claims (e.g., email, name, roles) and public claims, which are non-registered claims. Standard claims are defined in the OIDC specification, while public claims are non-registered claims. Custom claims are a subset of public claims. Understanding claim types and their management is critical for secure, flexible identity workflows.

Standard Claim Types

OIDC defines three primary categories of claims:

  1. Registered Claims
    These are standardized claims defined in the OpenID Connect specification (e.g., sub, email, name, roles). They are used to represent user identity, authentication, and authorization metadata.

  2. Public Claims
    Claims not registered in the OIDC specification. These are non-registered claims, and custom claims are a subset of public claims. Public claims are not encrypted and can be used freely, but they may expose sensitive data if not managed carefully.

  3. Private Claims
    Claims shared between parties (e.g., a client and an authorization server) using a shared secret. These are often used for internal workflows and are not intended for public use.

Public Claims in OpenID Connect

Public claims, including custom claims, are added to ID tokens or access tokens via the claims parameter in the authorization request. Here’s how to implement them:

1. Define Public Claims in Scopes

Public claims are often tied to scopes. For example, a scope custom/department might grant access to a claim like department:engineering.

2. Structure the Claims Parameter

The claims parameter is a JSON object specifying the custom claims you want included in the token. For example:

GET /authorize?response_type=code&client_id=your_client_id&redirect_uri=your_redirect_uri&scope=openid+custom/department&claims={"custom/department":{"essential":true,"values":["engineering"]}}

This request includes the custom/department scope and specifies that the department claim is essential and should include the value engineering.

3. Format Custom Claims in JWTs

Custom claims are included in the JWT payload as key-value pairs. For example:

{
  "sub": "1234567890",
  "email": "[email protected]",
  "custom/department": "engineering"
}

4. Handle Custom Claims in Client Applications

Clients must validate and use custom claims according to your application’s requirements. Ensure that claims are encrypted or scoped appropriately to prevent unauthorized access.