Auth Method Configuration

This guide covers authentication method configuration for org admins and platform operators. It describes how to enable or disable each auth method (OIDC, SAML, and native username/password), how to test IdP connectivity before going live, and how to move to an SSO-only posture.

For end-user login flow details (what happens when a user clicks “Sign in with Microsoft”), see SSO login flow. For initial IdP registration (creating SAML IdP configs and setting OIDC environment variables), see SSO configuration guide.

Authentication methods overview

Arbitex supports three authentication methods. All three can be active simultaneously. Users authenticate via whichever method their client initiates.

Method	Enabled by	Status check
Entra ID OIDC	Platform operator (environment variables)	`GET /api/auth/oauth/status`
SAML 2.0	Org admin (API or UI)	Check `is_active` on each IdP config
Native (username + password)	Active by default	No explicit on/off switch — disabled at the deployment level

OIDC and SAML are configured independently. You can have one, both, or neither active. Native login is available as long as it has not been disabled by the platform operator.

OIDC (Entra ID) configuration

Enabling OIDC

OIDC is enabled by setting three environment variables on the Platform API and restarting the service:

Variable	Value
`GOOGLE_CLIENT_ID`	Entra ID Application (client) ID
`GOOGLE_CLIENT_SECRET`	Entra ID client secret value
`GOOGLE_REDIRECT_URI`	`https://api.arbitex.ai/api/auth/oauth/google/callback`

These must be set by a platform operator (someone with access to the Platform API deployment). Org admins do not have access to environment variables.

In Kubernetes deployments, inject these values via Azure Key Vault CSI driver secrets rather than plaintext environment variables or ConfigMaps.

After setting the variables, restart the Platform API pod:

kubectl rollout restart deployment/arbitex-platform-api -n arbitex

Verifying OIDC is active

GET https://api.arbitex.ai/api/auth/oauth/status

Response when active:

{ "sso_enabled": true }

Response when not configured:

{ "sso_enabled": false }

If sso_enabled is false after setting the environment variables, verify that:

The Key Vault CSI driver secret provider class is referencing the correct secret names
The pod has restarted and picked up the new secrets (kubectl get pods shows a new pod age)
The environment variable names exactly match those listed above (they are case-sensitive)

Disabling OIDC

Remove the three OIDC environment variables and restart the Platform API. The /api/auth/oauth/status endpoint returns { "sso_enabled": false }.

Users provisioned via OIDC SSO retain their accounts. After OIDC is disabled, they must authenticate via SAML or native password (if those methods are active). If no other method is available for a user, they cannot log in until a method is enabled or their account is given a native password.

SAML 2.0 configuration

Enabling a SAML IdP

Create a SAML IdP configuration via the admin API:

POST /api/admin/saml/idp
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "name": "Okta SAML",
  "entity_id": "https://your-okta-domain.okta.com",
  "sso_url": "https://your-okta-domain.okta.com/app/arbitex/sso/saml",
  "slo_url": "https://your-okta-domain.okta.com/app/arbitex/slo/saml",
  "x509_cert": "<base64-encoded PEM certificate without headers>",
  "attribute_mapping": {
    "email": "urn:oid:0.9.2342.19200300.100.1.3",
    "display_name": "urn:oid:2.16.840.1.113730.3.1.241"
  },
  "is_active": true
}

is_active: true enables the IdP immediately. Set is_active: false to register the IdP without enabling it (useful for staging a new configuration before cutover).

Provide the following SP metadata to your IdP when creating the application:

Field	Value
ACS URL	`https://api.arbitex.ai/api/auth/saml/acs`
Entity ID (SP)	`https://api.arbitex.ai`
NameID format	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
Binding	HTTP POST

See SSO configuration guide for Entra ID-specific SAML setup steps.

Listing active SAML IdPs

GET /api/admin/saml/idp
Authorization: Bearer <admin_token>

Response:

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Okta SAML",
      "entity_id": "https://your-okta-domain.okta.com",
      "is_active": true,
      "created_at": "2026-03-11T00:00:00Z",
      "updated_at": "2026-03-11T00:00:00Z"
    }
  ],
  "total": 1
}

The entity_id field uniquely identifies each IdP configuration. If you attempt to create two configurations with the same entity_id, the second request returns 409 Conflict.

Disabling a SAML IdP

Set is_active: false without deleting the configuration:

PUT /api/admin/saml/idp/{idp_id}
Authorization: Bearer <admin_token>
Content-Type: application/json

{ "is_active": false }

The configuration is retained. Re-enable it by setting is_active: true. This is the recommended approach when testing a new IdP — disable the old one, enable the new one, verify, then delete the old one.

Deleting a SAML IdP

