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
The React Tooling Shell acts as the main administrative interface for . It integrates with Auth0 Organizations to support multi-tenant isolation.
Initial Authentication Sequence
- Navigate to the administrative URL (for example, admin.example.com).
- The
Auth0Providerredirects the browser to Auth0 Universal Login. - The user authenticates via username/password credentials or Single Sign-On (SSO).
- Auth0 returns
access_token,id_token(JWT), andrefresh_token. - The Tooling Shell stores tokens in memory (never in
localStorageorsessionStorage) and centralizes authentication, token management, and cookie handling for all API requests.
Tenant Configuration Resolution
| 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>
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).