Auth0 JSON Web Tokens Ignore Modifications to the Standard Sub Claim

Administrators integrating Auth0 with third-party applications often attempt to mask Personally Identifiable Information (PII) by overriding the standard sub and email claims in the generated Identity JSON Web Token (JWT). Auth0 restricts the sub claim to maintain OpenID Connect (OIDC) compliance, but administrators can inject new custom claims that use a Uniform Resource Identifier (URI) namespace prefix using a Post-Login Action. When an administrator attempts to modify the sub claim using an Auth0 Action, Auth0 silently ignores the change, and the token retains the original Auth0-generated user identifier.

• Auth0
• JSON Web Tokens (JWT)
• Post-Login Actions
• OpenID Connect (OIDC)

Auth0 classifies the sub claim as a strictly restricted claim. To maintain system integrity and strict compliance with the OpenID Connect (OIDC) specification, Auth0 explicitly blocks modifications or overrides to the sub claim via Actions or Rules. Standard methods like api.idToken.setCustomClaim('sub', customValue) fail without throwing a visible error.

How are custom namespaced claims implemented via Post-Login Actions?

The required workaround uses Custom Namespaced Claims. Instead of attempting to overwrite the restricted standard claims, inject new custom claims that use a Uniform Resource Identifier (URI) namespace prefix to avoid collisions with standard OpenID Connect (OIDC) claims. Configure the downstream third-party application to read the custom identifier from the namespaced claim rather than the standard sub claim.

Implement the custom namespaced claim by creating an Auth0 Post-Login Action with the following JavaScript code.

exports.onExecutePostLogin = async (event, api) => {
  // Define a URI namespace (required by Auth0 for custom claims, does not need to be a live site)
  const namespace = 'https://<your-brand.com>';
  
  // The custom identifier to send to the third party
  const customSubValue = "<your_generated_custom_id>"; 

  // Append the custom namespaced claim to the ID Token
  api.idToken.setCustomClaim(`${namespace}/sub`, customSubValue);
};