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

# TestDino SSO and SCIM Provisioning

> Set up per-organization SSO with OIDC or SAML 2.0, and provision users automatically with SCIM, from the TestDino settings UI.

<Callout icon="book-open" color="#3B82F6">
  **What you'll learn**

  * How to connect your IdP with OIDC or SAML 2.0
  * How the slug builds your sign-in URLs
  * How to enforce SSO and set a default role for new users
  * How to provision users automatically with SCIM
</Callout>

Single sign-on connects your organization to your company identity provider (Okta, Azure AD, Google Workspace, or any OIDC / SAML 2.0 IdP), so your team signs in with their existing credentials. You configure it per organization under **Settings → Single Sign-On**. No engineering work is needed.

## Quick Reference

| Step | What you do                          | Where    |
| :--- | :----------------------------------- | :------- |
| 1    | Open the SSO settings                | TestDino |
| 2    | Pick a protocol and organization key | TestDino |
| 3    | Configure your identity provider     | Your IdP |
| 4    | Set enforcement and a default role   | TestDino |
| 5    | Save and test sign-in                | Both     |
| 6    | Set up SCIM provisioning (optional)  | Both     |

## 2 hosts to keep straight

TestDino serves its dashboard and its API on different hostnames, and the split matters for SSO:

| You use this for                                 | Host                       |
| :----------------------------------------------- | :------------------------- |
| Signing in and using the TestDino dashboard      | `https://app.testdino.com` |
| Every URL you paste into your IdP (SSO and SCIM) | `https://api.testdino.com` |

<Warning>
  The most common setup failure is registering an `app.testdino.com` URL in your IdP. Every IdP-facing URL uses `api.testdino.com`. Use them exactly as written, with no trailing slash and no typos.
</Warning>

On a dedicated or custom domain, replace `api.testdino.com` with the API host your TestDino account team gave you.

## Before you start

* An **Owner or Admin** account. Only Owners and Admins see the Single Sign-On tab.
* **SSO enabled on your plan.** The tab appears only for SSO-entitled organizations, so contact [support@testdino.com](mailto:support@testdino.com) if it is missing.
* **IdP admin access** to create an app integration.
* An **organization key** you pick in TestDino, such as `acme`.

## How it fits together

SSO coordinates 2 systems that must agree on the same URLs:

1. **Your IdP**: the app and who may use it.
2. **TestDino** (Settings → Single Sign-On): the IdP address, signing material, and policy.

The link is your **organization key** (lowercase letters, digits, and hyphens, such as `acme`). Pick it first and use the exact same value on both sides. TestDino builds every URL from it.

```text theme={null}
Sign-in (start):     https://api.testdino.com/api/auth/sso/<your-org-key>/login
OIDC callback:       https://api.testdino.com/api/auth/sso/<your-org-key>/callback
SAML callback (ACS): https://api.testdino.com/api/auth/sso/<your-org-key>/saml/callback
SAML SP metadata:    https://api.testdino.com/api/auth/sso/<your-org-key>/saml/metadata
SCIM base URL:       https://api.testdino.com/scim/v2
```

<Warning>
  The callback or ACS URL you register in your IdP must match the organization key saved in TestDino, with no trailing slash and no typos. A mismatch is the most common reason sign-in fails. Pick the key first, then use it on both sides.
</Warning>

## Configure SSO

