SSO Configuration

Arbitex supports SAML 2.0 single sign-on, SCIM 2.0 automated provisioning, and flexible authentication method configuration. All SSO settings are managed from Admin → SSO in the admin panel.

Prerequisites

• Org Admin role
• Access to your identity provider’s admin console (Entra ID, Okta, Google Workspace, or equivalent)
• Your IdP’s entity ID, SSO URL, and X.509 signing certificate

---

SAML Identity Providers

The SAML IdPs tab lists all configured SAML identity providers and allows you to add, edit, or remove them.

Add a SAML IdP

1. Navigate to Admin → SSO → SAML IdPs.
2. Click Add Identity Provider.
3. Fill in the required fields:

Field	Required	Description
Name	Yes	Human-readable label for this IdP (e.g., “Corporate Entra ID”)
Entity ID	Yes	The SAML EntityID URI from your IdP’s metadata. Must be unique across all configured IdPs.
SSO URL	Yes	The IdP’s SAML 2.0 HTTP-POST binding endpoint for authentication requests
SLO URL	No	Single logout endpoint URL. Leave blank if your IdP does not support SLO.
X.509 Certificate	Yes	The IdP’s signing certificate in PEM format. You may paste the raw base64 content without the -----BEGIN CERTIFICATE----- header/footer lines.
Active	Yes	Enable or disable this IdP without deleting it

4. Click Save. The IdP appears in the list and is immediately available for authentication if enabled.

Edit or Delete an IdP

• Click the Edit icon on a row to modify any field.
• Click Delete on a row and confirm the deletion prompt.

Caution

Deleting an active IdP will block users who authenticate exclusively through that provider. Disable the IdP first and verify no users are affected before deleting.

API reference

# List all SAML IdPs
GET /api/admin/saml/idp

# Create a new SAML IdP
POST /api/admin/saml/idp
{
  "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": "<base64-encoded-certificate>",
  "is_active": true
}

# Update an existing IdP
PUT /api/admin/saml/idp/{idp_id}
{ ...same fields as POST... }

# Delete an IdP
DELETE /api/admin/saml/idp/{idp_id}

---

SCIM Provisioning

The SCIM Sync tab manages SCIM 2.0 provisioning tokens and shows per-group sync status. SCIM allows your IdP to automatically create, update, and deactivate Arbitex groups as they change in your directory.

Enable SCIM

SCIM provisioning uses a bearer token that your IdP presents with each provisioning request. To generate or rotate the token:

1. Navigate to Admin → SSO → SCIM Sync.
2. Locate the group or org row and click Rotate Token.
3. Review the amber warning — rotating the token immediately invalidates the existing token. Any IdP currently using the old token will fail until reconfigured.
4. Click Confirm Rotate.
5. Copy the displayed token. This is the only time the token is shown. Store it in a secrets manager before dismissing the dialog.
6. Enter the new token in your IdP’s SCIM provisioning configuration.

Danger

Once you dismiss the new-token dialog, the token cannot be retrieved. If lost, rotate again to generate a replacement.

Monitor sync status

The SCIM Sync panel lists all groups with their IdP integration status:

Status	Meaning
Active — IdP-managed	Group has a linked external group ID; SCIM provisioning is configured
Not configured — Local only	Group exists in Arbitex only; membership is managed manually

Groups configured via SCIM show an IdP-managed badge in the Group Management panel as well. Members in IdP-managed groups should not be added or removed manually — changes are overwritten on the next SCIM sync.

API reference

# Rotate the SCIM provisioning token for an org
POST /v1/orgs/{org_id}/scim/token/rotate
# Response: { "token": "<new-token>", "created_at": "<ISO-8601>" }

---

Authentication Methods

The Auth Methods tab controls which authentication mechanisms are available to users in your org. Settings are stored under the auth_methods_config system configuration key.

Available methods

Method	Description
Local (local)	Username and password stored in Arbitex
SAML 2.0 (saml)	Federated login via a configured SAML IdP
OIDC / OAuth (oidc)	Federated login via an OpenID Connect provider

At least one method must remain enabled. The platform rejects a save that would leave all methods disabled.

Configure authentication methods

1. Navigate to Admin → SSO → Auth Methods.
2. Check or uncheck the methods you want to permit.
3. Click Save.

SSO-only mode

Enabling SSO-only mode removes the local login form from the sign-in page and forces all users through a federated provider. To enable it:

1. Enable at least one of SAML 2.0 or OIDC / OAuth.
2. Toggle SSO-only mode on.
3. Click Save.

