> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borghq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity provider guides

> Step-by-step SSO and SCIM settings for Okta, Microsoft Entra ID, Auth0, JumpCloud and Keycloak

These guides cover the settings Odin needs in each identity provider (IdP). Copy the **ACS (Single Sign-On) URL**, **SP Entity ID / Audience** or **Redirect URL** from **Organisation Settings → Single Sign-On** wherever the guide says so. For directory sync, use the **SCIM endpoint** and **SCIM bearer token** from [directory sync](/platform/sso/directory-sync).

| Provider | SAML | OIDC | SCIM | SAML single logout |
| - | - | - | - | - |
| [Okta](#okta) | ✓ | ✓ | ✓ | ✓ |
| [Microsoft Entra ID](#microsoft-entra-id) | ✓ | ✓ | ✓ | ✓ (see note) |
| [Auth0](#auth0) | ✓ | ✓ | — | — |
| [JumpCloud](#jumpcloud) | ✓ | — | ✓ | — |
| [Keycloak](#keycloak) | ✓ | — | — | — |

Other standards-compliant SAML 2.0 and OIDC providers work with the [generic requirements](/platform/sso/set-up#values-for-your-identity-provider). Google Workspace and OneLogin guides will follow.

## Okta

### SAML

<Steps>
  <Step title="Create the app">
    In the Okta Admin Console, go to **Applications → Applications → Create App Integration** and choose **SAML 2.0**.
  </Step>

  <Step title="Configure SAML">
    * **Single sign-on URL**: the Odin **ACS (Single Sign-On) URL**. Keep **Use this for Recipient URL and Destination URL** ticked.
    * **Audience URI (SP Entity ID)**: the Odin **SP Entity ID / Audience**.
    * **Name ID format**: `EmailAddress`. **Application username**: `Email`.
    * **Attribute statements**: `email` = `user.email`, `firstName` = `user.firstName`, `lastName` = `user.lastName`.
  </Step>

  <Step title="Assign people">
    On the **Assignments** tab, assign the people or groups who should use Odin.
  </Step>

  <Step title="Connect Odin">
    On the **Sign On** tab, copy the **Metadata URL** into Odin's **IdP metadata URL**.
  </Step>
</Steps>

<Note>
  Okta's attribute preview shows placeholders such as `user.email`, not real values. Test with a real assigned user.
</Note>

### Single logout

Okta supports SAML single logout with Odin over the HTTP-POST binding.

1. In the app's SAML settings, open **Show Advanced Settings**, tick **Enable Single Logout** and **Allow application to initiate Single Logout**.
2. Set **Single Logout URL** to the ACS host followed by `/api/logout/callback`. For example, if the ACS URL is `https://sso.borghq.io/api/oauth/saml`, use `https://sso.borghq.io/api/logout/callback`.
3. Set **SP Issuer** to the Odin **SP Entity ID / Audience**.
4. Upload the **Signature Certificate** from the ACS host's `/.well-known/saml.cer`, for example `https://sso.borghq.io/.well-known/saml.cer`.
5. Download the app's metadata XML, delete the `SingleLogoutService` element whose binding is `HTTP-Redirect`, and paste the XML into Odin under **…or paste metadata XML**.

<Info>
  Odin's SSO service currently sends logout requests over HTTP-POST only, so the metadata must not offer the HTTP-Redirect logout endpoint. Integrations built with Okta's OIN Wizard do not expose single logout settings; use an app created with **Create App Integration**.
</Info>

### OIDC

1. **Create App Integration → OIDC - OpenID Connect → Web Application**.
2. **Sign-in redirect URIs**: the Odin **Redirect URL**. Grant type: **Authorization Code**.
3. Assign people on the **Assignments** tab.
4. In Odin, use the discovery URL `https://<your-okta-domain>/.well-known/openid-configuration`, with the app's **Client ID** and **Client secret**.

### Directory sync

1. In Odin, create a directory with provider **Okta SCIM 2.0**.
2. In Okta, add a SCIM-capable app such as **SCIM 2.0 Test App (OAuth Bearer Token)** from the catalogue, or enable SCIM provisioning on your Odin app.
3. On **Provisioning → Integration**, enable the API integration. Set the **SCIM 2.0 Base Url** to the Odin **SCIM endpoint** and the **OAuth Bearer Token** to the Odin **SCIM bearer token**, then select **Test API Credentials** and save.
4. On **Provisioning → To App**, enable **Create Users**, **Update User Attributes** and **Deactivate Users**. Leave **Sync Password** off.
5. Assign people or groups. For role mapping, add the mapped groups on **Push Groups**.

## Microsoft Entra ID

### SAML

<Steps>
  <Step title="Create the enterprise application">
    In the [Microsoft Entra admin centre](https://entra.microsoft.com), go to **Enterprise applications → New application → Create your own application**, name it and choose **Integrate any other application you don't find in the gallery (Non-gallery)**.
  </Step>

  <Step title="Basic SAML configuration">
    Open **Single sign-on → SAML** and edit **Basic SAML Configuration**:

    * **Identifier (Entity ID)**: the Odin **SP Entity ID / Audience**
    * **Reply URL (Assertion Consumer Service URL)**: the Odin **ACS (Single Sign-On) URL**
    * **Logout Url**: leave **empty**. See the note below.
  </Step>

  <Step title="Add an email claim">
    Under **Attributes & Claims**, add a claim named `email` whose source attribute is `user.mail`, or another attribute that holds the person's work email. Optionally add `firstName` (`user.givenname`) and `lastName` (`user.surname`).
  </Step>

  <Step title="Restrict and assign">
    Under **Properties**, set **Assignment required?** to **Yes**. Under **Users and groups**, assign the people who should use Odin.
  </Step>

  <Step title="Connect Odin">
    Copy the **App Federation Metadata Url** from the **SAML Certificates** section into Odin's **IdP metadata URL**.
  </Step>
</Steps>

<Warning>
  Add the explicit `email` claim. Entra leaves its built-in email claim out of the token when the address's domain is not verified in your Entra tenant. Without an email, Odin falls back to the sign-in name (often `…@<tenant>.onmicrosoft.com`) and refuses it.
</Warning>

<Note>
  **Signing out:** with **Logout Url** empty, signing out of Odin ends the Odin session, then signs the person out of Entra and shows Microsoft's "You signed out of your account" page. If you set a Logout Url, Entra replies in a format Odin's SSO service cannot read yet, and people see an error after signing out.
</Note>

### OIDC

1. Go to **App registrations → New registration**. Choose **Accounts in this organizational directory only** and add a **Web** redirect URI set to the Odin **Redirect URL**.
2. Under **Certificates & secrets**, create a **client secret**.
3. Under **Token configuration**, add the optional ID-token claims `email`, `given_name` and `family_name`.
4. Under **API permissions**, make sure `openid`, `profile` and `email` are granted, and grant admin consent.
5. To restrict access, open the matching **Enterprise application**, set **Assignment required?** to **Yes**, and assign people.
6. In Odin, use `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration` with the **Application (client) ID** and the client secret.

### Directory sync

1. In Odin, create a directory with provider **Microsoft Entra ID SCIM 2.0**.
2. In your Entra **Enterprise application**, open **Provisioning**, set **Provisioning Mode** to **Automatic**, and enter the Odin **SCIM endpoint** as **Tenant URL** and the **SCIM bearer token** as **Secret Token**. Select **Test Connection**, save, and start provisioning.
3. Entra sends each person's `mail` as their work email. People without a `mail` value are sent with their sign-in name, and Odin ignores them unless that name is on a verified domain.
4. Entra provisions everyone assigned to the application. Assigning groups, which [role mapping](/platform/sso/directory-sync#role-mapping) needs, requires Microsoft Entra ID P1 or higher. On Entra ID Free, leave **Directory manages roles** off and manage roles in Odin.

<Warning>
  If a person is disabled in Entra and later re-enabled, Entra may report *SystemForCrossDomainIdentityManagementServiceIncompatible* for that person. Contact [mail@borghq.io](mailto:mail@borghq.io) if this happens.
</Warning>

## Auth0

<Warning>
  Before connecting Auth0, turn off public sign-ups on your database connection (**Authentication → Database → your connection → Disable Sign Ups**), or require email verification. Odin refuses accounts Auth0 marks as unverified, but people should not be able to create accounts for your domain at all.
</Warning>

### SAML

1. **Applications → Create Application → Regular Web Applications**.
2. On **Addons**, enable **SAML2 Web App**. Set **Application Callback URL** to the Odin **ACS (Single Sign-On) URL**.
3. In **Settings**, set:

   ```json theme={null}
   {
     "audience": "<Odin SP Entity ID / Audience>",
     "recipient": "<Odin ACS URL>",
     "destination": "<Odin ACS URL>",
     "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
     "nameIdentifierProbes": ["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
   }
   ```

   Do not add a `logout` block: single logout with Auth0 is not supported yet.
4. Enable your user connection for the application on its **Connections** tab.
5. In Odin, use the metadata URL `https://<your-tenant>/samlp/metadata/<client-id>`.

### OIDC

1. **Applications → Create Application → Regular Web Applications**.
2. **Allowed Callback URLs**: the Odin **Redirect URL**.
3. **Credentials → Authentication Method**: **Client Secret (Basic)**.
4. In Odin, use `https://<your-tenant>/.well-known/openid-configuration` with the **Client ID** and **Client Secret**.

## JumpCloud

### SAML

1. Go to **SSO Applications → Add New Application → Custom Application**.
2. Select **Manage Single Sign-On (SSO)** with **Configure SSO with SAML**. Also select **Export users to this app (Provisioning)** if you want directory sync.
3. On the **SSO** tab, set:
   * **IdP Entity ID**: any unique value, for example your console URL followed by `/odin`
   * **SP Entity ID**: the Odin **SP Entity ID / Audience**
   * **ACS URL**: the Odin **ACS (Single Sign-On) URL**
   * **SAMLSubject NameID**: `email`, with format `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
   * **Attributes**: `email` → `email`, `firstName` → `firstname`, `lastName` → `lastname`
4. Grant access by binding **User Groups** to the application.
5. Select **Export Metadata** and paste the XML into Odin. JumpCloud does not publish a metadata URL.

JumpCloud does not offer SAML single logout. Odin signs people out of Odin only.

### Directory sync

1. In Odin, create a directory with provider **JumpCloud SCIM 2.0**.
2. On the application's **Provisioning** tab, choose **SCIM API** with **Bearer token**. Enter the Odin **SCIM endpoint** as **Base URL** and the **SCIM bearer token** as **Token Key**.
3. Enter an unused **Test User Email** and **Test User Group Name**, pick a **Source User** and **Source User Group**, then select **Test Connection** and **Activate**.
4. User groups bound to the application are pushed to Odin. Name them to match your [role mapping](/platform/sso/directory-sync#role-mapping), for example `Odin-Admins`.

<Note>
  Users created through the JumpCloud API start as **staged** and cannot sign in until they are activated.
</Note>

## Keycloak

### SAML

1. In your realm, go to **Clients → Create client**. Choose **SAML** and set **Client ID** to the Odin **SP Entity ID / Audience**.
2. Set **Valid redirect URIs** and **Assertion Consumer Service POST Binding URL** to the Odin **ACS (Single Sign-On) URL**.
3. Set **Name ID format** to `email` and turn on **Force name ID format**.
4. On the **Keys** tab, turn **Client signature required** off. Odin's SSO service does not sign authentication requests yet, so Keycloak otherwise answers "Invalid requester".
5. On **Client scopes → Mappers**, add **User Property** mappers for `email`, `firstName` and `lastName`, with SAML attribute names matching those properties.
6. In Odin, use the metadata URL `https://<keycloak-host>/realms/<realm>/protocol/saml/descriptor`.

Single logout with Keycloak is not supported yet. Odin signs people out of Odin only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.