Tutorial - Customize tokens using workflows

Use workflows to add or remove claims from Kinde’s access or ID tokens.

What you need

Link to this section

• A Kinde account (Sign up for free)
• A workflow Git repository connected to your Kinde account (use the workflow base template)

Customize the access token

Link to this section

Add a custom claim

Link to this section

1. Add the following code to your Workflow.ts file:

   Workflow.ts

   import {
     onUserTokenGeneratedEvent,
     WorkflowSettings,
     WorkflowTrigger,
     accessTokenCustomClaims,
   } from "@kinde/infrastructure";
   
   // The setting for this workflow
   export const workflowSettings: WorkflowSettings = {
     id: "addCustomClaimWorkflow",
     name: "Add Custom Claim Workflow",
     trigger: WorkflowTrigger.UserTokenGeneration,
     failurePolicy: {
       action: "stop",
     },
     bindings: {
       "kinde.accessToken": {}, // required to modify access token claims
       url: {}, // required for URL parameters
     },
   };
   
   // The workflow code to be executed when the event is triggered
   export default async function Workflow(event: onUserTokenGeneratedEvent) {
     const accessToken = accessTokenCustomClaims<{
       companyName: string,
     }>()
   
     accessToken.companyName = "Acme Inc."
   }

The above code adds the companyName claim to the access token, with the value Acme Inc..

Remove claims

Link to this section

1. Add the following code to your Workflow.ts file:

   Workflow.ts

   import {
     onUserTokenGeneratedEvent,
     WorkflowSettings,
     WorkflowTrigger,
     accessTokenCustomClaims,
   } from "@kinde/infrastructure";
   
   // The setting for this workflow
   export const workflowSettings: WorkflowSettings = {
     id: "removeClaimWorkflow",
     name: "Remove Claim Workflow",
     trigger: WorkflowTrigger.UserTokenGeneration,
     failurePolicy: {
       action: "stop",
     },
     bindings: {
       "kinde.accessToken": {}, // required to modify access token claims
       url: {}, // required for URL parameters
     },
   };
   
   // The workflow code to be executed when the event is triggered
   export default async function Workflow(event: onUserTokenGeneratedEvent) {
     const accessToken = accessTokenCustomClaims<{
       permissions: string[],
       feature_flags: Record<string, unknown>,
     }>()
   
     accessToken.permissions = []
     accessToken.feature_flags = {}
   }

The above code removes the permissions and feature_flags claims from the access token, replacing them with an empty array and object respectively. This is useful for reducing the size of access tokens that are used in API calls.

Take a look at the available access token claims in the about access tokens doc. You may not be able to remove every default claim. See the prohibited claims section for more information.

Customize the ID token

Link to this section

1. Add the following code to your Workflow.ts file:

   Workflow.ts

   import {
     onUserTokenGeneratedEvent,
     WorkflowSettings,
     WorkflowTrigger,
     idTokenCustomClaims,
   } from "@kinde/infrastructure";
   
   // The setting for this workflow
   export const workflowSettings: WorkflowSettings = {
     id: "customIdTokenClaimsWorkflow",
     name: "Custom ID Token Claims Workflow",
     trigger: WorkflowTrigger.UserTokenGeneration,
     failurePolicy: {
       action: "stop",
     },
     bindings: {
       "kinde.idToken": {}, // required to modify ID token claims
       url: {}, // required for URL parameters
     },
   };
   
   // The workflow code to be executed when the event is triggered
   export default async function Workflow(event: onUserTokenGeneratedEvent) {
     const idToken = idTokenCustomClaims<{
       house: string,
       name: string,
     }>()
   
     idToken.house = "Gryffindor"
     idToken.name = "Harry Potter"
   }

The above code adds a custom house claim to the ID token and updates the name claim as shown.

Take a look at the available ID token claims in the about ID tokens doc. You may not be able to modify every default claim. See the prohibited claims section for more information.

Glossary

Link to this section

Required bindings

Link to this section

Declare the token binding that matches the JWT you are modifying:

• kinde.accessToken: required to modify access token claims
• kinde.idToken: required to modify ID token claims
• kinde.m2mToken: required to modify M2M token claims

The workflow examples on this page also declare the native url binding (for URL parameters).

Prohibited claims

Link to this section

You can’t modify the following token claims:

Common prohibited claims:

• azp
• exp
• iat
• iss
• nbf
• sid
• sub
• act
• aud

Access token prohibited claims:

• jti
• scp

ID token prohibited claims:

• auth_time
• jti
• updated_at
• rat

M2M token prohibited claims:

• gty
• jti
• scp