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

ARX provides native OpenID Connect (OIDC) single sign-on integrations for Okta, Microsoft Entra ID (formerly Azure AD), and Google Workspace. This guide covers the SSO flow, provider configuration, environment variables, and just-in-time (JIT) user provisioning.

Architecture¶

The OIDC SSO implementation uses the standard authorization code grant flow. ARX acts as the relying party (RP). The flow involves three endpoints:

• POST /v1/auth/sso/authorize -- Initiates the SSO flow and returns the provider's authorization URL.
• POST /v1/auth/sso/callback -- Handles the callback after the user authenticates, exchanges the authorization code for tokens, and provisions the user.
• GET /v1/auth/sso/providers -- Lists configured SSO providers and their availability.

SSO Flow¶

Step 1: Initiate Authorization¶

The client sends a POST request to start the SSO flow:

curl -X POST "https://api.arxsec.io/v1/auth/sso/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "okta",
    "domain": "acme.okta.com"
  }'

The provider field accepts okta, microsoft, or google. The optional domain field can be used for multi-tenant configurations.

The response contains a redirect_url:

{
  "redirect_url": "https://acme.okta.com/oauth2/default/v1/authorize?response_type=code&client_id=...&redirect_uri=https://api.arxsec.io/v1/auth/sso/callback&scope=openid+profile+email&state=..."
}

A cryptographically random state parameter is generated and stored server-side for CSRF protection. The client redirects the user's browser to this URL.

Step 2: User Authenticates with Provider¶

The user authenticates with their identity provider using their organizational credentials and any MFA policies configured at the provider level. ARX does not control or have visibility into this step.

Step 3: Handle Callback¶

After successful authentication, the provider redirects the user back with an authorization code. The client posts the code to the callback endpoint:

curl -X POST "https://api.arxsec.io/v1/auth/sso/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTHORIZATION_CODE",
    "state": "STATE_TOKEN",
    "provider": "okta"
  }'

ARX performs the following operations:

1. Validates the state parameter against the stored value (CSRF protection).
2. Exchanges the authorization code for an ID token and access token at the provider's token endpoint.
3. Validates the ID token signature (RS256 via JWKS), issuer, and audience.
4. Extracts the sub, email (or preferred_username), and name claims.
5. Performs JIT user provisioning (creates the user if they do not exist).
6. Returns the access token and user profile.

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "user": {
    "id": "a1b2c3d4-...",
    "org_id": "e5f6a7b8-...",
    "email": "jane@acme.com",
    "role": "viewer",
    "full_name": "Jane Doe",
    "sso_provider": "okta"
  }
}

Configuring Okta¶

In the Okta Admin Console¶

1. Navigate to Applications > Create App Integration.
2. Select OIDC - OpenID Connect and Web Application.
3. Set the Sign-in redirect URI to https://api.arxsec.io/v1/auth/sso/callback.
4. Set Sign-out redirect URI (optional): https://app.arxsec.io/login.
5. Under Assignments, assign the application to the appropriate users or groups.
6. Copy the Client ID and Client Secret from the application settings.
7. Note your Okta domain (e.g., acme.okta.com).

Environment Variables¶

OKTA_DOMAIN=acme.okta.com
OKTA_CLIENT_ID=0oa1b2c3d4e5f6g7h8i9
OKTA_CLIENT_SECRET=your-client-secret

Token Validation Parameters¶

Configuring Microsoft Entra ID¶

In the Azure Portal¶

1. Navigate to Microsoft Entra ID > App registrations > New registration.
2. Set the Redirect URI to https://api.arxsec.io/v1/auth/sso/callback (Web platform).
3. Under Certificates & secrets, create a new client secret and copy the value.
4. Under API permissions, ensure openid, profile, and email are granted as delegated permissions.
5. Note the Application (client) ID and Directory (tenant) ID from the Overview page.

Environment Variables¶

MICROSOFT_TENANT_ID=your-tenant-id
MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_CLIENT_SECRET=your-client-secret

Token Validation Parameters¶

Configuring Google Workspace¶

In the Google Cloud Console¶

1. Navigate to APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client ID.
2. Select Web application as the application type.
3. Add https://api.arxsec.io/v1/auth/sso/callback to the Authorized redirect URIs.
4. Copy the Client ID and Client Secret.

Environment Variables¶

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Token Validation Parameters¶

JIT User Provisioning¶

When a user authenticates via OIDC SSO for the first time, ARX automatically creates a user record with the following attributes:

• Email: Extracted from the email or preferred_username claim.
• Full name: Extracted from the name claim.
• SSO subject: The sub claim, used as a stable identifier for subsequent logins.
• SSO provider: The provider name (okta, microsoft, or google).
• Role: Defaults to viewer. Administrators can change roles after provisioning, or use SCIM group-to-role mapping for automated role assignment.

JIT-provisioned users are associated with an organization based on domain matching or the SSO configuration.

Checking Provider Availability¶

To determine which SSO providers are configured, call:

curl "https://api.arxsec.io/v1/auth/sso/providers"

The response lists each provider with a configured boolean:

{
  "providers": [
    {"provider": "okta", "configured": true},
    {"provider": "microsoft", "configured": false},
    {"provider": "google", "configured": true},
    {"provider": "auth0", "configured": true},
    {"provider": "supabase", "configured": true}
  ]
}

A provider is considered configured when its required environment variables (domain/tenant ID and client ID) are set.

All Environment Variables¶

Security Considerations¶

• State parameter: A cryptographically random state token is generated for every authorization request and validated on callback to prevent CSRF attacks.
• Token validation: ID tokens are validated for signature (RS256 via JWKS), issuer, and audience before extracting claims.
• HTTPS required: All redirect URIs must use HTTPS in production.
• Client secret storage: Store provider client secrets in a secrets manager. Never commit them to source control.
• Token exchange timeout: The HTTP client for token exchange uses a 15-second timeout to prevent hanging requests.

Troubleshooting¶

Related Documentation¶

• Authentication Overview
• SAML 2.0 Setup
• SCIM 2.0 Provisioning
• RBAC & Roles