October, 2026 release

Setting up authentication for the Admin Tooling

A step-by-step setup guide for IT administrators configuring the Tooling Shell and Auth0 during initial deployment. Includes domain mapping in shell-config.json backend environment variables, and MFE token sharing architecture.

About this task

Authenticating the Tooling (Admin) UI

The React Tooling Shell acts as the main administrative interface for . It integrates with Auth0 Organizations to support multi-tenant isolation.

Initial Authentication Sequence

  1. Navigate to the administrative URL (for example, admin.example.com).
  2. The Auth0Provider redirects the browser to Auth0 Universal Login.
  3. The user authenticates via username/password credentials or Single Sign-On (SSO).
  4. Auth0 returns access_token, id_token (JWT), and refresh_token.
  5. The Tooling Shell stores tokens in memory (never in localStorage or sessionStorage) and centralizes authentication, token management, and cookie handling for all API requests.

Tenant Configuration Resolution

Removed the dependency on shell-config.json; the configuration is now fully driven by environment variables.
Table 1. Environment variables
Variable Expected value
APP_ENV sb, dv, qa, in, st, pd
AUTH0_AUDIENCE API audience URL/string
AUTH0_CLIENT_ID Auth0 app client ID
AUTH0_DOMAIN Auth0 tenant domain
AUTH0_ORG_ID Auth0 organization ID
MAPPED_ORGS Auth0 organization ID
PBC_ENV_SUFFIX -pbcst (any - or . is also added from here)
PBC_DOMAIN_SUFFIX .aks.local
PBC_PROXY_SCHEME https/http (http is default)

JWT Custom Claims

Auth0 issues JWT tokens containing custom claims under the https://commerce-plus.hcl.com/ namespace:

Claim Description
https://commerce-plus.hcl.com/user_id Commerce Plus user ID represented as a 21-character NanoID.
https://commerce-plus.hcl.com/user_account_id Account ID of the user.
https://commerce-plus.hcl.com/user_organization_id Organization ID of the user.
https://commerce-plus.hcl.com/virtual_organization_id Virtual Organization (tenant) ID.
https://commerce-plus.hcl.com/user_type User type enumeration (b2b, b2c, admin).
https://commerce-plus.hcl.com/personas Assigned persona IDs.
https://commerce-plus.hcl.com/permissions Granted user permissions.
org_id Auth0 Organization ID.

Bearer Token Strategy

The Tooling Shell uses the Auth0 id_token as the temporary bearer token for API calls during initial context setup:

Authorization: Bearer <id_token>
Note: The codebase utilizes id_token temporarily prior to switching to audience-scoped access tokens. Once the initial resolveContext mutation succeeds, Identity issues a signed httpOnly

axp_user

cookie. Subsequent requests rely on the browser sending this cookie automatically while stripping the Bearer token header.

Sharing authentication across Micro-Frontends (MFEs)

The shell installs a global fetch interceptor that automatically attaches required context headers (x-workspace-id, x-host-name) to outbound API requests while stripping redundant Authorization headers after context resolution.

Appendix — Auth0 Management API interactions

Identity utilizes Auth0 Management API (M2M) for backend administration tasks (user creation, organization assignments, password resets) using OAuth 2.0 client_credentials grant flow.

Identity PBC ──► Auth0 Management API
  │                     │
  │  POST /oauth/token  │
  │  grant_type: client_credentials
  │  client_id: <M2M_CLIENT_ID>
  │  client_secret: <M2M_CLIENT_SECRET>
  │  audience: https://<domain>/api/v2/
  │◄────────────────────│
  │  { access_token }   │
  │                     │
  │  POST /api/v2/users │
  │  Authorization: Bearer <m2m_token>
  │──────────────────►  │

Required backend environment variables:

  • AUTH0_DOMAIN — Auth0 tenant domain identifier.
  • AUTH0_M2M_CLIENT_ID — Machine-to-machine application client ID.
  • AUTH0_M2M_CLIENT_SECRET — Machine-to-machine client application secret.
  • AUTH0_DB_CONNECTION — Auth0 database connection string name (Default: Username-Password-Authentication).