Single Sign-On (SSO) Setup

SSO lets your organization authenticate DataRecs users through your corporate Identity Provider instead of the default email/password flow. Once enabled, user lifecycle management — creation, profile updates, deactivation — can be handled automatically via SCIM provisioning.

Overview

Centralised authentication

Users sign in through your corporate IdP (Entra ID, Okta, Google Workspace) using OIDC. No separate DataRecs passwords to manage.

Automatic user provisioning

SCIM 2.0 integration pushes user creation, updates, and deactivation from your IdP to DataRecs in real time.

Group management

IdP groups sync to DataRecs via SCIM, giving you centralised control over team membership and workspace access.

Break-glass access

Designated administrators retain legacy login access in case the IdP is unavailable or misconfigured.

Supported providers

Provider	SSO (OIDC)	SCIM 2.0 provisioning
Microsoft Entra ID	✓	✓
Okta	✓	✓
OneLogin	✓	✓
Google Workspace	✓	—

What changes after migration

• Authentication: Users log in via your IdP instead of email/password. The DataRecs login page redirects to your IdP’s authorization endpoint.
• User lifecycle: If SCIM is configured, your IdP manages user creation, profile updates, and deactivation. Manual user management in DataRecs still works alongside SCIM.
• Break-glass admins: Designated owner/admin accounts retain access to the legacy login path, ensuring you can always reach the platform even if the IdP is down.
• Existing data: Roles, permissions, workspaces, jobs, and all other data are unaffected. Nothing is deleted or modified during migration.

Security model

• OIDC Authorization Code Flow with PKCE — the authorization code is exchanged for tokens using a code verifier, preventing interception attacks.
• SCIM bearer token authentication — tokens follow the format dtrcs-scim:{token_id}:{secret} and are hashed with argon2id before storage. The plaintext is never persisted.
• Envelope encryption — all stored SSO credentials (client ID, client secret, issuer URL) are envelope-encrypted using the tenant’s dedicated encryption key in HashiCorp Vault.
• Ephemeral OIDC state — state, nonce, and code_verifier parameters are stored in NATS KV with a 5-minute TTL and deleted immediately after use.

Prerequisites

Before you begin, confirm you have:

• Tenant owner or admin role in DataRecs.
• Admin access to your Identity Provider:
  • Microsoft Entra ID: Global Administrator or Application Administrator
  • Okta: Super Admin
  • Google Workspace: Admin with access to Google Cloud Console
• The DataRecs callback URL for your environment:

  https://{your-datarecs-api-domain}/auth/sso/callback

• The DataRecs SCIM endpoint (if configuring provisioning):

  https://{your-datarecs-api-domain}/scim/v2

Step 1 — Configure your Identity Provider

Register DataRecs as an application in your IdP. The exact steps depend on your provider.

Microsoft Entra ID

Register the OIDC application

1. Go to Microsoft Entra admin center → Identity → Applications → App registrations → New registration.
2. Set the Name to something recognisable, e.g. DataRecs SSO.
3. Under Supported account types, select Accounts in this organizational directory only (single tenant).
4. Under Redirect URI, select Web and enter:

   https://{your-datarecs-api-domain}/auth/sso/callback

5. Click Register.
6. On the Overview page, note the Application (client) ID and Directory (tenant) ID.
7. Go to Certificates & secrets → New client secret. Set an expiry and click Add. Copy the Value immediately — it is only shown once.
8. Go to API permissions → verify that User.Read (Delegated) is listed. If not, add it. Click Grant admin consent for {your org}.

(Optional) Configure SCIM provisioning

1. Go to Enterprise applications → New application → Create your own application.
2. Select Integrate any other application you don’t find in the gallery (Non-gallery) and name it DataRecs SCIM Provisioning.
3. Open the new application and go to Provisioning → set Provisioning Mode to Automatic.
4. Under Admin Credentials, enter:
   • Tenant URL: https://{your-datarecs-api-domain}/scim/v2
   • Secret Token: the SCIM bearer token from DataRecs (generated in Step 2)
5. Click Test Connection to verify connectivity, then Save.
6. Under Mappings, configure attribute mappings for users and groups as needed.
7. Set Provisioning Status to On and save.

