Entra ID SSO

Arbitex supports OAuth 2.0 / OpenID Connect (OIDC) single sign-on via Microsoft Entra ID. When SSO is configured, users can sign in to the Arbitex platform using their Microsoft identity. New users are provisioned automatically (JIT provisioning) on first login — no pre-staging of accounts required.

This guide covers SSO login configuration. For automated user and group provisioning, see Entra ID SCIM provisioning.

sequenceDiagram
    participant User
    participant Arbitex as Arbitex Platform<br/>(api.arbitex.ai)
    participant Entra as Microsoft Entra ID

    User->>Arbitex: GET /api/auth/oauth/google/authorize
    Note over Arbitex: Generates state token
    Arbitex-->>User: 200 { authorization_url }
    User->>Entra: Redirect to authorization URL
    Entra->>User: Consent screen (if first login)
    User->>Arbitex: POST /api/auth/oauth/google/callback { code, state }
    Arbitex->>Entra: Exchange code for tokens
    Entra-->>Arbitex: id_token + access_token
    Note over Arbitex: Validate OIDC ID token<br/>Verify email_verified claim
    Note over Arbitex: JIT-provision user if new<br/>(email, username from OIDC claims)
    Arbitex-->>User: { access_token, refresh_token, user }

After successful authentication, Arbitex issues a JWT access token and refresh token. These tokens are used for all subsequent API calls.

Prerequisites

Microsoft Azure subscription with Entra ID (Azure Active Directory)
Permission to create and configure App Registrations in Entra ID
Arbitex admin credentials to configure platform environment variables

Step 1: Register an application in Entra ID

Sign in to the Azure Portal.
Navigate to Microsoft Entra ID → App registrations → New registration.
Set the following:
- Name: Arbitex Gateway (or your preferred display name)
- Supported account types: Accounts in this organizational directory only (single tenant) or Accounts in any organizational directory (multi-tenant) based on your requirements
- Redirect URI (optional at this step): Leave blank — you’ll add it in Step 2
Click Register.

After registration, note:

Application (client) ID — you’ll need this as GOOGLE_CLIENT_ID (or OAUTH_CLIENT_ID depending on your config)
Directory (tenant) ID — needed to construct the OIDC discovery URL

Step 2: Configure redirect URIs

In your app registration, navigate to Authentication → Add a platform → Web.

Add the redirect URI:

https://api.arbitex.ai/api/auth/oauth/google/callback

For local development:

http://localhost:8100/api/auth/oauth/google/callback

Under Implicit grant and hybrid flows, leave both checkboxes unchecked (Arbitex uses the authorization code flow).
Click Save.

Step 3: Create a client secret

Navigate to Certificates & secrets → New client secret.
Set a description (e.g., Arbitex SSO) and expiry period.
Click Add.
Copy the secret Value immediately — it is not displayed again after you leave this page.

Step 4: Configure API permissions

Arbitex requires the following Microsoft Graph permissions for OIDC login:

Permission	Type	Purpose
`openid`	Delegated	OIDC login
`profile`	Delegated	Display name for JIT provisioning
`email`	Delegated	Email address (primary identifier)

Navigate to API permissions → Add a permission → Microsoft Graph → Delegated permissions.
Add openid, profile, and email.
Click Add permissions.
If your tenant requires admin consent for delegated permissions: click Grant admin consent for [your tenant].

Step 5: Configure Arbitex platform

Set the following environment variables on the Arbitex Platform API:

Variable	Value	Notes
`GOOGLE_CLIENT_ID`	Application (client) ID from Step 1	Used as the OAuth client ID
`GOOGLE_CLIENT_SECRET`	Client secret value from Step 3	Keep this secret — treat as a credential
`GOOGLE_REDIRECT_URI`	`https://api.arbitex.ai/api/auth/oauth/google/callback`	Must match the redirect URI registered in Step 2

In production, these values are stored in Azure Key Vault and injected via the Key Vault CSI driver at pod startup. Do not store them in plaintext in configuration files.

Restart the Platform API after setting these variables.

Step 6: Verify SSO is enabled

Check that the platform recognizes the SSO configuration:

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

Response:

{ "sso_enabled": true }

If sso_enabled is false, the environment variables are not being read correctly. Check that the Key Vault secrets are accessible and the pod has restarted.

Get the authorization URL:

GET https://api.arbitex.ai/api/auth/oauth/google/authorize

Response:

{
  "authorization_url": "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?..."
}

Open the authorization_url in a browser. You are redirected to the Microsoft login page.
Sign in with a user account from your Entra ID tenant.
After successful authentication, the browser redirects back to the configured redirect URI with an authorization code.
The platform exchanges the code for tokens, validates the OIDC ID token, and either provisions a new user account (first login) or authenticates the existing account.
Verify the response includes access_token and the correct user object.

JIT user provisioning

When a user authenticates via SSO for the first time, Arbitex automatically creates their account using information from the OIDC ID token:

Field	Source
Email	`email` claim (must be verified — `email_verified: true`)
Username	`name` claim, or email prefix if name is not set
Role	`USER` (default) — admin role must be assigned separately
Password	Not set — authentication is SSO-only for JIT-provisioned users

If the email is not verified by the identity provider, authentication is rejected (email_verified must be true in the ID token).

If the derived username conflicts with an existing account, a unique suffix is appended automatically.

Disabling SSO

To disable SSO, remove the GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI environment variables and restart the Platform API. The /api/auth/oauth/status endpoint will return { "sso_enabled": false }.

Users provisioned via SSO retain their accounts but must use password authentication after SSO is disabled.