Custom Claim

Overview

LoginRadius now supports enriching JWT access tokens and ID tokens with custom claims. These claims allow you to embed additional user, session, or contextual metadata directly into tokens during OAuth 2.0 and OpenID Connect (OIDC) flows.

By injecting custom claims at authentication time, downstream applications—such as APIs, gateways, or microservices—can make authorization decisions without extra API calls, improving performance, scalability, and flexibility.

Custom claims are generated through Script-Based Injection.

Use Cases

Role-Based Access Control (RBAC): Embed user roles or group memberships directly into the token to drive fine-grained access control in downstream services.
Session Context: Include session-specific data (e.g., login time, device ID) to enforce policies like session expiration or device-based access.
Custom Authorization Logic: Derive and inject claims based on custom business rules using scripts, for example, marking VIP users or enforcing region-specific restrictions.
Reduced Latency for API Gateways: Allow API gateways and services to authorize requests without making extra calls to identity or profile APIs.

Key Features

Seamless Integration with OAuth/OIDC Flows Custom scripts are executed automatically during authentication when configured in the orchestration workflow.
Dynamic Claims Logic Supports complex logic using JavaScript (Node.js), including conditional rules, external API calls, and custom computations.
Claims Injected at Token Generation Time Custom claims are evaluated and included at the final stage of token generation, ensuring up-to-date and context-aware data.

Configurations

Orchestration supports OIDC and OAuth 2.0, and with the IO scripts, you can add custom claims to JWT tokens dynamically. Follow the steps below:

Create Application:
- Navigate to Applications.
- Create a new OIDC/OAuth application using the Add Apps button or select an existing application.
- Store the client ID, client secret, and application name.

Create a script to set custom claims:

Go to Orchestration > Scripts
Click on + New Script and set the script name.
Create a script as per your requirements and set custom claims in access_token and/or idToken using hook.accessToken.setCustomClaim() and hook.idToken.setCustomClaim() and save.

Below is a script for your reference

const axios = require('axios');

exports.execute = async (lrObject, hook) => {
    try {
        const response = await axios.get('https://blue-truth-6f59.mayankagrwal.workers.dev/');
        if (response){
            var role = response.data?.role;
            var permissions = response.data?.permissions;
            if (role) {
                hook.accessToken.setCustomClaim('role', role);
                hook.idToken.setCustomClaim('role', role);
            }
            if (permissions && permissions.length) {
                hook.accessToken.setCustomClaim('permissions', permissions.join(","));
                hook.idToken.setCustomClaim('permissions', permissions.join(","));
            }
        }
    } catch (error) {
        hook.setError('500', 'API Error', error.message);
    }
};

For more information on scripts, refer to this

Create IO Workflow:
- Navigate to Orchestration > Workflow
- Create a new workflow by clicking on New Workflow. Or select an existing one.
- From the left panel, drag and drop the Scripts node under Helper Nodes, then place it after the Auth node.
- Click the Script node, then select the script name set in step 1.
- Once done, save and update the workflow

How it works:

Initiate login

Use the /authorize endpoint to start OIDC authorization.
Provide workflow, client ID, and OIDC app name as shown below.

https://<siteUrl>/service/oidc/<AppName>/authorize
?client_id=<clientID>
&redirect_uri=http%3A%2F%2Flocalhost%3A3000
&response_type=code
&scope=openid%20email%20profile
&state=<random>
&workflow=<workflowName>
&debugmode=false

Once the user logs in, the script executes and injects custom claims into the token payload.

Exchange code for tokens

Use the /token endpoint to exchange the code received from Step 1. For example

curl --location 'https://<site url>/api/oidc/<OIDC App name>/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id":"<client ID>",
"client_secret":"<client secret>",
"redirect_uri":"http://localhost:3000",
"response_type":"token",
"grant_type":"authorization_code",
"code":"<code>"
}'

The resulting access_token and id_token will now include custom claims. For more information, refer to this.

Best Practices

Handle Errors Gracefully: Use hook.setError to handle validation or execution errors.
Always Validate Input: Ensure that fields like lrObject.Identity.Email exists before accessing them to avoid runtime errors.
Don't expose client secret: Always use the client secret in your backend server to avoid data breaches and security issues.