Skip to main content

Authentication with Auth0

This page documents how authentication is set up for the DeltaFM Facilities Maintenance application and how the frontend, Auth0, and backend APIs fit together.

DeltaFM is a multi-tenant application. Auth0 Organizations are used to separate client tenants, with each client that signs up receiving its own Auth0 organization.

Purpose​

Auth0 is the identity provider for DeltaFM. It is responsible for:

  • authenticating users
  • issuing identity and access tokens
  • managing sessions
  • centralising login and logout flows
  • separating customer tenants through Auth0 Organizations

The DeltaFM application is responsible for:

  • redirecting users to Auth0 when authentication is required
  • accepting tokens after login
  • attaching access tokens to protected API requests
  • enforcing authorization rules in backend services

High-level architecture​

The authentication flow has four main parts:

  1. The DeltaFM frontend application
  2. The Auth0 tenant
  3. The Auth0 organization for the client
  4. The DeltaFM backend API
  5. The user directory or identity source behind Auth0

Typical flow:

User
  -> DeltaFM frontend
  -> Auth0 login
  -> Auth0 organization resolution
  -> Auth0 issues tokens
  -> DeltaFM frontend stores session state
  -> DeltaFM frontend calls DeltaFM API with access token
  -> DeltaFM API validates token and authorizes request

Core Auth0 components​

Auth0 tenant​

The tenant is the central Auth0 instance for DeltaFM.

Document here:

  • Auth0 domain
  • tenant name
  • region
  • production vs non-production tenants

Example placeholders:

Domain: your-tenant.au.auth0.com
Management region: Australia
Environments: dev, test, production

Application​

This is the Auth0 application representing the DeltaFM frontend.

Document here:

  • application type
  • client ID
  • allowed callback URLs
  • allowed logout URLs
  • allowed web origins

For a browser-based frontend this is commonly a Single Page Application.

Organizations​

DeltaFM uses Auth0 Organizations to implement multi-tenancy.

Rules:

  • each client has its own Auth0 organization
  • users belong to the organization for their client
  • login requests should include the target organization when the tenant context is known
  • tokens should carry organization context so the backend can enforce tenant isolation

Document here:

  • organization naming convention
  • how organization membership is provisioned
  • whether users can belong to more than one organization
  • whether connections are enabled per organization
  • how the frontend determines which organization to send during login

Example placeholders:

Organization name: acme-facilities
Organization display name: Acme Facilities
Organization ID claim: org_id
Organization name claim: org_name

API​

If DeltaFM protects backend endpoints with Auth0-issued access tokens, there should be an Auth0 API configured with:

  • API identifier or audience
  • signing algorithm
  • token lifetime
  • scopes exposed to clients

Example placeholders:

Audience: https://api.deltafm.example.com
Scopes:
- read:workorders
- write:workorders
- read:assets
- write:assets

Users, roles, and permissions​

Document how Auth0 authorization is mapped into DeltaFM access rules.

Possible patterns:

  • Auth0 roles map directly to DeltaFM roles
  • Auth0 permissions are added to the access token
  • DeltaFM loads application roles from its own database after login
  • organization membership determines which client tenant the user can access

Be explicit about which model DeltaFM uses.

Login flow​

The recommended login flow for a web app is Authorization Code Flow with PKCE.

Typical sequence:

  1. The user opens DeltaFM.
  2. The frontend identifies the client tenant and its matching Auth0 organization.
  3. The frontend checks whether a valid Auth0 session exists.
  4. If the user is not authenticated, the frontend redirects to Auth0.
  5. The login request includes the Auth0 organization for that client.
  6. The user signs in through the Auth0 Universal Login page.
  7. Auth0 redirects the user back to DeltaFM using the configured callback URL.
  8. The frontend processes the response and establishes the application session.
  9. The frontend requests or reuses an access token for API calls.

Logout flow​

