Skip to content
Security management/
/
Templates
Last updated

Token template management

Token templates allow you to customize JWT structure, claims, and behavior for different use cases. You can create multiple templates and apply them conditionally based on user attributes, token types, or other criteria.

Creating token templates

Accessing token templates

  1. Navigate to [ENVIRONMENT] → Security → Token management
  2. Click Create Template to start creating a new template

jwt-templates-1

Template configuration

Basic settings

Template type

Choose your starting point:

Template information

  • Name: Descriptive name for your template
  • Description: Optional description explaining the template's purpose
  • Template key: Unique identifier (must be unique across your environment)

Security settings

Token expiration

  • Default: 300 seconds
  • Configure based on your security requirements
  • Shorter expiration times provide better security but may require more frequent token refreshes

JWT signing algorithm

  • RS256 (recommended): Asymmetric algorithm using RSA keys
  • HS256: Symmetric algorithm using shared secrets

JWT public key

  • Configure the public key for token verification
  • Required for RS256 algorithm

Template types

Frontegg default JWT template

When starting from the Frontegg default, your template includes these claims:

{
  "sub": "{{sub}}",
  "name": "{{user.name}}",
  "email": "{{user.email}}",
  "email_verified": "{{user.verified}}",
  "metadata": "{{user.metadata}}",
  "roles": "{{user.tenant.roles}}",
  "permissions": "{{user.tenant.permissions}}",
  "tenantId": "{{user.tenantId}}",
  "tenantIds": "{{user.tenantIds}}",
  "profilePictureUrl": "{{user.profilePictureUrl}}",
  "sid": "{{sid}}",
  "type": "{{type}}",
  "applicationId": "{{applicationId}}",
  "aud": "{{aud}}",
  "iss": "{{iss}}",
  "iat": {{iat}},
  "exp": {{exp}}
}

This matches the default Frontegg JWT structure that serves as the fallback when no custom templates are applied.

Blank template

When starting from blank, your template includes only required claims:

{
  "sub": "{{sub}}",
  "aud": "{{aud}}",
  "iss": "{{iss}}",
  "iat": {{iat}},
  "exp": {{exp}}
}

Managing existing templates

Template list view

The main Token management page displays all templates in a table with:

  • Template name: The display name of the template
  • Description: Template description (if provided)
  • Key: Unique template identifier
  • Expiration: Token expiration time in seconds
  • Created: Template creation date

Editing templates

  1. Click on any template row to open the template details page
  2. Modify template settings, claims, or targeting rules
  3. Click Save to apply changes

Deleting templates

Template deletion rules:

  • Templates currently used in targeting rules cannot be deleted
  • A tooltip will indicate if deletion is disabled due to active usage
  • If deletion is available, a confirmation modal will appear

To delete a template:

  1. Click the Delete button next to the template
  2. If the template is not in use, confirm deletion in the modal
  3. The template will be permanently removed

Template validation

Required claims validation

Templates must include these OIDC-required claims:

  • iss (Issuer): Identifier for the token issuer
  • sub (Subject): Unique identifier for the authenticated user
  • aud (Audience): Intended recipient(s) of the token
  • exp (Expiration Time): Token expiration timestamp
  • iat (Issued At): Token issuance timestamp

Frontegg required claims

For proper Frontegg integration, include:

  • type: Token type identifier
  • tenantId: Associated tenant identifier

Template requirements

Before saving your template, ensure:

  1. All required OIDC claims are included (iss, sub, aud, exp, iat)
  2. Frontegg required claims are present (type, tenantId)
  3. Template syntax is correct and uses valid template variables
  4. Templates cannot be saved without meeting these requirements

Session settings

Configure how tokens are handled in browser sessions:

  • Secure cookies: Ensure cookies are only sent over HTTPS
  • SameSite policy: Control cross-site request behavior
  • HttpOnly: Prevent client-side JavaScript access to tokens

Token expiration (refresh)

Default refresh token expiration: 86400 seconds (24 hours)

Configure refresh token behavior:

  • Rotation: Whether refresh tokens are rotated on use
  • Maximum lifetime: Maximum time a refresh token remains valid
  • Sliding expiration: Whether token lifetime extends with use

Template usage tracking

Before deleting a template, ensure it's not referenced in any targeting rules. Active templates cannot be deleted to prevent authentication failures.


Template fallback

If a template becomes corrupted or unavailable, Frontegg automatically falls back to the default JWT structure to ensure continuous authentication.