Custom claims

Custom claims let you declare your own project-wide set of typed claims and have enterprise or social (OIDC/OAuth) connections map their own attributes/claims onto them. This is distinct from attribute mapping, which renames a provider attribute/claim into one of Hanko’s fixed standard slots (name, email, …) - custom claims are project-defined, not fixed, and none of them are added to the session JWT automatically (see Accessing custom claims for how to opt one in).

​

Declaring custom claims

To declare a custom claim:

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Custom claims.
3. Click New claim.
4. Provide a Name, a Type (string, number, boolean, or string_list), and an optional Description.
5. Click Save.

A project may declare at most 50 custom claims. A claim name must be a valid identifier and must not be one of the claim keys Hanko always adds to the JWT itself (sub, iat, exp, aud, iss, email, username, session_id). Custom claims are deliberately scalar or list-of-scalar only (string, number, boolean, string_list) - there’s no nested/object type. Enterprise connection attributes are structurally flat, and this keeps one claim shape across both connection types.

​

Mapping custom claims

Once declared, an enterprise or social connection can map its own attributes/claims onto your custom claims. A mapping that references a claim name you haven’t declared is rejected - this is checked both when you save the mapping and whenever you remove a claim definition a connection still maps.

​

Enterprise connections

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Enterprise connections and open (or create) a connection.
3. Under Custom claims, add a mapping from each claim name to the SAML attribute name that should populate it.
4. Click Save.

​

Social connections

Custom claim mapping is available for custom OAuth/OIDC providers you’ve configured yourself - not the built-in providers (Apple, Discord, GitHub, Google, LinkedIn, Microsoft).

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Social connections and open (or create) a custom provider.
3. Under Custom claim mapping, add a mapping from each claim name to the provider claim that should populate it. The provider claim may be a gjson path to reach into a nested claim.
4. Click Save.

If a provider claim is itself a nested object, there’s no way to declare a custom claim that captures it as-is (see Declaring custom claims above). Instead, declare one flat claim per leaf field you need, each with its own gjson path into that object, and recompose them into a nested shape using session token customization, which does support arbitrary nested map literals with templated leaves. A mapped value that doesn’t match its claim’s declared type (e.g. a provider claim that resolves to a nested object for a claim declared as string) is silently skipped rather than blocking sign-in - see Resolving custom claims for exactly what happens to that claim’s stored value when this occurs.

​

Resolving custom claims

Resolved custom claim values are stored per user, one per project. Whichever connection a user most recently authenticated with wins for any claim it maps (last-one-wins); if that connection no longer asserts a value for a claim it maps, the claim is cleared - but only if that same connection was the one that set it, so a connection can never clear a claim it doesn’t own. This is connection-type agnostic: if you map the same claim name on both an enterprise connection and a social connection, whichever one a user most recently signed in through owns it - there’s no separate precedence between connection types. A mapped value that fails to resolve to its claim’s declared type is treated differently from a genuinely absent value: it’s skipped without clearing whatever was previously stored, since a malformed value is evidence of a mapping problem, not evidence the claim no longer applies. Resolved values are visible on a user’s detail page under Custom claims, and via the read-only Get custom claims of a user Admin API endpoint.

​

Using custom claims in JWT templates

None of your declared custom claims are added to the session JWT automatically. See Accessing custom claims for how to opt individual claims (or all of them) into your session token via session token customization.