Values you’ll need for DataRecs:

• Application (client) ID
• Directory (tenant) ID
• Client secret value

Okta

Create the OIDC application

1. Go to Okta Admin Console → Applications → Create App Integration.
2. Select OIDC - OpenID Connect and Web Application. Click Next.
3. Set the Sign-in redirect URI to:

   https://{your-datarecs-api-domain}/auth/sso/callback

4. Under Assignments, assign the users or groups that should have access.
5. Click Save.
6. On the application’s General tab, note the Client ID and Client secret.

(Optional) Configure SCIM provisioning

1. Go to Applications → Browse App Catalog → search for SCIM 2.0 Test App (Header Auth) → Add Integration.
2. Name it DataRecs SCIM and click Done.
3. Go to the Provisioning tab → Configure API Integration → check Enable API integration.
4. Enter:
   • Base URL: https://{your-datarecs-api-domain}/scim/v2
   • API Token: the SCIM bearer token from DataRecs (generated in Step 2)
5. Click Test API Credentials to verify, then Save.
6. Under Provisioning → To App, enable:
   • ✓ Create Users
   • ✓ Update User Attributes
   • ✓ Deactivate Users
7. Click Save.

Values you’ll need for DataRecs:

• Client ID (from the OIDC app)
• Client secret (from the OIDC app)
• Okta domain (your org URL, e.g. your-org.okta.com)

Google Workspace

Create the OAuth client

1. Go to Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Set Application type to Web application.
3. Under Authorized redirect URIs, add:

   https://{your-datarecs-api-domain}/auth/sso/callback

4. Click Create. Note the Client ID and Client secret.
5. Go to OAuth consent screen and ensure the requested scopes include openid, email, and profile.

Note

Google Workspace does not require a tenant directory ID — it uses a fixed OIDC issuer (https://accounts.google.com). SCIM provisioning is not currently supported for Google Workspace connections.

Values you’ll need for DataRecs:

• Client ID
• Client secret

OneLogin

Create the OIDC application

1. Go to OneLogin Admin → Applications → Add App.
2. Search for OpenId Connect (OIDC) and select it.
3. Set the Display Name to something recognisable, e.g. DataRecs SSO.
4. Click Save.
5. Go to the Configuration tab and set:
   • Redirect URI: https://{your-datarecs-api-domain}/auth/sso/callback
   • Login URL: https://{your-datarecs-console-domain}
6. Click Save.
7. Go to the SSO tab and note the Client ID and Client Secret (click “Show client secret”).
8. Go to the Access tab and assign the users or roles that should have access.

(Optional) Configure SCIM provisioning

Note

OneLogin requires a separate app for SCIM provisioning. The OIDC app handles SSO login; the SCIM app handles user lifecycle management.

1. Go to Applications → Add App → search for SCIM Provisioner with SAML (SCIM v2 Enterprise) → select it.
2. Set the Display Name to DataRecs SCIM and click Save.
3. Go to the Configuration tab:
   • Click Enable under API Status
   • Set SCIM Base URL: https://{your-datarecs-api-domain}/scim/v2
   • Set SCIM Bearer Token: the SCIM token from DataRecs (generated in Step 2, without the Bearer prefix)
4. Click Save.
5. Go to the Provisioning tab:
   • Check Enable provisioning
   • Uncheck all “Require admin approval” boxes (optional, for automatic provisioning)
6. Click Save.
7. Assign the same users/roles to this app as the OIDC app.

Caution

When entering the SCIM Bearer Token in OneLogin, enter only the token value (dtrcs-scim:token-id:secret). Do not include the Bearer prefix — OneLogin adds it automatically.

Values you’ll need for DataRecs:

• Client ID (from the OIDC app’s SSO tab)
• Client secret (from the OIDC app’s SSO tab)
• OneLogin subdomain (your org URL, e.g. your-company.onelogin.com)

Step 2 — Create the SSO connection in DataRecs

With your IdP configured, create the SSO connection in DataRecs and link it to your tenant.

Console

1. Navigate to Settings → SSO → Configure SSO.
2. Select your Identity Provider (Microsoft Entra ID, Okta, Google Workspace, or OneLogin).
3. Enter the credentials from Step 1 (client ID, client secret, and tenant/directory ID if applicable).
4. Click Save.
5. DataRecs generates a SCIM bearer token and displays it once. Copy it immediately and store it securely — you will not see it again.

CLI

Note

SSO connection creation is not yet available via the CLI. Use the Console or REST API.

REST API

curl -X POST https://{your-datarecs-api-domain}/sso/connection \
  -H "Authorization: Bearer {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production SSO",
    "provider_type": "microsoft_entra_id",
    "client_id": "{client-id}",
    "client_secret": "{client-secret}",
    "tenant_directory_id": "{directory-tenant-id}"
  }'

