Skip to main content

Manage token claims

Claims are the data your authorization server packs into the access tokens, ID tokens, and SAML assertions it issues. Use claims to put the user identity, scope, application, organization, or session context your application needs into the token, so the application can authorize requests without a second round-trip to SecureAuth Connect.

Configure claims on either a workspace or an organization, depending on where your application is registered. Both are authorization servers in their own right, and the Add Claim dialog is identical in both contexts.

About claims​

A claim is a name/value pair inside a token or a SAML assertion. The token issuer mints the claim's value from a source you pick, such as the user's authentication context, the organization the user signed in through, or the client application's metadata. Your application reads the claim out of the token to make access decisions.

Scopes group claims so they only appear in tokens when a specific scope is granted. By default a claim is global, included in every token; use Restrict Claim Release to scope it to specific scopes.

For outgoing SAML assertions, see SAML assertion attributes sent to service providers.

Prerequisites​

Add a claim​

  1. Go to the workspace or organization where you want the claim to apply, then in the left navigation select OAuth > Claims.

  2. Select the tab for the token type you're configuring:

    • Access Tokens – tokens your application uses to call APIs.
    • ID Tokens – OIDC tokens that carry user identity.
    • Custom Claims – claims that aren't tied to a built-in token type.
    • SAML Assertion Attributes – available only when SAML is enabled in your tenant.

    Claims landing page on the Access Tokens tab

  3. Click + Add Claim.

  4. Fill in the dialog. The fields are described in the table below; the Source options vary by Type, listed in Type options.

  5. Click Add.

    Add Claim dialog showing Name, Description, Type, Source, and the Restrict Claim Release toggle

Fields​

FieldDescription
NameThe claim's name in the issued token. Required.
DescriptionA short note about what the claim is for. Optional.
TypeThe category of data the claim pulls from. See Type options for what each Type exposes. Required.
SourceThe specific attribute within the chosen Type that supplies the claim's value. The Source dropdown's options change based on the selected Type. Required.
Restrict Claim ReleaseA toggle. When off (default), the claim is included in every token. When on, a Scopes field appears so you can limit the claim to tokens issued for specific scopes.
ScopesOnly visible when Restrict Claim Release is on. The scopes that must be granted for this claim to be included in the token.
SAML NameAvailable on the SAML Assertion Attributes tab only. The SAML attribute name issued by your Service Provider's assertion (for example, urn:oid:2.5.4.10).
SAML Attribute FormatAvailable on the SAML Assertion Attributes tab only. The format of the SAML attribute (for example, urn:oasis:names:tc:SAML:2.0:attrname-format:uri).

Type options​

Each Type exposes a different Source list. Pick the Type that matches where the data lives, then the Source for the specific attribute you want.

TypeWhat it representsSource options
AuthN ContextAttributes mapped from the identity provider through the authentication context schema. The most common choice for user identity claims.Subject, List of scopes, List of groups that user belongs to, Email, Email verified, Phone, Phone verified, Full mailing address, Full street address, City or locality, and others (scrollable list).
Risk ContextRisk-assessment data calculated at authentication time.Level of assurance, Fingerprint, Transaction ID.
Login SessionData about the user's current login session.Login identifier.
ClientAttributes of the OAuth client application that requested the token.Tenant ID, Server ID, ID, Name, Description, Application type, Redirect URIs, Grant types, Scopes, Audience, and others (scrollable list).
WorkspaceMetadata configured on the workspace.Metadata (with a secondary selector for the specific metadata field).
UserAttributes from the user directory.Payload, Metadata, Business Metadata, Groups.
OrganizationThe organization the user signed in through. Use this in B2B SaaS to attach customer context to every token.ID, Name, Description, Parent ID, Metadata.

Type dropdown expanded showing the seven Type options

Example: add organization_id to access tokens​

A common B2B SaaS need is to include the customer's organization ID in every access token so the application knows which customer each request belongs to.

  1. In the workspace where your shared application is registered, go to OAuth > Claims.
  2. On the Access Tokens tab, click + Add Claim.
  3. Fill in:
    • Name: organization_id
    • Type: Organization
    • Source: ID
  4. Click Add.

Add Claim dialog with Type set to Organization and Source set to ID

Every access token your authorization server issues now carries an organization_id claim whose value is the ID of the organization the user signed in through.

One claim, every organization

You configure this claim once on the workspace. Because the Type is Organization, SecureAuth Connect resolves the value at token-issue time from whichever organization the user signed in through. Add a new customer organization later and its tokens get the same organization_id claim automatically, with no extra setup.

Video tutorial​

In the video below, we add a custom claim based on authentication context data. The claim shows the user's phone number, provided by the identity provider, which is why the Type is AuthN Context. The Source is Phone, originally a claim sent by the IdP and mapped to SecureAuth Connect's authentication context.

Edit a claim​

  1. In the Claims section, select an existing claim. The Edit claim page appears.
  2. Modify the claim data and click Update.

Remove a claim​

  1. In the Claims section, click the trash can icon next to the claim you want to delete.
  2. Confirm.
warning

This action is permanent and cannot be undone.