This article explains the constraints of the sub (subject) claim within Identity (ID) and Access Tokens. It outlines standard system behavior and provides a practical workaround for requirements that necessitate a custom username.

• Sub claim
• ID token
• Access token
• Custom Authorization Server
• Group-based Application Assignment

The sub claim in an ID Token is a reserved system claim that defaults to the Okta User Identification (ID) and cannot be modified. While the sub claim in an Access Token can be modified using a Custom Authorization Server (CAS), creating a new custom claim in both tokens is the recommended approach to ensure consistency.

Follow these steps to create a custom claim:

1. Go to Security > API > Authorization Servers.
2. Select the appropriate Custom Authorization Server.
3. Navigate to the Claims tab and click Add Claim.
4. Create a claim (for example, test_username) for the ID Token:
   1. Include in token type: ID Token.
   2. Value type: Expression.
   3. Value: user.login.
5. Create the same claim for the Access Token:
   1. Include in token type: Access Token.
   2. Value: user.login.
6. Update the external application configuration to utilize this new claim instead of sub or uid.

Related References

• Customize tokens returned from Okta with custom claims
• Create API access claims