JWT claims define the information included in your tokens. Frontegg's Token management allows you to customize which claims are included, ensuring your tokens contain exactly the information your application needs while maintaining security and compliance.
These claims are mandatory for OpenID Connect compliance and cannot be removed:
| Claim | Description | Example Value |
|---|---|---|
iss | Issuer identifier | "https://your-domain.frontegg.com" |
sub | Subject (unique user identifier) | "user-123-456" |
aud | Audience (intended recipient) | "your-client-id" or "your-app-id" |
exp | Expiration time (UNIX timestamp) | 1640995200 |
iat | Issued at time (UNIX timestamp) | 1640991600 |
Audience claim flexibility
Audience claim flexibility
The aud claim can accept either clientId or appId as valid values, providing flexibility for different integration patterns.
OIDC claims are mandatory
OIDC claims are mandatory
These OIDC claims (iss, sub, aud, exp, iat) must be included in every token template. Removing them will cause token validation failures and break authentication flows.
These claims are required for proper Frontegg functionality:
| Claim | Description | Template Variable |
|---|---|---|
type | Token type identifier | "{{type}}" |
tenantId | Associated tenant ID | "{{user.tenantId}}" |
Claim name vs template variable
Claim name vs template variable
Note that the template variable {{type}} creates a claim named type in the JWT token.
Critical for Frontegg SDKs
Critical for Frontegg SDKs
The type and tenantId claims are essential for Frontegg SDKs to function properly. If these claims are missing from your JWT:
- Frontend SDKs will fail to identify the token type and tenant context
- Backend SDKs will not be able to validate tokens correctly
- Authentication flows may break entirely
Always include these claims in your token templates.
Include user-specific information in your tokens:
| Claim | Description | Template Variable |
|---|---|---|
name | User's display name | "{{user.name}}" |
email | User's email address | "{{user.email}}" |
email_verified | Email verification status | "{{user.verified}}" |
metadata | Custom user metadata | "{{user.metadata}}" |
profilePictureUrl | User's profile picture URL | "{{user.profilePictureUrl}}" |
Include authorization information:
| Claim | Description | Template Variable |
|---|---|---|
roles | User's assigned roles | "{{user.tenant.roles}}" |
permissions | User's permissions | "{{user.tenant.permissions}}" |
Backend SDK authorization requirements
Backend SDK authorization requirements
If you're using Frontegg backend SDKs for authorization checks, the roles and permissions claims are critical:
- Backend SDKs rely on these claims to perform role-based access control (RBAC)
- Missing
rolesorpermissionsclaims will cause authorization checks to fail - Users may be denied access to resources they should have access to
Include roles and permissions claims if your backend uses Frontegg SDKs for authorization.
Include tenant-specific information:
| Claim | Description | Template Variable |
|---|---|---|
tenantIds | All user's tenant IDs | "{{user.tenantIds}}" |
Include session-specific information:
| Claim | Description | Template Variable |
|---|---|---|
sid | Session identifier | "{{sid}}" |
applicationId | Application identifier | "{{applicationId}}" |
Claim name vs template variable
Claim name vs template variable
Note that the template variable {{sid}} creates a claim named sid in the JWT token.
Previous JWT configurations will be overridden
Previous JWT configurations will be overridden
If you had previous configurations to modify JWT templates, they will be overridden once you create a template and use it in a targeting rule. The new template will replace any existing JWT customizations when applied through targeting rules.
- Navigate to your template's Claims tab
- Select claims from the available categories
- Use the template variables provided for each claim
- Preview the resulting JWT structure
- Identify claims that are not needed for your use case
- Remove them from your template (except required claims)
- Ensure that your application can handle the reduced claim set
You can customize claim values using template variables:
{
"custom_user_info": "{{user.name}} ({{user.email}})",
"tenant_context": "{{user.tenantId}}",
"user_metadata": "{{user.metadata}}"
}Frontegg protects certain internal claims that cannot be modified:
act(Actor)amr(Authentication Methods References)acr(Authentication Context Class Reference)
Internal claim override
Internal claim override
If you attempt to include internal Frontegg claims (act, amr, acr) in your template, they will be automatically overridden with Frontegg's internally generated values during token generation. Your custom values for these claims will be ignored.
Claims added via JWT generation prehooks will override template values:
- Prehook claims take precedence over template claims
- Use prehooks for dynamic claim generation
- Template claims provide the base structure
Keep token size manageable:
- Header limits: HTTP headers are typically limited to 8KB-16KB
- Performance impact: Larger tokens increase request/response times
- Network overhead: Consider bandwidth implications
Optimization strategies:
- Remove unnecessary claims
- Use shorter claim names where possible
- Consider claim value formats (arrays vs. strings)
For high-security, short-lived tokens:
{
"sub": "{{sub}}",
"aud": "{{aud}}",
"iss": "{{iss}}",
"iat": {{iat}},
"exp": {{exp}},
"type": "{{type}}",
"tenantId": "{{user.tenantId}}"
}For feature-rich applications:
{
"sub": "{{sub}}",
"name": "{{user.name}}",
"email": "{{user.email}}",
"email_verified": "{{user.verified}}",
"roles": "{{user.tenant.roles}}",
"permissions": "{{user.tenant.permissions}}",
"tenantId": "{{user.tenantId}}",
"aud": "{{aud}}",
"iss": "{{iss}}",
"iat": {{iat}},
"exp": {{exp}},
"type": "{{type}}"
}For third-party API integrations:
{
"sub": "{{sub}}",
"email": "{{user.email}}",
"tenantId": "{{user.tenantId}}",
"permissions": "{{user.tenant.permissions}}",
"aud": "{{aud}}",
"iss": "{{iss}}",
"iat": {{iat}},
"exp": {{exp}},
"type": "{{type}}"
}Testing your claims
Testing your claims
Ensure all required claims are present before saving your template. Templates cannot be saved without including the mandatory OIDC and Frontegg required claims.