loading
Preparing LoginRadius developer resources
Mission: Help enterprises accelerate digital transformation with our fully-managed Customer IAM technology.
Skip to main content

Override Registered Claims

By default, LoginRadius sets the registered JWT claims in the tokens it issues. sub is the user's LoginRadius identifier, iss is your LoginRadius tenant, and aud is the default audience for the token. With Registered Claim Override, you replace sub, iss, and aud with your own values in the Access Tokens and ID Tokens issued to your OAuth 2.0 and OIDC apps. You can also add custom claims to those tokens.

Use Registered Claim Override for the following cases:

  • External subject identifiers: Downstream systems identify users by their own ID, such as a hubuserid custom field, rather than the LoginRadius Uid.
  • Opaque subjects: Send an encrypted or pseudonymous sub instead of the raw user ID.
  • Custom issuer: Relying parties expect a specific issuer URL in iss.
  • Your own audiences: Access Tokens list your APIs in aud so your resource servers accept them.
  • Richer tokens: Add extra claims, such as entitlements, tiers, or nested objects, to the token.

How it works

Registered claims are overridden only when both the tenant-level feature and the per-app selection allow it, as described in Required settings. Any other override is ignored, and invalid values fail the token request rather than issuing an incorrect token.

  1. Opt each app in from the Admin Console. Turn on Enable registered claim override and select which of sub, iss, and aud each token type may override.
  2. Supply the values with a mapping template (static values or profile placeholders) or an Identity Orchestration Custom Script (values computed at login).
  3. Tokens are issued with the overrides from /authorize, /token (including refresh), and /userinfo. /introspect returns the claims as issued.

Quick start

The steps below set sub to a custom field value in both the Access Token and the ID Token. They assume the tenant-level feature is already enabled, as described in Required settings.

  1. In the Registered claim override section of your OAuth 2.0 or OIDC app, turn on Enable registered claim override, then select sub under Access token claims and ID token claims.
  2. In Access token mapping template and ID token mapping template, enter { "sub": "{{CustomField.hubuserid}}" }.
  3. Save the app, sign in, and decode the tokens to confirm sub holds the user's hubuserid value.

Claims and prerequisites

Only three registered claims can be overridden, and only when two separate settings allow it. Custom claims are not subject to these restrictions.

Claims you can override

ClaimAccess TokenID Token
subYes (not for pairwise apps)Yes (not for pairwise apps)
issYesYes
audYesYes

No other registered or reserved claim can be overridden. These include exp, iat, nbf, jti, azp, cnf, scope, client_id, act, authorization_details, and similar claims. If a template or script sets one of them, LoginRadius ignores it.

Required settings

Overriding sub, iss, or aud requires both of the following settings:

  1. Tenant-level enablement: The OAuth Registered Claim Override feature is enabled for your LoginRadius tenant. The feature is off by default. Contact LoginRadius Support to enable it.
  2. App-level opt-in: Each OAuth 2.0 or OIDC app explicitly allows the claims it may override, separately for Access Tokens and ID Tokens.

If either setting is off, LoginRadius silently drops any sub, iss, or aud value from a template or script and keeps the default value.

Custom claims are not gated. Non-reserved claims, such as tier or entitlements, are added to the token even when the feature is off or the app has not opted in. A custom claim cannot change how the token's subject, issuer, or audience is identified.

Override value sources

Override values come from a mapping template, an Identity Orchestration workflow script, or both. Each token type is configured separately, so the Access Token and ID Token can carry different values.

SourceAccess TokenID Token
Mapping template on the OAuth 2.0 or OIDC appAccess token mapping templateID token mapping template
Identity Orchestration workflow Custom Scripthook.accessToken.setField(name, value)hook.idToken.setField(name, value)

If a mapping template and a workflow script set the same claim, the workflow script value wins.

Values set by a workflow script are kept with the user's session. They also apply to tokens issued later for the same app, such as on a refresh_token grant.

Configure the app

The Registered claim override section of the app settings controls which registered claims each token type may override. Open your OAuth 2.0 or OIDC app's settings in the Admin Console and complete the following steps.

  1. Turn on Enable registered claim override. This master switch lets the selected registered claims be replaced with values set when the token is issued.
  2. In Access token claims (optional), select the claims the Access Token may override: sub, aud, or iss.
  3. In ID token claims (optional), select the claims the ID Token may override: sub, aud, or iss.
  4. Save the app.

Selecting a claim only makes it eligible for override. The value itself comes from a mapping template or an Identity Orchestration script. A registered claim set by a template or script but not selected here is dropped, and the default value is kept.

  • Leave a list empty to allow no overrides for that token type.
  • Turning the switch off disables all overrides for the app but keeps your claim selections.
  • sub can be selected for any subject type, but LoginRadius ignores it for pairwise apps.
  • If the tenant-level feature is turned off, LoginRadius ignores existing app opt-ins when issuing tokens and clears them the next time the app is saved.

Use mapping templates

