SAML SSO

Arbitex supports SAML 2.0 single sign-on as a Service Provider (SP). Enterprise organizations can configure any SAML 2.0-compliant Identity Provider (IdP) — Microsoft Entra ID, Okta, OneLogin, Google Workspace, and others. Users authenticate through your IdP and Arbitex provisions their account automatically (JIT provisioning).

SP endpoints

Arbitex acts as the SAML Service Provider. The following endpoints are used for SAML integration:

Endpoint	URL	Purpose
SP metadata	`GET https://api.arbitex.ai/api/auth/saml/metadata`	SP metadata XML for IdP configuration
SP-initiated login	`GET https://api.arbitex.ai/api/auth/saml/login?idp_id={uuid}`	Initiates SP-initiated SSO flow
Assertion Consumer Service	`POST https://api.arbitex.ai/api/auth/saml/acs`	Receives and processes SAML Response from IdP
Single Logout	`GET https://api.arbitex.ai/api/auth/saml/slo?idp_id={uuid}`	SP-initiated single logout

How SAML SSO works

sequenceDiagram
    participant User
    participant Arbitex as Arbitex SP<br/>(api.arbitex.ai)
    participant IdP as Identity Provider

    User->>Arbitex: GET /api/auth/saml/login?idp_id={uuid}
    Note over Arbitex: Look up IdP config<br/>Generate AuthnRequest
    Arbitex-->>User: { redirect_url }
    User->>IdP: Redirect to SSO URL with AuthnRequest
    Note over IdP: User authenticates<br/>(password + MFA per IdP policy)
    IdP->>Arbitex: POST /api/auth/saml/acs (SAMLResponse)
    Note over Arbitex: Parse SAMLResponse<br/>Look up IdP by Issuer<br/>Validate signature + cert<br/>Extract attributes
    Note over Arbitex: JIT-provision user if new<br/>Sync group memberships
    Arbitex-->>User: { access_token, refresh_token, user }

Arbitex supports both SP-initiated and IdP-initiated flows. The ACS endpoint handles both.

Step 1: Retrieve SP metadata

The SP metadata XML contains all information your IdP needs to configure the SAML integration:

GET https://api.arbitex.ai/api/auth/saml/metadata

The metadata XML includes:

Entity ID: arbitex
ACS URL: https://api.arbitex.ai/api/auth/saml/acs (POST binding)
SLO URL: https://api.arbitex.ai/api/auth/saml/slo (redirect binding)
NameID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Download or copy the metadata XML for use in Step 2.

Step 2: Configure your IdP

In your Identity Provider’s admin console, create a new SAML application using the Arbitex SP metadata. The steps vary by IdP:

Microsoft Entra ID

Navigate to Microsoft Entra ID → Enterprise applications → New application → Create your own application.
Select Integrate any other application you don’t find in the gallery (Non-gallery).
Name the application (e.g., Arbitex Gateway) and click Create.
Go to Single sign-on → SAML.
Click Upload metadata file and upload the Arbitex SP metadata XML, or configure manually:
- Entity ID (Identifier): arbitex
- Reply URL (ACS URL): https://api.arbitex.ai/api/auth/saml/acs
- Sign on URL: https://api.arbitex.ai/api/auth/saml/login?idp_id={your-idp-uuid} (fill in after Step 3)
Under Attributes & Claims, configure the attribute mappings. See Attribute mapping below.
Download the SAML Signing Certificate (Base64 format) — you’ll need this in Step 3.
Note the Login URL (SSO URL) and Azure AD Identifier (entity ID) from the SAML Certificates section.

Okta

Navigate to Applications → Create App Integration → SAML 2.0.
Set the Single sign-on URL to https://api.arbitex.ai/api/auth/saml/acs.
Set the Audience URI (SP Entity ID) to arbitex.
Configure attribute statements. See Attribute mapping below.
Complete setup and download the IdP metadata or note the SSO URL, entity ID, and signing certificate.

Step 3: Register the IdP in Arbitex

After configuring your IdP, register it in Arbitex using the admin API. Requires admin role.

POST https://api.arbitex.ai/api/admin/saml/idp
Authorization: Bearer arb_live_your-admin-key
Content-Type: application/json

{
  "name": "Corporate Entra ID",
  "entity_id": "https://sts.windows.net/{tenant_id}/",
  "sso_url": "https://login.microsoftonline.com/{tenant_id}/saml2",
  "slo_url": "https://login.microsoftonline.com/{tenant_id}/saml2",
  "x509_cert": "MIIEVzCCAj+gAwIBAgIQHf...(base64 certificate, no PEM headers)",
  "is_active": true,
  "attribute_mapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "username": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    "groups": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
  }
}

Response (201 Created):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Corporate Entra ID",
  "entity_id": "https://sts.windows.net/{tenant_id}/",
  "sso_url": "https://login.microsoftonline.com/{tenant_id}/saml2",
  "slo_url": "https://login.microsoftonline.com/{tenant_id}/saml2",
  "is_active": true,
  "created_at": "2026-03-09T00:00:00Z"
}

Note the id field — this is your IdP UUID, used in the login URL.

`x509_cert` format

Provide the Base64-encoded certificate content without PEM headers. Remove the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines:

# Extract the cert body from PEM:
cat idp-cert.pem | grep -v "^-----" | tr -d '\n'

`attribute_mapping` fields

