Skip to main content

Authentication

OctoMesh uses OAuth 2.0 and OpenID Connect (OIDC) for authentication. This page explains how authentication works, which flows are supported, and what happens during the login process.

Overview​

Supported Flows​

Authorization Code with PKCE​

Used by web applications like Data Refinery Studio. The browser redirects to the Identity Service login page, the user authenticates, and the browser receives an authorization code that is exchanged for tokens.

  • PKCE (Proof Key for Code Exchange) is required — prevents authorization code interception
  • No client secret needed for public clients (SPAs)
  • Supports offline_access for refresh tokens

Device Code​

Used by octo-cli and other devices without a browser. The CLI displays a URL and code, the user opens the URL in any browser, enters the code, and authenticates.

  • The CLI polls /connect/token until the user completes authentication
  • Supports offline_access for long-lived sessions

Client Credentials​

Used for service-to-service communication where no user is involved. The client authenticates with its own credentials (client ID + secret) and receives an access token.

  • The token request must carry acr_values=tenant:{tenantId}. Clients are stored per tenant, and /connect/token has no tenant path segment — acr_values is the only way to tell the Identity Service which tenant's client store to search. Without it the lookup falls back to the system tenant, so a tenant-registered client fails with invalid_client. (Only clients that genuinely live in the system tenant may omit it.)
  • No user context — the token has no sub and no allowed_tenants claim. It carries tenant_id = the tenant selected with acr_values (the system tenant when acr_values is missing, which only clients of the system tenant may do; mirrored clients must send acr_values) and the tenant_gen of that tenant.
  • Client-credentials tokens are subject to the route tenant check like user tokens: they may address only their own tenant_id, unless the client is on the allow-list TenantAuthorization:CrossTenantServiceClientIds (see Tenant Authorization). A service that works in several tenants requests one token per tenant.
  • If the client has been assigned roles (directly or via group membership), the token carries the resolved role claims — in the same shape as a user token — so the client can call role-protected endpoints. Roles are resolved in the tenant selected via acr_values. See Client Roles and Group Membership.
  • Used for background jobs, inter-service calls, and automated processes

Token Exchange (RFC 8693) — Cross-Tenant Switching​

Used by the MCP Services to switch a session's operating tenant without a new browser login. Every access token is bound to exactly one operating tenant (tenant_id claim); services enforce this strictly. Instead of re-authenticating, an already-valid access token from the user's current tenant is exchanged for a token of the target tenant:

  • The exchange is only granted if the user has cross-tenant access to the target tenant (an ExternalTenantUserMapping; see Cross-Tenant Authentication)
  • The issued token runs on the target tenant's shadow user (xt_…), so roles are re-resolved in the target tenant — roles from the source tenant never leak across
  • No refresh token is issued for exchanged tokens; the client re-exchanges from the still-valid original token when needed
  • Only clients with the token-exchange grant may call it (the octo-mcpServices-device client)

Delegation / On-Behalf-Of​

A service-account client (machine-to-machine) can obtain an access token that runs on a user's identity, so work performed on that user's behalf is attributable to the user and bounded by what both parties may do. This is not impersonation: the service account can never exceed its own authority.

  • The issued token carries role = serviceAccountRoles ∩ userRoles — a broadly privileged service account acting for a low-privilege user gets the user's narrow set, and vice versa. Group-inherited roles count on both sides. An empty intersection is a successful grant: the token carries no role claim and every role-gated consumer fails closed.
  • The act claim names the service account's client_id, so services and the audit trail can tell a delegated token apart from one the user obtained themselves.
  • Same tenant only: the tenant in acr_values, the subject token's tenant_id and the request tenant must match; cross-tenant identity movement uses the token-exchange grant above.
  • No refresh tokens — requesting offline_access is rejected with invalid_scope. The role intersection is computed at issuance; a refresh would freeze it, so a role revoked on either side would keep working. Delegated tokens are re-minted from the still-valid user token.
  • Only clients listing the grant URN in their AllowedGrantTypes may call it.

The main consumer of this grant is Pipeline Identity: a pipeline running on behalf of the calling user.

Dynamic Client Registration (RFC 7591)​

Interactive MCP clients (Claude Code, Claude Desktop) do not use a pre-configured client_id — they self-register at the Identity Service's registration_endpoint (POST /connect/register) before starting the Authorization Code + PKCE flow.

  • Registered clients are named octo-dcr-* and are hard-constrained: loopback-only redirect URIs, PKCE required, public client (no secret), server-fixed scopes, bounded lifetime, per-IP rate limit and per-tenant cap
  • Registration alone grants nothing — a real user login is still required to obtain a token
  • Enabled by default; disable per deployment with OCTO_IDENTITY__DYNAMICCLIENTREGISTRATION__ENABLED=false
  • Because registration is tenant-agnostic, the subsequent login runs through tenant discovery (e-mail-first tenant selection); the registered client is mirrored into all tenants automatically

Multi-Tenant Authentication​

Authentication in OctoMesh is always scoped to a tenant. The tenant ID determines which user database, identity providers, and roles are used.