Each OAuth 2.0 or OIDC app has an Access token mapping template and an ID token mapping template. Each template is a JSON payload rendered for every token issued. {{Field}} placeholders resolve against the user's profile, such as {{Uid}} or {{CustomField.hubuserid}}.

Set up mapping templates

Complete the following steps to override claims with a mapping template.

  1. Confirm that mapping templates are enabled for your tenant. They are on by default for new tenants.
  2. In the app's Registered claim override section, turn on Enable registered claim override and select every registered claim the template sets under Access token claims and ID token claims. A registered claim in the template that is not selected is dropped.
  3. In the app's Access token mapping template and ID token mapping template sections, enter the claims in the JSON Editor, as shown in the examples below.
    • To insert a profile placeholder, click a field under Standard fields, such as + Uid, or expand Custom fields and click a custom field, such as hubuserid.
    • Non-reserved keys, such as token_type, are added to the token as custom claims.
  4. Save the app.

Example: override sub only

The example below replaces sub with the user's hubuserid custom field in both tokens. Configure Registered claim override as follows:

  1. Turn on Enable registered claim override.
  2. Under Access token claims, select sub.
  3. Under ID token claims, select sub.

Enter the following JSON in the JSON Editor of both the Access token mapping template and the ID token mapping template:

{
"sub": "{{CustomField.hubuserid}}"
}

sub now holds the user's hubuserid value in the Access Token, the ID Token, /userinfo, and /introspect. LoginRadius still associates the token with the real user, so LoginRadius APIs that accept the Access Token keep working.

Example: override sub, iss, and aud

The example below sets all three registered claims in both tokens. Configure Registered claim override as follows:

  1. Turn on Enable registered claim override.
  2. Under Access token claims, select sub, iss, and aud.
  3. Under ID token claims, select sub, iss, and aud.

Enter the following JSON in the JSON Editor of the Access token mapping template:

{
"sub": "{{CustomField.hubuserid}}",
"iss": "https://at.issuer.example.com",
"aud": ["api://authentication", "https://api.example.com"]
}

Set the ID token mapping template the same way, using the issuer and audiences your ID Token relying parties expect. The ID Token aud does not need api://authentication.

Both tokens, /userinfo, and /introspect carry the template values. The Access Token aud keeps api://authentication, so LoginRadius still accepts the token. The override also works when the Access Token is issued as an encrypted JWT (JWE), and the overridden values are visible through /introspect.

Use an Identity Orchestration script

An Identity Orchestration workflow can run a Custom Script node after the user authenticates. The script sets claims with hook.accessToken.setField(name, value) and hook.idToken.setField(name, value).

Set up the workflow script

Complete the following steps to override claims with a workflow script.

  1. Confirm that Identity Orchestration is enabled for your tenant.
  2. Create a Custom Script that sets the claims, as shown in the examples below.
  3. Create a workflow with a Custom Script node that runs the script after authentication.
  4. In the app's Registered claim override section, turn on Enable registered claim override and select every registered claim the script sets under Access token claims and ID token claims. A registered claim that is not selected is dropped.
  5. In the app's settings, select the workflow as the app's Default workflow so /authorize runs it. Mapping templates are not required.
  6. Save the app.

Example: override sub with an opaque identifier

The example below sets sub to the user's Uid, encrypted with AES-256-CBC and base64url-encoded, so downstream systems receive an opaque identifier. iss and aud keep their default values. Configure the app in the Admin Console as follows:

  1. Under Default workflow, select the workflow that runs the script below.
  2. Under Registered claim override, turn on Enable registered claim override.
  3. Under Access token claims, select sub.
  4. Under ID token claims, select sub.
const crypto = require("crypto");
const ALGORITHM = "aes-256-cbc";
const KEY_LENGTH = 32; // 32 bytes = 256 bits
const IV_LENGTH = 16; // 16 bytes = 128 bits
// Placeholders only. Never hardcode a real key or IV in a script;
// load them from your secure configuration.
const encKey = "<base64-encoded 32-byte key>";
const iv = "<base64-encoded 16-byte IV>";

function encrypt(value, encKey, iv) {
const key = Buffer.from(encKey, "base64");
const initializationVector = Buffer.from(iv, "base64");
if (key.length !== KEY_LENGTH) {
throw new Error("AES-256-CBC requires a 32-byte key");
}
if (initializationVector.length !== IV_LENGTH) {
throw new Error("AES-256-CBC requires a 16-byte IV");
}
const cipher = crypto.createCipheriv(ALGORITHM, key, initializationVector);
const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
return encrypted.toString("base64url");
}

exports.execute = async (lrObject, hook) => {
try {
if (lrObject.IsAuthenticated && lrObject.Identity?.Uid) {
const encryptedSubValue = encrypt(lrObject.Identity.Uid, encKey, iv);
hook.accessToken.setField("sub", encryptedSubValue);
hook.idToken.setField("sub", encryptedSubValue);
}
} catch (error) {
hook.setError(500, "API Error", error.message);
}
};

