Portal Community
Passport

Auth0 Integration

Configure Auth0 as the identity provider — create an API resource, set the audience, use Auth0 Actions to inject custom claims and tenant ID, and map roles to BizFirstGO.

Auth0 Configuration Steps

1

Create Auth0 API

In Auth0 Dashboard → APIs → Create API.
Name: BizFirstGO API, Identifier (Audience): https://api.bizfirstgo.com
Signing Algorithm: RS256.

2

Create Auth0 Action (Add Custom Claims)

In Auth0 → Actions → Flows → Login → Add Custom Claims:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://bizfirstgo.com/';

  // Add BizFirstGO tenant ID
  api.accessToken.setCustomClaim(
    namespace + 'tenant_id',
    event.user.app_metadata?.bizfirst_tenant_id ?? 'tenant-default'
  );

  // Add roles from app_metadata
  const roles = event.user.app_metadata?.bizfirst_roles ?? [];
  api.accessToken.setCustomClaim(namespace + 'roles', roles);
};
3

Assign Roles in User Profiles

Set bizfirst_roles and bizfirst_tenant_id in each user's app_metadata via Auth0 Management API or the Auth0 Dashboard user editor.

Auth0 Token Structure

// Decoded Auth0 access token
{
  "iss":   "https://your-tenant.auth0.com/",
  "sub":   "auth0|5f7c8796f0bb1a0d5e5bcdfe",
  "aud":   ["https://api.bizfirstgo.com", "https://your-tenant.auth0.com/userinfo"],
  "exp":   1748120400,
  "iat":   1748119500,
  "email": "jane.smith@company.com",
  "name":  "Jane Smith",

  // Custom namespace claims (added by Auth0 Action)
  "https://bizfirstgo.com/tenant_id": "tenant-abc",
  "https://bizfirstgo.com/roles":     ["admin", "manager"]
}

BizFirstGO Federation Configuration

POST /passport/admin/tenants/{tenantId}/federation
{
  "providerId":    "auth0-main",
  "displayName":   "Auth0",
  "issuer":        "https://your-tenant.auth0.com/",
  "jwksUri":       "https://your-tenant.auth0.com/.well-known/jwks.json",
  "audience":      "https://api.bizfirstgo.com",
  "tenantIdClaim": "https://bizfirstgo.com/tenant_id",
  "userIdClaim":   "sub",
  "emailClaim":    "email",
  "rolesClaim":    "https://bizfirstgo.com/roles",
  "roleMapping": {
    "admin":   "admin",
    "manager": "manager",
    "user":    "user",
    "viewer":  "viewer"
  }
}
Auth0 Custom Claims Must Use a Namespace URL

Auth0 requires all custom claims in access tokens to use a namespace URI prefix (e.g., https://bizfirstgo.com/tenant_id). Claims without a namespace are stripped from the token. Configure tenantIdClaim and rolesClaim in BizFirstGO with the full namespaced claim name.

← Azure AD Integration Next: Keycloak Integration →