Authentication Overview¶

ARX supports six authentication methods to accommodate organizations at every stage of identity maturity. This guide describes each method, when to use it, and how to choose the right combination for your deployment.

Supported Authentication Methods¶

1. Supabase JWT Authentication¶

Supabase Auth is the default authentication layer for ARX. Users sign in through the ARX web application, which issues a JSON Web Token (JWT) signed with HS256 using the Supabase anonymous key. The JWT carries an aud claim of "authenticated" and a sub claim containing the user ID.

Best for: Teams getting started with ARX, small-to-medium deployments, and organizations that do not yet have a centralized identity provider.

2. Auth0 OIDC¶

Auth0 serves as a bridge between ARX and enterprise identity providers. Tokens issued by Auth0 are signed with RS256 and validated against the Auth0 JWKS endpoint. ARX determines the issuer from the iss claim and routes validation accordingly. The sub claim is resolved to a local user record via the sso_subject field.

Best for: Organizations that already use Auth0 as an identity broker, or teams that need to federate multiple upstream IdPs through a single integration point. Auth0 features such as Universal Login, MFA policies, and anomaly detection are available when using this method.

3. SAML 2.0¶

ARX operates as a SAML 2.0 Service Provider (SP). It exposes SP metadata at /v1/auth/saml/metadata, accepts SAML assertions at the Assertion Consumer Service (ACS) endpoint, and supports both SP-initiated and IdP-initiated login flows. After successful authentication, ARX issues a session JWT and performs just-in-time (JIT) user provisioning. Single Logout (SLO) is supported.

Best for: Enterprises with SAML-based identity providers such as Okta, Microsoft Entra ID, or OneLogin that require direct SAML federation without an intermediate broker.

4. OIDC SSO (Okta, Microsoft Entra ID, Google Workspace)¶

ARX provides native OIDC SSO integrations for Okta, Microsoft Entra ID, and Google Workspace. The flow uses the standard authorization code grant: the client calls POST /v1/auth/sso/authorize to obtain a redirect URL, the user authenticates with the provider, and ARX exchanges the authorization code for tokens at the callback endpoint. JIT user provisioning is performed automatically.

Best for: Organizations that prefer OIDC over SAML, or those using Okta, Microsoft Entra ID, or Google Workspace as their primary identity provider. OIDC SSO is the recommended path for most enterprises due to simpler configuration and faster time-to-value.

5. API Keys¶

API keys provide non-interactive, machine-to-machine authentication for CI/CD pipelines, scripts, and third-party integrations. Keys use the prefix arx_k1_ and are sent via the X-API-Key HTTP header. Each key is SHA-256 hashed for storage and inherits the RBAC role of the user who created it.

Best for: Automated workflows, CI/CD pipelines, Terraform providers, and any scenario that requires programmatic access without interactive login.

6. SCIM Tokens¶

SCIM bearer tokens authenticate provisioning requests from identity providers that support the SCIM 2.0 protocol. These are organization-scoped shared secrets, hashed with bcrypt, and stored in the scim_tokens table. SCIM tokens grant access only to the SCIM 2.0 provisioning endpoints (/scim/v2/*) and are separate from user-facing authentication.

Best for: Enabling automated user lifecycle management (provisioning, deprovisioning, group sync) from Okta, Microsoft Entra ID, or any SCIM 2.0-compliant identity provider.

Authentication Decision Tree¶

Use the following framework to select the appropriate authentication method for your organization.

Start
  |
  +-- Are you building a CI/CD integration or automated pipeline?
  |     YES --> API Keys
  |
  +-- Do you need automated user provisioning from an IdP?
  |     YES --> SCIM Tokens (for provisioning) + SSO method (for login)
  |
  +-- Does your IdP support OIDC and is it Okta, Entra ID, or Google?
  |     YES --> OIDC SSO (recommended for most enterprises)
  |
  +-- Does your organization mandate SAML 2.0?
  |     YES --> SAML 2.0
  |
  +-- Do you already use Auth0 as an identity broker?
  |     YES --> Auth0 OIDC
  |
  +-- None of the above?
        --> Supabase JWT Authentication

Combining Methods¶

Most enterprise deployments use a combination of methods:

How Authentication Flows Into RBAC¶

Regardless of the authentication method, every authenticated request produces a User context containing:

• id -- the user's unique identifier (UUID).
• org_id -- the organization the user belongs to (UUID).
• email -- the user's email address.
• role -- one of admin, deployer, auditor, or viewer.
• full_name -- the user's display name (optional).

This user context is then evaluated by the RBAC middleware before every API endpoint. See RBAC & Roles for the full permission matrix.

Token Lifecycle¶

Next Steps¶

• Supabase JWT Authentication
• OIDC SSO (Okta, Microsoft, Google)
• SAML 2.0 Setup
• API Key Management
• SCIM 2.0 Provisioning
• RBAC & Roles