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

# Configure SSO

> Connect Okta, Microsoft Entra ID, Google Workspace or any SAML 2.0 or OIDC identity provider to Sazabi, and test the connection.

Add Sazabi as an application at your identity provider (IdP), enter the IdP's values in Sazabi, then test the connection. You need to be a Sazabi **owner**.

## Service provider values

Your IdP needs Sazabi's values. Go to [**Settings > Single sign-on**](https://app.sazabi.com/settings/single-sign-on); they're under **Service provider details**, each with a copy button. `sazabi sso connection get` prints them too.

| Value | Used for |
| - | - |
| SAML entity ID | SAML: the audience, also called the SP entity ID or identifier |
| SAML ACS URL | SAML: where your IdP sends the sign-in response |
| SAML metadata URL | SAML: an IdP that can read service provider metadata can import it instead |
| OIDC redirect URL | OIDC: the redirect URI, also called the callback or reply URL |
| Initiate login URL | Where a tile in your IdP's app dashboard sends people to start sign-in; see [Add an app dashboard tile](#add-an-app-dashboard-tile) |

Sazabi doesn't sign its SAML requests, so your IdP doesn't need a service provider certificate.

## Add Sazabi at your identity provider

> [tab] Okta
>
> Okta supports SAML and OIDC. Prefer SAML; these steps use it.
>
> **Step 1**
>
> ### Create the SAML app
>
> In the Okta Admin Console, go to **Applications > Applications** and choose **Create App Integration**. Choose **SAML 2.0** and name the app Sazabi.
>
> **Step 2**
>
> ### Set the SAML settings
>
> Under **SAML Settings**, set:
>
> * **Single sign-on URL**: the **SAML ACS URL**.
> * **Audience URI (SP Entity ID)**: the **SAML entity ID**.
> * **Name ID format**: **Persistent**.
> * **Application username**: **Custom**, with `user.getInternalProperty("id")`. The name ID is then the Okta user ID, which never changes.
>
> **Step 3**
>
> ### Add the attribute statements
>
> Finish creating the app. Then, on its **Sign On** tab, add these attribute statements:
>
> | Name | Value |
> | - | - |
> | `email` | `user.profile.email` |
> | `givenName` | `user.profile.firstName` |
> | `surname` | `user.profile.lastName` |
>
> **Step 4**
>
> ### Assign people
>
> Assign the people and groups who should sign in to Sazabi.
>
> **Step 5**
>
> ### Copy the identity provider values
>
> On the **Sign On** tab, choose **View SAML setup instructions**. Keep it open; it has the three values the connection needs: the identity provider issuer, the single sign-on URL and the X.509 certificate.