Typical logout sequence:

  1. The user clicks logout in DeltaFM.
  2. The frontend clears local session state.
  3. The frontend redirects to the Auth0 logout endpoint.
  4. Auth0 clears the identity provider session and returns the user to the configured post-logout URL.

Document whether DeltaFM performs:

  • local logout only
  • Auth0 logout
  • federated logout

Token usage​

DeltaFM should distinguish between:

  • ID token: proves the identity of the authenticated user to the frontend
  • Access token: sent to backend APIs to authorize protected requests
  • Refresh token: used only if the app is configured for refresh token rotation

Important rule:

  • the frontend should not use the ID token to authorize API calls

Frontend responsibilities​

The frontend integration usually handles:

  • initializing the Auth0 SDK
  • redirecting unauthenticated users to login
  • processing the callback after login
  • reading user profile claims
  • silently obtaining access tokens
  • sending the access token in the Authorization: Bearer <token> header

Document the exact integration points here:

  • auth provider setup file
  • route guard or protected route component
  • login action
  • logout action
  • token acquisition helper
  • HTTP client interceptor or fetch wrapper
  • tenant-to-organization resolution logic

Example topics to capture:

src/auth/auth-provider.tsx
src/auth/protected-route.tsx
src/api/http-client.ts

Backend responsibilities​

The backend must not trust the frontend session by itself. It should validate every incoming access token.

Document here:

  • how the API validates JWT signatures
  • expected issuer
  • expected audience
  • required scopes or permissions
  • how user claims are mapped into application identity
  • how organization claims are mapped to the DeltaFM tenant record
  • how cross-tenant access is blocked

Typical checks:

  • token signature is valid
  • token is not expired
  • issuer matches the Auth0 tenant
  • audience matches the DeltaFM API identifier
  • required permissions are present
  • organization claim matches the tenant being accessed

Environment configuration​

Record the environment variables and where they are used.

Typical frontend variables:

AUTH0_DOMAIN=
AUTH0_CLIENT_ID=
AUTH0_AUDIENCE=
AUTH0_REDIRECT_URI=
AUTH0_LOGOUT_URI=
AUTH0_ORGANIZATION=

Typical backend variables:

AUTH0_DOMAIN=
AUTH0_AUDIENCE=
AUTH0_ISSUER=

For each variable, document:

  • where it is defined
  • which environments use it
  • whether it is safe to expose to the frontend

How everything ties together​

At runtime, the pieces connect like this:

  1. DeltaFM frontend starts and loads Auth0 configuration.
  2. The application identifies which client tenant is being accessed.
  3. The frontend maps that client tenant to the correct Auth0 organization.
  4. A user attempts to access a protected page.
  5. The frontend sends the user to Auth0 login with the organization context.
  6. Auth0 authenticates the user inside that organization and redirects back to DeltaFM.
  7. The frontend obtains an access token for the DeltaFM API audience.
  8. The token includes identity, authorization, and organization context.
  9. The frontend calls the API with the bearer token.
  10. The backend validates the token and checks that the organization matches the DeltaFM tenant being accessed.
  11. DeltaFM returns data only if the claims, roles, permissions, and tenant context are valid.

Security notes​

  • Never hardcode secrets into the frontend.
  • Protect production callback and logout URLs carefully.
  • Keep token lifetimes aligned with user experience and risk.
  • Prefer role or permission checks on the backend, not only in the UI.
  • Document any custom Auth0 Actions, Rules, or Hooks that modify tokens.
  • Treat organization context as part of every authorization decision in a multi-tenant flow.

What should be added next​

This page should be updated with the actual DeltaFM implementation details:

  • Auth0 tenant domain
  • application name and type
  • callback URLs
  • logout URLs
  • audience value
  • scopes and permissions
  • organization naming and tenant mapping rules
  • frontend auth files
  • backend token validation files
  • any role-mapping rules

Once those values are added, this becomes the source of truth for authentication across the team.