Tenant Resolution​

Different endpoints resolve the tenant differently:

EndpointTenant Source
REST API (/{tenantId}/v1/...)URL path segment
/connect/authorizeacr_values=tenant:{tenantId} query parameter
/connect/token (authorization_code, device_code, refresh_token)Mapped from the authorization code, device code, or refresh token
/connect/token (client_credentials, token exchange)acr_values=tenant:{tenantId} form parameter — required; without it the client lookup falls back to the system tenant
/connect/endsessionDecoded from id_token_hint JWT

The Identity Service scopes authentication cookies per tenant by appending the tenant ID to cookie names:

Standard CookieTenant-Scoped Cookie
.AspNetCore.Identity.Application.AspNetCore.Identity.Application.{tenantId}
idsrvidsrv.{tenantId}
idsrv.sessionidsrv.session.{tenantId}

This prevents session leakage between tenants when a user has sessions in multiple tenants on the same browser.

Per-Tenant Identity Provider Schemes​

External identity provider schemes are registered with a tenant prefix to prevent conflicts:

{tenantId}:{providerName}

Examples:
octosystem:Google
customer-project:AzureAD

Each tenant independently configures which providers are available and their credentials. Providers are dynamically registered at runtime — adding or updating a provider takes effect immediately without restarting the service.

Tenant-Specific Authentication for External Clients​

External applications (datasource plugins, third-party integrations, custom web apps) that need to authenticate users against a specific tenant must include the acr_values parameter in the OAuth authorize request. The acr_values parameter is defined in the OpenID Connect Core Specification (Section 3.1.2.1) and is the standard mechanism for requesting specific authentication contexts.

Authorize request with tenant selection:

GET /connect/authorize?
response_type=code
&client_id=my-application
&redirect_uri=https://my-app.example.com/callback
&scope=openid profile email role octo_api
&acr_values=tenant:customer-project
&code_challenge=...
&code_challenge_method=S256
&state=...

What happens:

The Identity Service:

  1. Parses tenant:customer-project from the acr_values parameter
  2. Redirects the user to the tenant's login page (/customer-project/login)
  3. The user sees only the authentication methods configured for that tenant
  4. After authentication, the issued token carries tenant_id: customer-project with roles and scopes from that tenant

Concurrent multi-tenant sessions: Because cookies are scoped per tenant, a user can authenticate with multiple tenants in the same browser. Switching between tenants after the initial login is seamless — the existing tenant cookie enables SSO without re-entering credentials.

Client registration: The OAuth client must be registered in each tenant where users need to authenticate. See Clients and API Scopes for details.

Access Token Structure​

When authentication succeeds, the Identity Service issues a JWT access token containing:

Standard Claims​

ClaimDescriptionExample
subUser ID"a1b2c3d4"
preferred_usernameUsername"john.doe"
nameDisplay name"John Doe"
emailEmail address"john@example.com"
given_nameFirst name"John"
family_nameLast name"Doe"

OctoMesh-Specific Claims​

ClaimDescriptionExample
tenant_idTenant the user logged into"customer-project"
allowed_tenantsTenants the user may access (repeated claim)"customer-project", "octosystem"
roleEffective roles (direct + group-inherited, repeated claim)"Development", "DashboardViewer"
home_tenant_idFor cross-tenant users: their parent tenant"octosystem"
tenant_genGeneration of the tenant in tenant_id: its creation time in Unix milliseconds. Access tokens only, not ID tokens or userinfo. See Tenant Generations"1794750381540"

Effective Roles​

The role claims include the union of:

  • Roles directly assigned to the user
  • Roles inherited through group membership (resolved recursively up to 10 levels of nesting)

Roles are resolved at token issuance time and updated on token refresh. The same resolution applies to clients authenticating via client_credentials — their directly-assigned and group-inherited roles are emitted as identical role claims.

Allowed Tenants​

The allowed_tenants claims are resolved from:

  1. The login tenant — always included
  2. The home tenant — for cross-tenant users, their parent tenant
  3. Ancestor tenants — walks up the tenant hierarchy via OctoTenantIdentityProvider parent references (up to 10 levels)
  4. Descendant tenants — BFS traversal down through child tenants where an ExternalTenantUserMapping exists for this user (cascading through multiple levels)

Token Validation by Services​

All OctoMesh services validate incoming requests using the same pattern:

Bearer Token Authentication​

Services validate JWT tokens against the Identity Service's signing keys. The token must:

  • Be a valid JWT signed by the Identity Service
  • Not be expired
  • Contain the required scopes for the requested operation

Tenant Authorization​

After standard JWT validation, the TenantAuthorizationMiddleware enforces the tenant binding of the token. Every OctoMesh API service with tenant routes runs it (except platform services), the Identity Service's own API included:

  1. Extract {tenantId} from the request URL path
  2. Compare it with the tenant_id claim of the token (user and client-credentials tokens alike)
  3. If they differ → 403 Forbidden in Enforce mode (in LogOnly the request is logged as "would be denied" and continues; see Configuration), with a JSON body {"message": "..."} naming the reason. Exceptions: endpoints marked for parent-tenant administration accept a user token of the parent tenant, and clients on the allow-list TenantAuthorization:CrossTenantServiceClientIds may address other tenants
  4. Compare the token's tenant_gen with the current generation of the tenant, so that a token of a deleted tenant is not accepted by a new tenant with the same id