> [tab] Microsoft Entra ID (SAML)
>
> Entra supports SAML and OIDC. Prefer SAML: with **Sign on URL** set, My Apps opens Sazabi's sign-in.
>
> **Step 1**
>
> ### Create the enterprise application
>
> In the Microsoft Entra admin center, go to **Entra ID > Enterprise apps > All applications** and choose **New application**. Create your own application, name it Sazabi, and choose the option to integrate an application that isn't in the gallery.
>
> **Step 2**
>
> ### Choose SAML
>
> In the app's **Manage** section, choose **Single sign-on**, then **SAML**.
>
> **Step 3**
>
> ### Set the basic SAML configuration
>
> Edit **Basic SAML Configuration** and set:
>
> * **Identifier (Entity ID)**: the **SAML entity ID**.
> * **Reply URL (Assertion Consumer Service URL)**: the **SAML ACS URL**.
> * **Sign on URL**: the **Initiate login URL**. My Apps then starts sign-in at Sazabi instead of sending a response Sazabi didn't ask for.
>
> **Step 4**
>
> ### Set the name ID and claims
>
> Edit **Attributes & Claims**:
>
> * Open **Unique User Identifier (Name ID)**, choose **Persistent** as the name identifier format and `user.objectid` as the source attribute. The name ID is then the person's Entra object ID, which never changes.
> * Choose **Add new claim** for each row below. Leave **Namespace** empty, so the claim's name is exactly the one in the table. Entra's default claims have URI names such as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`, which Sazabi doesn't read.
>
> | Name | Source attribute |
> | - | - |
> | `email` | `user.mail` |
> | `givenName` | `user.givenname` |
> | `surname` | `user.surname` |
>
> `user.mail` must hold the address people sign in to Sazabi with, on a verified domain. If it doesn't, use `user.userprincipalname`, as long as it isn't on an `onmicrosoft.com` domain.
>
> **Step 5**
>
> ### Assign people
>
> Under **Users and groups**, assign the people and groups who should sign in to Sazabi.
>
> **Step 6**
>
> ### Copy the identity provider values
>
> Under **SAML Certificates**, download **Certificate (Base64)**. Under the app's set-up section, copy **Login URL** and **Microsoft Entra Identifier**. These are the three values the connection needs. Creating the connection needs the certificate; you can also add the **App Federation Metadata Url** as its **Metadata URL**, so Sazabi re-reads Entra's certificates when they rotate.

> [tab] Microsoft Entra ID (OIDC)
>
> **Step 1**
>
> ### Register the app
>
> In the Microsoft Entra admin center, go to **Entra ID > App registrations** and choose **New registration**. Name it Sazabi. Under **Supported account types**, choose the single-tenant option, so only people in your tenant can sign in.
>
> **Step 2**
>
> ### Add the redirect URI
>
> Under **Redirect URI**, choose the **Web** platform and enter the **OIDC redirect URL**. You can also add it later under the app's **Authentication** page.
>
> **Step 3**
>
> ### Copy the client and tenant IDs
>
> Register the app. On its **Overview**, copy the **Application (client) ID** and the **Directory (tenant) ID**.
>
> **Step 4**
>
> ### Create a client secret
>
> Under **Certificates & secrets > Client secrets**, choose **New client secret** and copy its **Value**. Entra shows it only once. Note its expiry; update the connection with a new secret before it expires.
>
> **Step 5**
>
> ### Add the email claim
>
> Under **Token configuration**, choose **Add optional claim**, choose the **ID** token type and add `email`. Entra's ID token already carries `name` when Sazabi asks for the `profile` scope.
>
> For the connection, you need:
>
> * **Issuer URL**: `https://login.microsoftonline.com/<tenant-id>/v2.0`, with your **Directory (tenant) ID**.
> * **Client ID**: the **Application (client) ID**.
> * **Client secret**: the secret's **Value**.

