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
hubuseridcustom field, rather than the LoginRadiusUid. - Opaque subjects: Send an encrypted or pseudonymous
subinstead 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
audso 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.
- Opt each app in from the Admin Console. Turn on Enable registered claim override and select which of
sub,iss, andaudeach token type may override. - Supply the values with a mapping template (static values or profile placeholders) or an Identity Orchestration Custom Script (values computed at login).
- Tokens are issued with the overrides from
/authorize,/token(including refresh), and/userinfo./introspectreturns 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.
- In the Registered claim override section of your OAuth 2.0 or OIDC app, turn on Enable registered claim override, then select
subunder Access token claims and ID token claims. - In Access token mapping template and ID token mapping template, enter
{ "sub": "{{CustomField.hubuserid}}" }. - Save the app, sign in, and decode the tokens to confirm
subholds the user'shubuseridvalue.
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
| Claim | Access Token | ID Token |
|---|---|---|
sub | Yes (not for pairwise apps) | Yes (not for pairwise apps) |
iss | Yes | Yes |
aud | Yes | Yes |
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:
- 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.
- 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
tierorentitlements, 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.
| Source | Access Token | ID Token |
|---|---|---|
| Mapping template on the OAuth 2.0 or OIDC app | Access token mapping template | ID token mapping template |
| Identity Orchestration workflow Custom Script | hook.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.
- Turn on Enable registered claim override. This master switch lets the selected registered claims be replaced with values set when the token is issued.
- In Access token claims (optional), select the claims the Access Token may override:
sub,aud, oriss. - In ID token claims (optional), select the claims the ID Token may override:
sub,aud, oriss. - 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.
subcan 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.
- Confirm that mapping templates are enabled for your tenant. They are on by default for new tenants.
- 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.
- 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.
- 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:
- Turn on Enable registered claim override.
- Under Access token claims, select
sub. - 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:
- Turn on Enable registered claim override.
- Under Access token claims, select
sub,iss, andaud. - Under ID token claims, select
sub,iss, andaud.
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.
- Confirm that Identity Orchestration is enabled for your tenant.
- Create a Custom Script that sets the claims, as shown in the examples below.
- Create a workflow with a Custom Script node that runs the script after authentication.
- 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.
- In the app's settings, select the workflow as the app's Default workflow so
/authorizeruns it. Mapping templates are not required. - 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:
- Under Default workflow, select the workflow that runs the script below.
- Under Registered claim override, turn on Enable registered claim override.
- Under Access token claims, select
sub. - 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.
| Claim | Accepted value | Notes |
|---|---|---|
sub | Non-empty string (whitespace trimmed) | Ignored for pairwise apps. The pairwise subject is derived per sector and always wins. |
iss | Non-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. |
aud | String or array of strings | Blank 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"]
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.
| Scenario | Outcome |
|---|---|
Template or script sets sub, iss, and aud, but only sub is selected for the app | sub 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 in | No registered claim is overridden. The app opt-in is ignored. |
Pairwise app with sub opted in | The pairwise sub is kept. The override is ignored. |
Access Token aud override without api://authentication | Token is issued. LoginRadius /userinfo rejects it and /introspect returns { "active": false }. |
| Allowed claim with an invalid value type | Token request fails with server_error. |
| Custom claims with the tenant-level feature off | Custom 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, oraudrequires 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:
subis never overridden for pairwise apps, so subject identifiers stay unlinkable across sectors. - Treat
issandaudoverrides as trust-boundary changes: Resource servers that validateissagainst the LoginRadius discovery document, oraudagainst 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://authenticationin the Access Tokenaud: 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.