allowed_tenants is never used for this decision; it only lists the tenants a user can switch to.

Request: GET /customer-project/v1/runtime/entities

Token claims:
sub: "a1b2c3d4"
tenant_id: "customer-project"

→ route tenant equals tenant_id → Access granted
Request: GET /other-tenant/v1/runtime/entities

Token claims:
sub: "a1b2c3d4"
tenant_id: "customer-project"
allowed_tenants: ["customer-project", "other-tenant"]

→ route tenant differs from tenant_id → 403 Forbidden (in Enforce mode)
(sign in to "other-tenant" or use the token exchange to get a token of that tenant)

The modes of both checks (LogOnly, Enforce), their configuration and Helm values, what happens to tokens when a tenant is deleted, recreated or restored, and troubleshooting are described in Tenant Authorization and Tenant Generations.

Authentication Flow: Step by Step​

This section traces a complete authentication flow for a browser-based application.

1. User Opens Application​

The client application (e.g., Data Refinery Studio) detects no valid session and redirects to the Identity Service:

GET /connect/authorize?
client_id=octo-data-refinery-studio
&response_type=code
&scope=openid profile email role octo_api
&redirect_uri=https://studio.example.com/callback
&code_challenge=...
&code_challenge_method=S256
&acr_values=tenant:customer-project

2. Identity Service Presents Login Page​

The Identity Service renders the login page for the customer-project tenant, showing the available identity providers (e.g., "Corporate Azure AD", local login form).

Tenant Unavailable

If a child tenant has no local users and no cross-tenant user mappings, the login page displays "This tenant is not available. Please contact your administrator." instead of the login form. This indicates that the tenant has not yet been provisioned with any user access. An administrator must first provision users from the parent tenant.

3. User Authenticates​

The user either:

  • Enters username/password (validated against the tenant's local user database)
  • Clicks an external provider button (redirected to Google, Azure AD, etc.)
  • Is authenticated via a parent tenant (if an OctoTenantIdentityProvider is configured)

4. First Login Processing​

On first login via an external provider, the Identity Service:

  1. Creates a local user record linked to the external identity
  2. Checks email domain group rules and adds the user to matching groups
  3. If the provider has a DefaultGroupRtId, adds the user to that group
  4. Resolves effective roles from group memberships

5. Token Issuance​

The Identity Service:

  1. Resolves all effective roles (direct + group-inherited)
  2. Resolves allowed tenants (login tenant + home tenant + child tenants with mappings)
  3. Issues a JWT access token with all claims
  4. Returns the token to the client application

6. API Calls​

The client includes the access token in API requests:

GET /customer-project/v1/runtime/entities
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

The target service validates the token and checks tenant authorization before processing the request.

Password Changes End Existing Sessions​

Every password change through the REST API (a user changing or setting their own password, an administrator resetting a password, or the e-mailed reset link) ends all sessions issued before the change:

  • The user's security stamp is rotated.
  • All refresh tokens and authorizations of that user in the same tenant are revoked. A client that presents an old refresh token receives invalid_grant; the user signs in again with the new password.
  • Other users, and the same user in another tenant, are not affected.
  • One audit log entry records the tenant, the user, the acting user and the path. Passwords and token values are never logged.

Access tokens that were already issued stay valid until they expire (they are short-lived); only renewal is blocked.

Initial Setup​

The very first time the Identity Service starts, no users exist. The setup endpoint creates the initial administrator:

# Interactive: octo-cli asks for the admin password twice, without echoing it (when OCTO_CLI_NEW_PASSWORD is not set)
octo-cli -c Setup -e "admin@example.com"

# In a script: pipe the password in from a secret store (or set OCTO_CLI_NEW_PASSWORD from one)
Get-Secret -Name OctoAdminPassword -AsPlainText | octo-cli -c Setup -e "admin@example.com" --password-stdin
# bash: read the password without echoing it, then pipe it in; it never appears in the history
read -rs -p "Admin password: " PW && echo && printf '%s' "$PW" | octo-cli -c Setup -e "admin@example.com" --password-stdin
status=$?; unset PW; [ "$status" -eq 0 ] # keeps success or failure of octo-cli

Never pass the password as an argument: a value on the command line ends up in the shell history and the process list. -p/--password is deprecated (it still works but writes a warning); the date of its removal will be announced.

This endpoint:

  1. Verifies no users exist in the system tenant (fails otherwise)
  2. Creates the admin user with the specified credentials
  3. The admin can then log in and configure tenants, clients, and providers

After setup, the system tenant has:

  • The admin user
  • Default clients (octo-cli, Swagger UI)
  • Default identity resources (openid, profile, email, role)
  • Default API scopes and resources
  • Default identity providers (Google, Microsoft — disabled; system tenant only)
  • Default roles and TenantOwners group

See Also​