> [tab] Google Workspace
>
> Google Workspace adds custom apps over SAML, so use SAML.
>
> You need to be a super administrator in Google Workspace.
>
> **Step 1**
>
> ### Add a custom SAML app
>
> In the Google Admin console, go to **Apps > Web and mobile apps** and choose **Add app > Add custom SAML app**. Name it Sazabi and continue.
>
> **Step 2**
>
> ### Copy the identity provider values
>
> On **Google Identity Provider details**, copy the **SSO URL** and **Entity ID** and download the **Certificate**. These are the three values the connection needs. Continue.
>
> **Step 3**
>
> ### Set the service provider details
>
> On **Service provider details**, set:
>
> * **ACS URL**: the **SAML ACS URL**.
> * **Entity ID**: the **SAML entity ID**.
> * **Name ID format**: `EMAIL`.
> * **Name ID**: **Primary email**.
>
> **Step 4**
>
> ### Map the attributes
>
> On **Attribute mapping**, choose **Add mapping** for each row below. Pick the Google Directory attribute, and type the app attribute exactly as shown.
>
> | Google Directory attribute | App attribute |
> | - | - |
> | Primary email | `email` |
> | First name | `givenName` |
> | Last name | `surname` |
>
> **Step 5**
>
> ### Turn the app on
>
> Choose **Finish**. Then open the app's **User access** and turn it on for the organizational units or groups who should sign in to Sazabi. New custom apps are off for everyone.
>
> Google's metadata is a downloaded file, not a URL, so leave **Metadata URL** empty and add Google's new certificate before the old one expires. Google's app launcher tile sends a response Sazabi didn't ask for, so people sign in from Sazabi; see [Add an app dashboard tile](#add-an-app-dashboard-tile).

> [tab] OneLogin
>
> OneLogin supports both protocols. Prefer SAML: the steps below use OneLogin's SAML Custom Connector (Advanced).
>
> **Step 1**
>
> ### Add the connector
>
> In the OneLogin admin portal, add the application **SAML Custom Connector (Advanced)**. Name it Sazabi and save.
>
> **Step 2**
>
> ### Set the configuration
>
> On the app's **Configuration** tab, set:
>
> * **Audience (EntityID)**: the **SAML entity ID**.
> * **ACS (Consumer) URL**: the **SAML ACS URL**.
> * **ACS (Consumer) URL Validator**: a regular expression that matches only the **SAML ACS URL**, anchored with `^` and `$` and with each `/` and `.` escaped.
> * **Login URL**: the **Initiate login URL**.
> * **SAML initiator**: **Service Provider**.
> * **SAML nameID format**: **Persistent**.
> * **SAML signature element**: **Assertion**. Sazabi needs the assertion signed.
>
> **Step 3**
>
> ### Add the attributes
>
> Add an attribute named `email` with the person's email address, `givenName` with their first name and `surname` with their last name.
>
> **Step 4**
>
> ### Assign people
>
> Assign the app to the people or roles who should sign in to Sazabi.
>
> **Step 5**
>
> ### Copy the identity provider values
>
> On the app's **SSO** tab, copy the **Issuer URL** and the **SAML 2.0 Endpoint (HTTP)**, and download the **X.509 Certificate**. These are the three values the connection needs.

> [tab] JumpCloud
>
> JumpCloud supports both protocols. Prefer SAML.
>
> **Step 1**
>
> ### Add a custom application
>
> In the JumpCloud Admin Portal, go to **Access > SSO Applications** and choose **+ Add New Application**. Select **Custom Application**, choose **Manage Single Sign-On (SSO)** and **Configure SSO with SAML**. Set the **Display Label** to Sazabi, then **Save Application** and **Configure Application**.
>
> **Step 2**
>
> ### Set the SSO fields
>
> * **IdP Entity ID**: an identifier for JumpCloud in this app. You'll give it to Sazabi.
> * **SP Entity ID**: the **SAML entity ID**.
> * **ACS URLs**: the **SAML ACS URL**.
> * **SAMLSubject NameID**: leave it as `email`, or pick an attribute that never changes for the person.
> * Sign the assertion: JumpCloud signs only the response by default, so choose to sign the assertion, or both.
> * **Login URL**: the **Initiate login URL**.
>
> **Step 3**
>
> ### Add the attributes
>
> Under the attributes section, add three user attributes. Type the **Service Provider Attribute Name** and pick the **JumpCloud Attribute Name**:
>
> | Service Provider Attribute Name | JumpCloud Attribute Name |
> | - | - |
> | `email` | email |
> | `givenName` | firstname |
> | `surname` | lastname |
>
> **Step 4**
>
> ### Authorize people
>
> Save the app. On its **User Groups** tab, select the groups who should sign in to Sazabi.
>
> **Step 5**
>
> ### Copy the identity provider values
>
> Download the app's certificate. Bring back the **IdP Entity ID** you set, the app's **SSO IdP URL** and the certificate.

> [tab] PingOne
>
> PingOne supports both protocols. Prefer SAML.
>
> **Step 1**
>
> ### Add the application
>
> In the PingOne admin console, go to **Applications > Applications** and click the **+** icon. Name the application Sazabi, choose the SAML application type and click **Configure**.
>
> **Step 2**
>
> ### Enter the connection details
>
> Choose **Manually Enter**, then set:
>
> * **ACS URLs**: the **SAML ACS URL**.
> * **Entity ID**: the **SAML entity ID**.
>
> Save. On the **Configuration** tab, set the signing option to sign the assertion, either **Sign Assertion** or **Sign Assertion & Response**.
>
> **Step 3**
>
> ### Map the attributes
>
> On the **Attribute Mappings** tab, keep `saml_subject` mapped to a value that never changes for the person, such as the user ID. Add `email`, `givenName` and `surname`, mapped to the PingOne email address, given name and family name.
>
> **Step 4**
>
> ### Turn the application on
>
> Turn the application on with the toggle in its details panel, and give the groups who should sign in to Sazabi access to it.
>
> **Step 5**
>
> ### Copy the identity provider values
>
> On the **Configuration** tab, copy the **Issuer ID** and the single sign-on service URL, and choose **Download Signing Certificate** in X509 PEM format. These are the three values the connection needs.
>
> Don't use PingOne's **Initiate Single Sign-On URL** on the **Overview** tab as a tile: it starts sign-in from PingOne, which Sazabi refuses.

> [tab] Other SAML 2.0
>
> This covers any other SAML 2.0 IdP. Add Sazabi as a SAML application (service provider). IdPs name the fields differently:
>
> | Sazabi value | Common IdP field names |
> | - | - |
> | **SAML ACS URL** | ACS URL, Reply URL, Single sign-on URL, Assertion Consumer Service URL |
> | **SAML entity ID** | Entity ID, Audience, Audience URI, Identifier, SP entity ID |
> | **Initiate login URL** | Login URL, Sign-on URL, Initiate login URI |
>
> Then set:
>
> * **ACS binding**: HTTP-POST.
> * **Signed assertions**, signed with the certificate you give Sazabi. Signing only the response isn't enough.
> * **Name ID**: a value that never changes for the person, such as a persistent ID. Sazabi identifies people by it.
> * **Attributes**, named exactly:
>
>   | Name | Value |
>   | - | - |
>   | `email` | The person's email address, on a verified domain |
>   | `givenName` | The person's first name |
>   | `surname` | The person's last name |
>
>   Sazabi uses the name ID as the address when there's no `email` attribute.
>
> If your IdP can import service provider metadata, give it the **SAML metadata URL** instead of typing the values. For the connection, bring back:
>
> * The IdP's entity ID, also called its issuer.
> * Its single sign-on URL for the HTTP-Redirect binding. Sazabi sends sign-in requests by redirect, so a URL that accepts only HTTP-POST doesn't work.
> * Its signing certificate. Creating the connection needs it. If the IdP publishes metadata at a URL, also add it as the **Metadata URL**, so Sazabi re-reads the certificates when they rotate.

> [tab] Other OIDC
>
> This covers any OpenID Connect IdP. Register Sazabi as a web application (a confidential client) with:
>
> * **Redirect URI**: the **OIDC redirect URL**. IdPs also call it the callback URL or reply URL.
> * The authorization code flow.
> * The scopes `openid`, `email`, `profile` and `offline_access`. Sazabi requests all four, so if your IdP lists the scopes each app may request, allow all four.
>
> Sazabi identifies people by the ID token's `sub` claim. It reads the address from `email`, which must be on a verified domain, and the person's name from `name`. If your IdP leaves `email` out of the ID token, turn it on for the app.
>
> If the IdP's app dashboard can open a URL for the app, set it to the **Initiate login URL**.
>
> For the connection, bring back the issuer URL, the client ID and the client secret. The issuer URL is the one in the IdP's `/.well-known/openid-configuration` document.

### Other identity providers

These identity providers also support Sazabi's values. Set them in the fields below, then bring back the values in the last columns.

| Identity provider | SAML ACS URL | SAML entity ID | Initiate login URL | SAML values to bring back | OIDC redirect URL | OIDC values to bring back |
| - | - | - | - | - | - | - |
| Rippling | **ACS URL** | **Entity ID** | The app's sign-in URL, if Rippling asks for one | The entity ID, single sign-on URL and certificate in the metadata Rippling gives you for the app | Use SAML | Use SAML |
| AWS IAM Identity Center | **Application ACS URL** | **Application SAML audience** | **Application start URL** | The **IAM Identity Center SAML metadata file**, and the **IAM Identity Center certificate** (**Download**) | Use SAML | Use SAML |
| Auth0 | **Application Callback URL** in the **SAML2 Web App** addon | The addon's `audience` setting | **Application Login URI** | **SAML Protocol URL** on the **Endpoints** tab, the certificate from **Certificates > Download Certificates** (PEM), and the entity ID in Auth0's SAML metadata | **Allowed Callback URLs** | Issuer `https://<Domain>/`, **Client ID** and **Client Secret** on the **Settings** tab |
| Keycloak | **Master SAML Processing URL**, or **Assertion Consumer Service POST Binding URL** | **Client ID** | **Home URL** | The realm's descriptor at `https://<host>/realms/<realm>/protocol/saml/descriptor` (entity ID, single sign-on URL and signing certificate) | **Valid redirect URIs** | Issuer `https://<host>/realms/<realm>`, the **Client ID**, and **Client Secret** on the **Credentials** tab |
| Duo SSO | **Assertion Consumer Service (ACS) URL** | **Entity ID** | **Service Provider Login URL** | **Entity ID**, **Single Sign-On URL** and **Download certificate**, under **Metadata** | **Sign-In Redirect URLs** | **Issuer**, **Client ID** and **Client Secret** on the **Metadata** tab |

For SAML, set the name ID and the `email`, `givenName` and `surname` attributes, and sign the assertion, as described under **Other SAML 2.0**. For OIDC, use the `sub`, `email` and `name` claims and the `openid`, `email`, `profile` and `offline_access` scopes described under **Other OIDC**.

## Create the connection

> [tab] Dashboard
>
> **Step 1**
>
> ### Open the connection form
>
> Go to [**Settings > Single sign-on**](https://app.sazabi.com/settings/single-sign-on) and choose **Set up connection**.
>
> **Step 2**
>
> ### Enter your identity provider's values
>
> Choose **SAML 2.0** or **OpenID Connect**, and enter your IdP's values:
>
> | Field | What to enter |
> | - | - |
> | Identity provider entity ID (SAML) | The IdP's entity ID, also called the issuer |
> | Single sign-on URL (SAML) | The IdP's single sign-on URL |
> | Signing certificate (SAML) | The IdP's signing certificate, in PEM form |
> | Metadata URL (SAML, optional) | The IdP's metadata address. Sazabi re-reads its certificates from it, and keeps the last good certificates if a re-read fails. |
> | Issuer URL (OIDC) | The IdP's issuer, exactly as in its ID tokens. Sazabi reads `/.well-known/openid-configuration` under it. |
> | Client ID (OIDC) | The application's client ID |
> | Client secret (OIDC) | The application's client secret. Sazabi never shows it again; to change it, enter a new one. |
>
> **Step 3**
>
> ### Choose the default role
>
> Choose the **Default role**, Member or Viewer, and whether to **Add people on their first sign-in**. See [Single sign-on](https://docs.sazabi.com/guides/administer/single-sign-on/setup.md#adding-people-on-first-sign-in).

> [tab] CLI
>
> Install and authenticate the CLI per [`/reference/cli`](https://docs.sazabi.com/reference/cli). You need an owner account, or a secret key that can manage SSO (`can_manage_sso`). If the organization already has a connection, `sazabi sso connect` replaces its identity settings.
>
> ```bash theme={"system"}
> # SAML 2.0
> sazabi sso connect --protocol saml \
>   --issuer "http://www.okta.com/exk1example" \
>   --sso-url "https://example.okta.com/app/example/sso/saml" \
>   --certificate-file okta.pem \
>   --default-role member
>
> # OIDC: the client secret is read from a file so it stays out of your shell history
> sazabi sso connect --protocol oidc \
>   --issuer "https://example.okta.com" \
>   --client-id "0oa1example" \
>   --client-secret-file client-secret.txt
> ```
>
> | Flag | What it sets |
> | - | - |
> | `--certificate-file` | An IdP signing certificate. Repeat it, up to twice, while you rotate. |
> | `--metadata-url` | The IdP metadata URL. `none` clears it. |
> | `--default-role` | `member` or `viewer` |
> | `--enable-jit`, `--disable-jit` | Whether people are added on their first sign-in |
> | `--max-session-age` | Seconds before people sign in through the IdP again, or `none` |
> | `--enable`, `--disable` | Whether the connection allows sign-in |
>
> To manage the connection with Terraform, use [`sazabi_sso_connection`](https://docs.sazabi.com/reference/terraform/sazabi_sso_connection) and the [`sazabi_sso_service_provider`](https://docs.sazabi.com/reference/terraform/sazabi_sso_service_provider) data source. Terraform can't run the connection test, which needs a person to sign in.

## Adding people on first sign-in

With **Add people on their first sign-in** on (the default), a person your IdP lets in who isn't a member yet joins the organization at their first sign-in with the connection's **Default role**, Member or Viewer. Each new member counts toward your plan's members. Turn it off to let only existing members sign in through SSO. Change it, and the default role, with **Edit connection**. New people are also added only while **Just-in-time member provisioning** is on under [**Settings > Organization**](https://app.sazabi.com/settings/organization) (on by default), which only owners can change.

People you removed stay removed: an SSO sign-in doesn't add back a member an admin removed. Invite them again from [**Settings > Members**](https://app.sazabi.com/settings/members) to restore access. An invitation to an address on a domain that requires SSO can be accepted only after signing in through SSO as that address.

## Add an app dashboard tile

Sazabi refuses a sign-in response it didn't ask for, so a tile in your IdP's app dashboard must open Sazabi's **Initiate login URL**. The URL starts an ordinary SSO sign-in for your connection. Copy it from **Service provider details**, from `sazabi sso connection get`, or from the `initiate_login_url` attribute of the `sazabi_sso_service_provider` data source. If the connection is deleted or doesn't allow sign-in, the tile lands on the SSO error page.

* **Okta (SAML app):** Okta's own tile for a SAML app sends a response Sazabi didn't ask for. On the app's **General** tab, check **Do not display application icon to users**. Then add a **Bookmark App** whose **URL** is the Initiate login URL, and assign it to the same people and groups.
* **Okta (OIDC app):** on the app's **General** tab, edit **General Settings**. Set **Login initiated by** to **Either Okta or App**, check **Display application icon to users**, set **Login flow** to **Redirect to app to initiate login (OIDC Compliant)**, and paste the Initiate login URL into **Initiate login URI**.
* **Microsoft Entra ID (SAML):** set **Sign on URL** under **Single sign-on > Basic SAML Configuration** to the Initiate login URL. My Apps then starts sign-in at Sazabi.
* **Microsoft Entra ID (OIDC):** set the app's home page URL to the Initiate login URL.
* **Google Workspace:** Google's app launcher signs people in to a custom SAML app by sending a response Sazabi didn't ask for, and its **Start URL** field only sets where the app goes after sign-in. Sazabi refuses that response, so there's no working Google tile. People sign in from Sazabi's sign-in page or a bookmark of the Initiate login URL.
* **JumpCloud:** turn on **Show this application in User Portal**. With **Login URL** set to the Initiate login URL, the tile starts sign-in at Sazabi.
* **PingOne (OIDC app):** the application portal shows OIDC apps that have an **Initiate Login URI**. Set it to the Initiate login URL.
* **Other IdPs:** if the IdP's tile can open a URL, set it to the Initiate login URL. If the tile can only send a SAML response, hide it and add a bookmark or link app with the Initiate login URL instead.

## Change or delete the connection

* **Edit connection** changes the connection's fields. Changing an identity provider field (issuer, single sign-on URL, certificates, metadata URL, client ID or client secret) makes the connection untested until a test passes again.
* **Allow sign-in** turns sign-in through the connection off and on.
* **Delete connection** deletes it, as does `sazabi sso disconnect`. It ends the sessions and MCP access of everyone who signed in through it; their accounts and memberships stay.

To rotate a SAML signing certificate without a metadata URL, see [Troubleshooting SSO](https://docs.sazabi.com/guides/administer/single-sign-on/troubleshooting.md#certificate-errors). While a domain requires SSO, the connection can't be deleted and **Allow sign-in** can't be turned off.

## Verify the connection

**Step 1**

### Start the test

On [**Settings > Single sign-on**](https://app.sazabi.com/settings/single-sign-on), choose **Test connection**, or run `sazabi sso connection test`. If your browser is signed in to your IdP's admin console, such as Okta's, run the test from a private window.

**Step 2**

### Sign in at your identity provider

Sign in at your IdP with an account assigned to the Sazabi application.

The page reports a successful sign-in, and the connection shows **Tested**. Until a test passes, it shows **Untested**. If the test fails, see [Troubleshooting SSO](https://docs.sazabi.com/guides/administer/single-sign-on/troubleshooting.md).

## Further reading

> [card] [SSO enforcement](https://docs.sazabi.com/guides/administer/single-sign-on/enforcement.md)
>
> Require SSO for your domains once the test passes.

> [card] [Troubleshooting SSO](https://docs.sazabi.com/guides/administer/single-sign-on/troubleshooting.md)
>
> Certificate, audience, issuer and sign-in failures.


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