JWTs (JSON Web Tokens) are a common method for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. With Authgear, it is straightforward to add custom fields to your JWT access tokens.

This how-to guide will walk you through the process of adding custom fields such as User Profiles attributes to a JWT access token payload using Authgear and Javascript Hooks.

Here's an example of the fields in the JWT Access Tokens by default and an explanation of their values.

Prerequisites

• An Authgear account: You need an Authgear account to follow this guide. If you don't have one, you can create it for free on the Authgear website.

• A Registered App: You need a registered application (client) in Authgear.

Enable Access Token for your App

Make sure the option Issue JWT as access token is enabled in your Application settings in the Portal.

1. Log into your Authgear account.

2. Navigate to the Applications tab and choose the existing App.

3. On the App Configuration dashboard, locate the "Access token" section.

4. Make the toggle Issue JWT as access token switch on.

Create a new Event Hook

With the use of Hooks, Authgear provides flexibility for adding custom logic to your authentication pipeline. You can create a Hook which is triggered any of these Events about to occur. For example, oidc.jwt.pre_create the event happens just before issuing the JWT access token and it can be used to put extra information into the token.

1. Navigate to your Authgear Dashboard's Advanced->Hooks section.

2. Add a new Blocking Event.

3. Choose the Block Hook Type as the TypeSctipt and set the Event option to JWT access token pre-create. You will write a new Typescript function from scratch.

4. Click on Edit Script under the Config option.

5. Copy and paste the following into the editor:

import { EventOIDCJWTPreCreate, HookResponse } from "https://deno.land/x/authgear_deno_hook@v1.0.0/mod.ts";

export default async function(e: EventOIDCJWTPreCreate): Promise<HookResponse> {
  return {
    mutations:{
      jwt: {
        payload:{
          ...e.payload.jwt.payload,
          standard_attributes: e.payload.user.standard_attributes,
          custom_attributes: e.payload.user.custom_attributes
        }
      }
    },
    is_allowed: true
  };
}

6. Click on Finish Editing.

7. Back to the Hooks page from the navigation bar and click on the Save button at the top of the page.

In the above code, we are importing the necessary modules such as HookResponse and EventOIDCJWTPreCreate which are types from the Authgear Deno hook Typescript library. We modify the JWT payload by adding Standard Attributes(e.payload.user.standard_attributes) and Custom Attributes(e.payload.user.custom_attributes) of the user.

Verify the Custom Field in a JWT token

There are two ways to test it:

• You can do this by decoding the JWT token on your application server side using a JWT decoder and inspecting the payload.

• If you created the application type OIDC Client Application, you need to follow the steps below. Expand it to see instructions.

https://<YOUR_AUTHGEAR_ENDPOINT>/oauth2/authorize?client_id={YOUR_CLIENT_ID}&response_type=code&scope=openid

curl --request POST \
  --url 'https://<YOUR_AUTHGEAR_ENDPOINT>/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data code={YOUR_AUTHORIZATION_CODE} \
  --data redirect_uri={YOUR_REDIRECT_URI} \
  --data 'client_id={YOUR_CLIENT_ID}' \
  --data client_secret={YOUR_CLIENT_SECRET} \
  --data scope=openid