Provider-specific notes:

• microsoft_entra_id — tenant_directory_id is the Entra Directory (tenant) ID.
• okta — tenant_directory_id is your Okta org domain (e.g. your-org.okta.com).
• google_workspace — omit tenant_directory_id entirely.

The response includes a scim_token field containing the SCIM bearer token. Copy it immediately. It is only shown once.

{
  "id": "sso_conn_abc123",
  "name": "Production SSO",
  "provider_type": "microsoft_entra_id",
  "status": "active",
  "scim_token": "dtrcs-scim:tok_abc:secret_xyz..."
}

Step 3 — Configure SCIM provisioning (recommended)

SCIM (System for Cross-domain Identity Management) automates user lifecycle management between your IdP and DataRecs. When configured, your IdP pushes changes to DataRecs in real time:

• User creation — new IdP users are automatically provisioned in DataRecs.
• Profile updates — name and email changes sync automatically.
• Deactivation — disabled or removed IdP users are deactivated in DataRecs.
• Group management — IdP group memberships sync to DataRecs groups.

SCIM token format

The token generated in Step 2 follows the format:

dtrcs-scim:{token_id}:{secret}

This is the value you enter as the bearer token / API token / secret token in your IdP’s provisioning configuration.

SCIM endpoint

Enter this as the Tenant URL or Base URL in your IdP:

https://{your-datarecs-api-domain}/scim/v2

Where to enter the token

Refer back to the SCIM provisioning instructions in Step 1 for your specific provider. In summary:

• Entra ID: Enterprise application → Provisioning → Admin Credentials → Secret Token
• Okta: SCIM app → Provisioning → API Integration → API Token
• OneLogin: SCIM app → Configuration → SCIM Bearer Token (without Bearer prefix)

Supported SCIM operations

Resource	Operations
Users	POST, GET, PUT, PATCH, DELETE
Groups	POST, GET, PATCH, DELETE
ServiceProviderConfig	GET
ResourceTypes	GET
Schemas	GET

Tip

Rotating the SCIM token: You can rotate the SCIM bearer token at any time without disrupting the SSO connection itself. Use the Console (Settings → SSO → Rotate SCIM Token) or the API:

curl -X POST https://{your-datarecs-api-domain}/sso/connection/rotate-scim-token \
  -H "Authorization: Bearer {your-api-key}"

After rotating, update the token in your IdP’s provisioning configuration immediately. The old token is invalidated as soon as the new one is generated.

Step 4 — Test the SSO connection

You can validate the OIDC flow before committing to migration. The test creates a session but does not change your tenant’s authentication mode.

1. In the Console, go to Settings → SSO.
2. Click Test SSO Connection.
3. A new browser window opens and redirects to your IdP’s login page.
4. Sign in with a valid account from your directory.
5. If successful, you are redirected back to the SSO settings page with a confirmation message.

If the test fails, check:

• The redirect URI in your IdP matches https://{your-datarecs-api-domain}/auth/sso/callback exactly.
• The client ID and client secret are correct.
• Admin consent has been granted (Entra ID).
• The user is assigned to the application (Okta).

Caution

The test login creates a session and validates the OIDC flow, but it does not change the tenant’s authentication mode. Your users continue to log in with their current method until you complete the migration in Step 6.

Step 5 — Designate break-glass administrators

Break-glass administrators can log in via the legacy authentication path even after SSO is enabled. This ensures you can always access the platform if your IdP is unavailable or the SSO connection is misconfigured.

At least one user with the owner or admin role must be designated as a break-glass administrator before migration can proceed.