<Steps>
  <Step title="Open the SSO settings">
    Go to **Settings → Single Sign-On**. You see 2 cards:

    * **Single sign-on** holds the protocol and IdP config.
    * **SCIM provisioning** holds the token. It stays disabled until you save an SSO config.

    No tab means you are not an admin, or the organization is not SSO-entitled.
  </Step>

  <Step title="Pick a protocol and organization key">
    | Protocol     | Use it when                                                |
    | :----------- | :--------------------------------------------------------- |
    | **OIDC**     | Default. Modern OAuth-based sign-in. Works with most IdPs. |
    | **SAML 2.0** | Only if your IT policy requires XML-based sign-in.         |

    Enter your **organization key** before you set up the IdP. It becomes part of every sign-in URL, so changing it later breaks existing links.
  </Step>

  <Step title="Configure your identity provider">
    Create an app in your IdP, copy its values into TestDino, then save. The fields below use Okta as the example. Azure AD and Google Workspace use the same fields under different menu names.

    <Tabs>
      <Tab title="OIDC">
        **In your IdP**, create an OIDC web app with the Authorization Code grant type, set the sign-in redirect URI, and assign your users.

        Okta path: **Applications → Create App Integration → OIDC / Web Application**, set the redirect URI, then open **Assignments** and save.

        Set the redirect URI to:

        ```text theme={null}
        https://api.testdino.com/api/auth/sso/<your-org-key>/callback
        ```

        | Value to enter in TestDino | Where to find it in Okta                                      |
        | :------------------------- | :------------------------------------------------------------ |
        | **Issuer**                 | Security → API → Authorization Servers → default → Issuer URI |
        | **Client ID**              | App → General → Client Credentials                            |
        | **Client secret**          | Same section → Show → copy (shown once)                       |

        **In TestDino**, paste the Issuer, Client ID, and Client secret. The secret is encrypted at rest and never shown again.

        <Callout icon="circle-info" color="#3B82F6">
          If Okta returns "Policy evaluation failed", add an access policy: **Security → API → Authorization Servers → default → Access Policies**, then add a policy and rule that allows the Authorization Code grant for your assigned users.
        </Callout>
      </Tab>

      <Tab title="SAML 2.0">
        A SAML app is separate from an OIDC app, so create a new one.

        **In your IdP**, create a SAML app with these fields:

        | Field                       | Value                                                                |
        | :-------------------------- | :------------------------------------------------------------------- |
        | Single sign-on URL (ACS)    | `https://api.testdino.com/api/auth/sso/<your-org-key>/saml/callback` |
        | Audience URI (SP Entity ID) | `testdino-<your-org-key>`                                            |
        | Name ID format              | EmailAddress                                                         |
        | Application username        | Email                                                                |

        Add 3 attribute statements: `email = user.email`, `firstName = user.firstName`, `lastName = user.lastName`. Then assign your users.

        Okta path: open the app's **Sign On** tab, click **View SAML setup instructions**, and copy the **Identity Provider Single Sign-On URL** and the **X.509 Certificate** (PEM).

        **In TestDino**, enter the IdP Single Sign-On URL, the SP Entity ID (the same Audience URI), and the full PEM certificate, including the `BEGIN` and `END` lines. Extra whitespace is fine.

        <Tip>
          Okta can also consume `https://api.testdino.com/api/auth/sso/<your-org-key>/saml/metadata` as a metadata URL, which pre-fills the ACS URL and Entity ID.
        </Tip>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set enforcement and a default role">
    * **Require SSO for these domains** blocks password sign-in for any email on those domains and sends those users to your IdP. At least one domain is required when this is on.
    * **Default role** is the role assigned on a user's first SSO sign-in. Member is typical, and Admins can change it later.
  </Step>
</Steps>

## Save and test

Click **Save changes**. The status badge shows **Configured · OIDC** or **Configured · SAML**.

Test in an incognito window:

<Steps>
  <Step title="Start the sign-in">
    Open [`https://app.testdino.com/auth/sso`](https://app.testdino.com/auth/sso), enter a work email on an SSO-enabled domain, and click **Continue**. The direct link `https://api.testdino.com/api/auth/sso/<your-org-key>/login` also works and skips email discovery.
  </Step>

  <Step title="Sign in at your IdP">
    Complete the login with your IdP credentials.
  </Step>

  <Step title="Confirm the result">
    You return signed in, and the user appears in your organization.
  </Step>
</Steps>

**Just-in-time (JIT) provisioning:** The first SSO sign-in creates the account, assigns the default role, and adds it to the matching-domain organization. Later sign-ins reuse the same account.

## How your team signs in

Once SSO is active, your team has 3 ways to sign in:

* **Email discovery** at [`https://app.testdino.com/auth/sso`](https://app.testdino.com/auth/sso). The user enters their work email under **Continue with SSO**, and TestDino routes them to the matching organization's IdP. The **Continue with SSO** button on the main login page (`app.testdino.com/auth/login`) opens this same page.
* **IdP app tile** in your identity provider (IdP-initiated).
* **Direct link** to `https://api.testdino.com/api/auth/sso/<your-org-key>/login`, which skips email discovery and starts your org's IdP login.

## Set up SCIM provisioning

SCIM provisions TestDino users from your IdP automatically: create, update, and deactivate. Save an SSO config first, then generate a token in the SCIM card. The token is shown once.

Configure your IdP's provisioning with these values:

| Field                   | Value                              |
| :---------------------- | :--------------------------------- |
| SCIM connector base URL | `https://api.testdino.com/scim/v2` |
| Unique identifier       | userName                           |
| Auth mode               | HTTP Header (Bearer token)         |
| Bearer token            | the copied token                   |

In Okta, a custom app does not show a SCIM toggle. Add the prebuilt **SCIM 2.0 Test App (Header Auth)** from the catalog, open **Provisioning → Configure API Integration**, enable it, enter the base URL and token, test the credentials, then enable Create, Update, and Deactivate under "To App" and assign users.

### What each SCIM action does

Every change you make in your IdP maps to one action in TestDino. The table below shows what each one does.

| IdP action            | Effect in TestDino                                                       |
| :-------------------- | :----------------------------------------------------------------------- |
| Assign                | Creates the user and adds org membership. Repeat assigns are idempotent. |
| Update                | Updates the user's name.                                                 |
| Deactivate / unassign | Disables the user but keeps org membership, so reactivation works.       |
| Reactivate            | Re-enables the user.                                                     |
| Delete                | Removes the user from the organization.                                  |

## Day-2 operations

Once SSO is live, these are the routine tasks for keeping it running and rotating credentials.

| Task                   | How                                                                                                                            |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| Rotate the SCIM token  | SCIM card → **Rotate**. Update your IdP connector right away, since the old token stops working at once.                       |
| Rotate the OIDC secret | Create a new secret in your IdP, paste it into Client secret, and save. Leaving it blank keeps the current secret.             |
| Pause SSO              | Clear enforcement to allow password sign-in again.                                                                             |
| Switch protocol        | Saving the other protocol replaces the sign-in config but keeps your SCIM token. Update the IdP callback or ACS path to match. |

## Troubleshooting

Most SSO failures trace to a mismatch between your IdP and the values saved in TestDino. Match your error message to the row below.

| Symptom                                              | Cause                                            | Fix                                                                                                                                                 |
| :--------------------------------------------------- | :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| IdP: "redirect\_uri must be a Login redirect URI"    | Callback URL does not match the organization key | Set the IdP redirect URI to exactly `…/sso/<your-org-key>/callback` (or `…/saml/callback`) on `api.testdino.com`, not `app`, with no trailing slash |
| Okta: "Policy evaluation failed"                     | No access policy, or the user is not assigned    | Add an access policy and rule on the default auth server, then assign the user                                                                      |
| SAML: "idpCert is not in PEM format"                 | Certificate not pasted as full PEM               | Paste the whole certificate, including the `BEGIN` and `END` lines                                                                                  |
| SCIM test fails: "Missing or malformed bearer token" | Wrong or blank token                             | Re-paste the exact token, set auth mode to HTTP Header (Bearer), and confirm the base URL is `https://api.testdino.com/scim/v2`                     |
| No Single Sign-On tab                                | Not an admin, or the org is not SSO-entitled     | Get admin access, or contact support                                                                                                                |
| Password login refused with an SSO message           | Enforcement is on for that domain                | Sign in with SSO, or remove the domain from enforcement                                                                                             |
| Cannot sign in after deactivation                    | Expected. Deactivated accounts are blocked.      | Reactivate through your IdP (SCIM) or in TestDino                                                                                                   |
| "User limit reached" on sign-in or SCIM              | The plan seat limit is full                      | Free a seat or upgrade the plan                                                                                                                     |

<Callout icon="circle-info" color="#3B82F6">
  Seat limits apply to new users only. A net-new SSO sign-in or SCIM create is blocked when the org is at its limit, but existing members signing in again are never blocked.
</Callout>

## Related

<CardGroup cols={2}>
  <Card title="Users, Roles & Permissions" icon="users" href="/platform/organizations/users-roles">
    Understand the roles a new SSO user can receive.
  </Card>

  <Card title="Organization Settings" icon="gear" href="/platform/organizations/settings">
    Manage your organization profile and ownership.
  </Card>

  <Card title="Security & Compliance" icon="shield-check" href="/data-privacy/security-compliance">
    Review how TestDino handles credentials and customer data.
  </Card>

  <Card title="Generate API Keys" icon="key" href="/guides/generate-api-keys">
    Create keys for CLI uploads and integrations.
  </Card>
</CardGroup>