Both tokens, /userinfo, and /introspect carry the encrypted sub. LoginRadius still associates the token with the real user, so LoginRadius APIs that accept the Access Token keep working. To also override iss or aud, call setField for those claims and select them under Access token claims and ID token claims.

Example: add custom claims

Custom (non-reserved) claims require only the workflow selected as the app's Default workflow. Registered claim override and the tenant-level feature are not required. Values must be JSON-safe types: string, boolean, finite number, array, or plain object.

const accessTokenClaims = {
loyalty_tier: "gold",
marketing_opt_in: true,
entitlements: ["reports:read", "reports:export"],
billing_address: { city: "Pune", country: "IN", geo: { verified: true, zones: ["west", "metro"] } }
};
const idTokenClaims = {
preferred_store: "store-411001",
newsletter_subscribed: false,
interests: ["identity", "security"],
profile_meta: { source: "workflow-script", tags: ["beta"], flags: { kyc_done: true } }
};

exports.execute = async (lrObject, hook) => {
try {
if (lrObject.IsAuthenticated && lrObject.Identity?.Uid) {
for (const [claim, value] of Object.entries(accessTokenClaims)) {
hook.accessToken.setField(claim, value);
}
for (const [claim, value] of Object.entries(idTokenClaims)) {
hook.idToken.setField(claim, value);
}
// A claim derived from the logged-in user.
hook.accessToken.setField("user_ref", "at-" + lrObject.Identity.Uid);
hook.idToken.setField("user_ref", "idt-" + lrObject.Identity.Uid);
}
} catch (error) {
hook.setError(500, "API Error", error.message);
}
};

You can combine registered claim overrides and custom claims in one script. Registered claims follow the rules above, and custom claims are always added.

Value rules

LoginRadius validates each override value when the token is issued, not when the app is saved. The table below lists the accepted value for each claim.

ClaimAccepted valueNotes
subNon-empty string (whitespace trimmed)Ignored for pairwise apps. The pairwise subject is derived per sector and always wins.
issNon-empty string (whitespace trimmed)Replaces the default LoginRadius issuer. Relying parties that validate iss against the LoginRadius discovery document reject the token unless they are configured to accept the overridden value.
audString or array of stringsBlank entries are removed, and at least one value is required. The override replaces the default audience rather than adding to it. For Access Tokens, include api://authentication.

Invalid values

If an allowed claim has the wrong type or is empty, the token request fails instead of issuing a partial token. Examples of invalid values include {"sub": 12345}, {"sub": ["value"]}, {"iss": {"url": "..."}}, {"aud": []}, and {"aud": ["https://a.example.com", 12345]}. LoginRadius returns the following error:

{
"error": "server_error",
"error_description": "An override claim for a registered JWT claim (sub, aud, iss) has an invalid value type."
}

Fix the template or script to resolve the error.

Keep api://authentication in the Access Token audience

The default Access Token audience is api://authentication, and LoginRadius requires it whenever it validates its own Access Tokens. If your override leaves it out, the token is still issued and your own resource servers can accept it, but LoginRadius rejects it.

To keep the token working with LoginRadius, include api://authentication alongside your own audiences:

"aud": ["api://authentication", "https://api.example.com"]
warning

LoginRadius does not enforce this requirement when you save the app or when the token is issued. Including api://authentication is recommended in every Access Token aud override. The ID Token aud has no such requirement.

Behavior reference

The table below summarizes the outcome for common configuration combinations.

ScenarioOutcome
Template or script sets sub, iss, and aud, but only sub is selected for the appsub is overridden. iss and aud keep their defaults.
Enable registered claim override turned off for the app (claim selections kept)No registered claim is overridden.
Tenant-level feature turned off after the app opted inNo registered claim is overridden. The app opt-in is ignored.
Pairwise app with sub opted inThe pairwise sub is kept. The override is ignored.
Access Token aud override without api://authenticationToken is issued. LoginRadius /userinfo rejects it and /introspect returns { "active": false }.
Allowed claim with an invalid value typeToken request fails with server_error.
Custom claims with the tenant-level feature offCustom claims are added. Registered claims are not overridden.

Security considerations

Overriding registered claims changes how relying parties identify the subject, issuer, and audience of a token. Review the following controls before enabling the feature.

  • Deny by default: Overriding sub, iss, or aud requires both the tenant-level feature and an explicit per-app opt-in, and all other registered claims can never be overridden.
  • Pairwise subjects are preserved: sub is never overridden for pairwise apps, so subject identifiers stay unlinkable across sectors.
  • Treat iss and aud overrides as trust-boundary changes: Resource servers that validate iss against the LoginRadius discovery document, or aud against their own identifier, reject the token unless they are configured for the overridden values, so coordinate with every relying party before enabling the override.
  • Keep api://authentication in the Access Token aud: Include it whenever LoginRadius endpoints must also accept the token.
  • Fail closed: An invalid override fails the token request rather than issuing a partial or incorrect token.
  • Audit every override: LoginRadius records every registered claim override (token type, claim, and value) in your tenant's audit logs.