Console

1. Go to User Management.
2. Click on the user you want to designate.
3. In the Identity panel, click Grant Break-glass Access.
4. Confirm the action.

REST API

curl -X PATCH https://{your-datarecs-api-domain}/users/{user-id}/bypass-sso \
  -H "Authorization: Bearer {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{ "bypass_sso": true }'

Danger

Migration will be blocked if no break-glass administrator is designated. The platform enforces this precondition to prevent lockout scenarios.

Step 6 — Migrate to SSO

Once you have an active SSO connection, SCIM provisioning configured (optional), and at least one break-glass admin designated, you can migrate your tenant to SSO authentication.

1. In the Console, go to Settings → SSO.
2. The pre-migration checklist shows your current state: active user count, break-glass accounts, and any warnings.
3. Review the checklist and click Confirm Migration.
4. The migration runs as a background job that:
   • Validates preconditions (active SSO connection, break-glass admin exists, current auth mode is workos)
   • Canonicalises all active user email addresses
   • Validates no duplicate emails or identity bindings exist
   • Flips the tenant’s auth_mode from workos to sso
5. Once complete, all users must log in via the IdP.
6. Break-glass administrators retain access to the legacy login path at /auth/legacy.

Danger

Migration is irreversible. Once auth_mode is set to sso, it cannot be reverted through the UI. Ensure your SSO connection is tested and your break-glass administrators are in place before proceeding.

What happens to existing users and groups

• Existing users are not deleted or modified. Roles, permissions, workspace memberships, and all associated data remain intact.
• On first SSO login, each user is matched by their canonical email address and linked to their IdP identity (idp_subject). This binding is stored and used for all subsequent logins.
• If SCIM is configured, your IdP can push profile updates, provision new users, and manage group memberships going forward.
• Existing manually-created groups are unaffected. SCIM-provisioned groups appear alongside them and are tagged with source='scim' for easy identification.

Identity recovery

Admin tools for handling edge cases after migration:

Action	What it does	When to use
Reset Identity Binding	Clears the stored idp_subject so the user can be relinked on next SSO login.	A user’s IdP account was deleted and recreated with a new subject identifier.
Archive User	Soft-deletes the user, freeing their email address for reprovisioning.	An employee leaves and their email will be reassigned to a new hire.
Full Relink	Clears both idp_subject and external_id for a complete identity reset.	The user needs to be fully unlinked from their previous IdP identity (e.g. IdP migration).

These actions are available in the Console under User Management → {user} → Identity panel, or via the REST API.

Security considerations

• All SSO connection credentials (client_id, client_secret, issuer_url) are envelope-encrypted at rest using the tenant’s dedicated encryption key in HashiCorp Vault.
• SCIM bearer tokens are hashed with argon2id before storage. The plaintext token is never persisted.
• OIDC state parameters (state, nonce, code_verifier) are stored in NATS KV with a 5-minute TTL and deleted immediately after use to prevent replay attacks.
• ID tokens are verified using the IdP’s JWKS (JSON Web Key Set) public keys, with automatic key rotation support.
• The email domain is deterministically encrypted for lookup, preventing cross-tenant data leakage.
• All SSO and SCIM operations emit audit events for compliance tracking.

Troubleshooting

Error code	Meaning	Resolution
SSO_NOT_CONFIGURED	No active SSO connection exists for the email domain.	Verify the SSO connection is active in Settings → SSO.
SSO_IDENTITY_MISMATCH	The IdP subject has changed for an existing user.	An admin needs to reset the identity binding (see Identity recovery).
BREAK_GLASS_REQUIRED	No break-glass administrator is designated.	Designate at least one owner/admin before migrating (see Step 5).
INVALID_STATE	The authentication session expired (5-minute TTL).	Try the login again. If persistent, check for clock skew between your network and DataRecs.
IDP_DISCOVERY_FAILED	Cannot reach the IdP’s OIDC discovery endpoint.	Verify the issuer URL is correct and the IdP’s /.well-known/openid-configuration endpoint is reachable.
SCIM 401 Unauthorized	The SCIM bearer token is invalid or expired.	Rotate the SCIM token and update the value in your IdP’s provisioning configuration.