DELETE /api/admin/saml/idp/{idp_id}
Authorization: Bearer <admin_token>

Returns 204 No Content. Deletion is permanent. Users cannot authenticate via this IdP after deletion. This does not delete user accounts — it only removes the authentication path.

Rotating the signing certificate

When your IdP rotates its SAML signing certificate, update the registered certificate in Arbitex before the old certificate expires:

PUT /api/admin/saml/idp/{idp_id}
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "x509_cert": "<new base64-encoded PEM certificate without headers>"
}

Only the fields included in the request are updated. Rotating the certificate does not affect the is_active status or other fields. Update the certificate in Arbitex before the IdP stops signing with the old certificate, not after — if the old certificate expires while still registered, SAML signature validation fails immediately for all users on that IdP.

Native (username + password) authentication

Native authentication is active by default. It cannot be toggled by org admins — it is controlled at the deployment level by the platform operator.

When to disable native auth: Organizations that require all users to authenticate via a managed identity provider (for access lifecycle management, conditional access, MFA enforcement) should disable native auth to prevent users from bypassing IdP controls by logging in with local credentials.

Disabling native authentication (platform operator)

Native auth disable is a deployment-level configuration change. Contact your platform operator. The platform operator removes or disables the native auth route in the Platform API deployment.

After disabling, any user who authenticates exclusively via native credentials (no SSO account linked) cannot log in. Ensure all users have SSO accounts provisioned before disabling native auth.

Verifying auth method availability

To confirm which methods are available to users before and after configuration changes:

OIDC status: GET /api/auth/oauth/status → { "sso_enabled": true/false }
SAML status: GET /api/admin/saml/idp → count is_active: true items
Native auth: attempt a login with a test account credentials

Enforcing SSO-only authentication

SSO-only enforcement means users can only authenticate via OIDC or SAML — native username/password login is unavailable.

Steps to enforce SSO-only

Provision all users via SSO first. Ensure every active user account has authenticated via SSO at least once (JIT provisioning creates their account on first SSO login). Users who have only ever used native auth need to sign in via SSO before native auth is disabled.
Verify SSO is working. Confirm at least one SSO method is active and functional:
- For OIDC: GET /api/auth/oauth/status returns { "sso_enabled": true }
- For SAML: at least one IdP with is_active: true exists
Test SSO login end-to-end. Sign in as a test user via SSO to confirm the full flow works before disabling native auth.
Disable native authentication at the deployment level (platform operator step — see above).
Monitor for login failures. After disabling native auth, watch for users who cannot sign in. These users likely do not have an SSO account. Re-enable native auth temporarily to allow them to link their account, or provision them via SCIM.

SCIM-provisioned users and SSO-only

If your org uses SCIM provisioning (Entra ID or Okta), users are created in Arbitex before they log in. Their accounts exist but have no password. When they sign in via SSO, the account is matched by email. This is the recommended path for SSO-only enforcement — provision via SCIM, then disable native auth.

See SSO configuration guide — SCIM token rotation for SCIM setup.

Testing IdP connectivity

Before enabling an IdP for production use, verify the configuration end-to-end:

Testing OIDC

Set the OIDC environment variables on a staging deployment of the Platform API.
Call GET /api/auth/oauth/status — confirm { "sso_enabled": true }.
Initiate a login: call GET /api/auth/oauth/google/authorize and follow the returned authorization_url in a browser.
Complete the Entra ID login.
Verify you are redirected back to https://api.arbitex.ai/api/auth/oauth/google/callback and receive tokens.
Call GET /api/auth/me with the returned access token to confirm the user profile is correct.

Testing SAML

Create a SAML IdP configuration with is_active: false (inactive staging config).
Use a SAML testing tool (your IdP’s built-in tester, or a SAML tracer browser extension) to verify the SP metadata is correct:
- ACS URL: https://api.arbitex.ai/api/auth/saml/acs
- Entity ID: https://api.arbitex.ai
Set is_active: true on the IdP configuration.
Initiate a SAML login flow and verify it completes without signature validation errors.
Check the user account is created or matched correctly via GET /api/auth/me.

Common connectivity issues

Symptom	Likely cause	Resolution
OIDC callback returns error	Redirect URI mismatch	Verify redirect URI in Azure Portal App Registration matches exactly
SAML signature validation failed	x509_cert mismatch	Rotate the certificate in the IdP config
`email_verified: false` on OIDC	Entra ID user’s email not verified	Check Entra ID user profile; contact Entra ID admin
SAML attribute not found	Attribute mapping misconfigured	Update `attribute_mapping` in the IdP config to match your IdP’s attribute URIs
409 on SAML IdP creation	`entity_id` already registered	Fetch existing configs with `GET /api/admin/saml/idp`, update or delete the existing one