Field	Required	Description
`email`	Required	SAML attribute name that contains the user’s email address. Used as the unique identifier for JIT provisioning.
`username`	Optional	Display name for the user. Falls back to email prefix if not provided.
`groups`	Optional	SAML attribute name that contains group membership values. Used for group mapping.

Construct the login URL using the idp_id from Step 3:

https://api.arbitex.ai/api/auth/saml/login?idp_id=3fa85f64-5717-4562-b3fc-2c963f66afa6

Open this URL in a browser. You are redirected to your IdP’s SSO login page. After authentication, the IdP posts the SAML Response to the ACS endpoint, and Arbitex returns a JWT access token.

Verify the response includes:

access_token — platform JWT for the authenticated user
refresh_token
user object with the correct email

If the login fails, see Troubleshooting below.

Attribute mapping

SAML assertions carry user attributes as AttributeStatement elements. Arbitex maps these to platform fields using the attribute_mapping configuration you set in Step 3.

Microsoft Entra ID default mappings

Arbitex field	Entra ID attribute URI
`email`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
`username`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
`groups`	`http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`

For Entra ID group claims, the attribute value is the Entra Object ID of the group (e.g., a1b2c3d4-...). Configure Arbitex groups with entra_ad_group_id set to match these Object IDs. See Entra ID SCIM provisioning for group configuration details.

Okta default mappings

Arbitex field	Okta attribute name
`email`	`user.email`
`username`	`user.displayName`
`groups`	`user.groups`

Group mapping

When the SAML assertion includes a groups attribute, Arbitex synchronizes group memberships for the authenticated user. Group matching works by:

Matching the SAML group value against Group.name in Arbitex
Matching the SAML group value against Group.entra_ad_group_id in Arbitex

If a match is found and the user is not already a member, they are added to the group. Group memberships from SAML are additive — existing memberships are not removed.

Group membership is effective immediately after login — Policy Engine rules that check user_groups apply to the user’s next request.

Managing IdP configurations

List all IdPs

GET https://api.arbitex.ai/api/admin/saml/idp
Authorization: Bearer arb_live_your-admin-key

Get a single IdP

GET https://api.arbitex.ai/api/admin/saml/idp/{idp_id}
Authorization: Bearer arb_live_your-admin-key

Update an IdP (partial update)

PUT https://api.arbitex.ai/api/admin/saml/idp/{idp_id}
Authorization: Bearer arb_live_your-admin-key
Content-Type: application/json

{
  "x509_cert": "MIIEVzCCAj+gAwI...(new certificate)",
  "is_active": true
}

Only fields included in the request body are updated.

Disable an IdP

Set is_active: false to prevent new logins without deleting the configuration:

PUT https://api.arbitex.ai/api/admin/saml/idp/{idp_id}
Authorization: Bearer arb_live_your-admin-key
Content-Type: application/json

{ "is_active": false }

Delete an IdP

DELETE https://api.arbitex.ai/api/admin/saml/idp/{idp_id}
Authorization: Bearer arb_live_your-admin-key

Permanent deletion. Users authenticated through this IdP retain their accounts but cannot log in via SAML until a new IdP is configured.

Certificate rotation

When your IdP rotates its signing certificate:

Obtain the new certificate from your IdP.
Update the IdP configuration in Arbitex with the new x509_cert value (Step 3 format — no PEM headers).
Verify the update with a test login.

Arbitex validates the SAML Response signature against the stored certificate. If the certificate is expired or mismatched, authentication fails with a 401.

Plan for certificate rotation before expiry. Most IdP certificates have a 3-year validity period. Set a calendar reminder 30 days before expiry.

Single logout

To initiate SP-initiated single logout, redirect the user to the SLO endpoint:

GET https://api.arbitex.ai/api/auth/saml/slo?idp_id={idp_id}
Authorization: Bearer arb_live_user-token

Arbitex generates a SAML LogoutRequest using the user’s stored NameID and SessionIndex (captured at login) and returns the IdP SLO redirect URL.

If the IdP does not support SLO (no slo_url configured), a 400 is returned. In this case, handle logout by clearing the local session — the IdP session remains active.

JIT user provisioning

Users who authenticate via SAML for the first time are provisioned automatically:

Field	Source
Email	`email` attribute from SAML assertion (or NameID)
Username	`username` attribute, or email prefix if not mapped
Role	`USER` (default) — admin role must be assigned separately
Tenant	Set to the IdP’s tenant ID at provisioning time

Accounts are created with a random password. Users cannot log in via password — SAML is their only authentication method unless an admin sets a password separately.

Troubleshooting

`401 Invalid SAML response`

The SAML Response signature failed validation. Common causes:

Wrong x509_cert in the IdP configuration — update with the correct certificate from your IdP
Certificate has been rotated in the IdP but not updated in Arbitex — rotate the certificate (see Certificate rotation)
Clock skew between Arbitex and IdP — SAML responses have a short validity window (typically 5 minutes)

`400 No active IdP configuration found for issuer`

The Issuer in the SAML Response does not match any entity_id in Arbitex. Verify that the entity_id in the Arbitex IdP configuration exactly matches the EntityID in your IdP’s metadata or SAML Response.

`401 No email found in SAML assertion`

The email attribute is missing from the SAML assertion. Check the attribute_mapping configuration and verify the IdP is sending the attribute under the expected name.

`400 SAML IdP is not active`

The IdP configuration has is_active: false. Enable it:

PUT /api/admin/saml/idp/{idp_id}
{ "is_active": true }