Custom Claims and Profile Mapping

Optare SSO provides custom claims in the ID Token and UserInfo response to help you manage user access and organization context.

Available Claims

In addition to standard OIDC claims (sub, name, email, etc.), the following custom claims are available:

organizationId

Type: string Description: The unique identifier of the organization the user is currently acting within.

licenses

Type: string[] Description: An array of product slugs that the user has an active license for within the requested scopes. Example: ["crm", "analytics"]

entitlements

Type: string[] Description: A flattened list of granular feature flags or entitlements derived from the products the user has access to. Example: ["crm:read", "crm:write", "analytics:view"]

Accessing Claims

Via UserInfo Endpoint

When you call the /oauth/userinfo endpoint with a valid Access Token, the JSON response will include these fields directly at the top level.

Example Response:

{
  "sub": "user_12345",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "organizationId": "org_98765",
  "licenses": ["crm", "analytics"],
  "entitlements": ["crm:full_access", "analytics:viewer"]
}

Via ID Token

The ID Token (JWT) returned during the token exchange also includes these claims. You can decode the JWT to access them without making an additional request to the UserInfo endpoint.

Mapping in NextAuth.js

To use these claims in your application, you should map them in the profile callback of your provider configuration.

profile(profile) {
  return {
    id: profile.sub,
    name: profile.name,
    email: profile.email,
    // Custom mappings
    organizationId: profile.organizationId,
    licenses: profile.licenses,
    entitlements: profile.entitlements
  }
}

Then, verify they are passed to the session in the session callback.

callbacks: {
  async session({ session, token }) {
    session.user.organizationId = token.organizationId;
    session.user.licenses = token.licenses;
    session.user.entitlements = token.entitlements;
    return session;
  }
}