Lockout risk

If SSO-only mode is enabled but no SSO provider (SAML or OIDC) is active, users will be unable to log in. The admin panel shows a warning in this state. Always verify SSO is working (see Test SSO Connection) before enabling SSO-only mode.

API reference

# Read current auth method configuration
GET /api/admin/config
# Find the entry with key "auth_methods_config":
# { "allowed_methods": ["local", "saml"], "sso_only_mode": false }

# Update auth method configuration
PUT /api/admin/config/auth_methods_config
{
  "allowed_methods": ["saml", "oidc"],
  "sso_only_mode": true
}

---

Test SSO Connection

The SSO Test tab runs a dry-run validation of a SAML IdP configuration before you put it into production. The test checks metadata reachability, certificate validity, and endpoint responsiveness without requiring a real user login.

Run a test

1. Navigate to Admin → SSO → SSO Test.
2. Select the IdP to test from the dropdown.
3. Click Run Test.

The test posts to POST /api/admin/saml/test with the selected IdP’s ID and returns a per-check result panel.

Interpret results

A successful test shows a green header with the IdP name and entity ID, followed by a checklist of passed checks (each marked ✓).

A failed test shows a red header and marks failing checks with ✗. Each check includes a description of what was tested and, on failure, a message explaining the problem.

Common checks include:

Check	What it validates
Metadata reachable	The IdP’s metadata URL responds with valid XML
Certificate valid	The X.509 certificate is not expired and parses correctly
SSO URL reachable	The SSO endpoint returns an expected response code
Entity ID matches	The entity ID in the IdP’s metadata matches what was configured

If the test endpoint is not available in your deployment, the panel shows an amber SSO test endpoint not available notice rather than a failure — this is informational, not an error.

API reference

POST /api/admin/saml/test
{ "idp_id": "<idp-uuid>" }

# Success response:
{
  "success": true,
  "idp_name": "Corporate Entra ID",
  "entity_id": "https://sts.windows.net/<tenant-id>/",
  "checks": [
    { "name": "Metadata reachable", "passed": true, "message": "OK" },
    { "name": "Certificate valid", "passed": true, "message": "Expires 2027-01-15" }
  ]
}

# Failure response:
{
  "success": false,
  "checks": [
    { "name": "Certificate valid", "passed": false, "message": "Certificate expired 2024-03-01" }
  ],
  "error": "One or more checks failed"
}

---

Troubleshooting

Certificate expired

Symptom: SSO test shows “Certificate valid” failed; users receive authentication errors.

Resolution: Obtain the renewed certificate from your IdP admin console. Edit the IdP configuration in Admin → SSO → SAML IdPs and replace the x509_cert value. Run the SSO test to confirm the new certificate passes before notifying users.

Wrong Entity ID

Symptom: SSO test shows “Entity ID matches” failed; the IdP returns an InvalidIssuer or NoSuchProvider error.

Resolution: Compare the Entity ID in the Arbitex IdP record against the entityID attribute in your IdP’s SAML metadata XML. They must match exactly (including trailing slashes and casing). Update whichever side is wrong.

Clock skew

Symptom: Authentication succeeds intermittently or fails with a timestamp-related assertion error in the IdP logs.

Resolution: SAML assertions contain NotBefore and NotOnOrAfter timestamps. If the Arbitex server clock and the IdP clock differ by more than a few seconds, assertions may be rejected. Ensure both systems sync to a reliable NTP source. Most IdPs allow a configurable clock skew tolerance (typically 5 minutes).

IdP not sending groups

Symptom: Users authenticate successfully via SSO but are not assigned to any groups in Arbitex.

Resolution: Group membership in Arbitex is populated via SCIM provisioning — it is not read from SAML assertions at login time. Verify that:

1. SCIM provisioning is configured in your IdP with a valid token (see SCIM Provisioning).
2. The groups in your IdP directory are assigned to the Arbitex SCIM application.
3. The SCIM sync has run at least once after the assignment (most IdPs trigger on demand or within minutes).

You can confirm SCIM linkage by checking Admin → SSO → SCIM Sync and looking for IdP-managed status on the expected groups.

---

See also

• Entra ID SSO Setup — step-by-step Entra ID configuration
• SAML SSO Setup — generic SAML IdP walkthrough
• Entra ID SCIM Setup — Entra-specific SCIM provisioning
• Groups and RBAC — managing group membership and permissions
• User and Group Management — admin panel group operations