How to expose custom claims in okta-auth-js AccessToken?

[EricL_BG]

We are using @okta/okta-auth-js version 7.5.1 for a react 18 app. Our security team is helping us configure the access token with the claims we need. This is what they look like

But the AccessToken type is defined with claims as UserClaims and they look like:

export declare type UserClaims<T extends CustomUserClaims = CustomUserClaims> = T & {
    auth_time?: number;
    aud?: string;
    email?: string;
    email_verified?: boolean;
    exp?: number;
    family_name?: string;
    given_name?: string;
    iat?: number;
    iss?: string;
    jti?: string;
    locale?: string;
    name?: string;
    nonce?: string;
    preferred_username?: string;
    sub: string;
    updated_at?: number;
    ver?: number;
    zoneinfo?: string;
    at_hash?: string;
    acr?: string;
};

I tried to use module augmentation in TypeScript to overrride the claims prop on the AccessToken interface, but it’s complaining that Subsequent property declarations must have the same type. Property 'claims' must be of type 'UserClaims', but here has type 'UserClaims<{ firstName: string; lastName: string; }>'. My module augmentation looks like:

import "@okta/okta-auth-js";
import { UserClaims } from "@okta/okta-auth-js";

declare module "@okta/okta-auth-js" {
    interface AccessToken {
        claims: UserClaims<{ firstName: string; lastName: string }>;
    }
}

I can of course force the type conversion where I access the claims, but I was hoping to clearly define those claims for the next person.

Am I just doing something wrong? any recommendation how to properly type those access token claims?

[andrea]

If your code is going the be reliant on the claims within the Access Token, you really should be validating the tokens first. Access Token validation is usually only completed at the server receiving these tokens as authorization (e.g. an API endpoint protected by these access tokens) and wouldn’t be read client-side (the ID token would be instead).

Are you trying to read these claims from the client side (within your React app) or from the server side (the receiving resource server)?

[EricL_BG]

Thanks for the info. We are enforcing actual security server-side with the Access Token. However, the access token contains claims about sub-resources the user has access to. We would like to avoid making an extra API call if we don’t have to, to parse those claims and provide a summary of the subresources the user has access to.
Our current solution, not using Okta, uses the additional API call. As we upgrade to Okta, we want to review all our API calls and make sure they are still necessary.
So, while not critical to get properly typed claims client-side, it would just be nice.