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

# Single Sign-On (SAML & OIDC)

> Connect your own identity provider to Share Of Model, test it, activate it and require it for your email domains.

Single sign-on lets your members sign in to Share Of Model with your own identity provider (IdP) instead of a Share Of Model password. You configure it yourself, from the organisation settings, without opening a ticket.

Share Of Model acts as the **service provider (SP)**. Your IdP authenticates the user and asserts their identity; Share Of Model resolves that identity to a member of your organisation and issues its own session.

<CardGroup cols={2}>
  <Card title="SAML 2.0" icon="shield-halved">
    Okta, Microsoft Entra ID, Google Workspace, OneLogin and most enterprise identity providers.
  </Card>

  <Card title="OpenID Connect" icon="key">
    Modern OAuth 2.0 based sign-in. Use it when your identity provider does not offer SAML.
  </Card>
</CardGroup>

## Prerequisites

* You are an **Organization Owner** — see [User Roles & Workspaces](/platform/getting-started/user-roles-and-workspaces-management).
* Single sign-on is enabled for your organisation. It is rolled out per organisation; contact your account manager if you do not see the tab.
* You can administer your identity provider (create an application, read its metadata).
* You own the email domains your members sign in with. Personal email domains (Gmail, Outlook, and similar) cannot be used.

<Note>
  One identity provider per organisation. Domains are verified by the Share Of Model team before single sign-on can be activated — see [Email domains](#email-domains).
</Note>

## Where to find it

Open **Settings** from your profile icon, select your organisation, then open the **Single sign-on** tab. It has two sections:

| Section               | Purpose                                                                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Sign-in**           | Identity provider configuration, service provider values, domains, connection test, activation, provisioning and group mappings. |
| **SCIM provisioning** | SCIM base URL and bearer tokens — see [SCIM Provisioning](/platform/getting-started/scim-provisioning).                          |

## Configuration statuses

Your configuration moves through four statuses, shown at the top of the Sign-in section.

| Status       | Meaning                                                          |
| ------------ | ---------------------------------------------------------------- |
| **Draft**    | Saved but never tested successfully. No one can sign in with it. |
| **Tested**   | A test sign-in succeeded. You can activate it.                   |
| **Active**   | Members can sign in through your identity provider.              |
| **Disabled** | Turned off. Members sign back in with a password or Google.      |

<Warning>
  Any change to an identity provider field sends the configuration back to **Draft**. Re-run the connection test and activate it again.
</Warning>

## Set up single sign-on

The **Set up single sign-on** wizard walks through six steps. You can leave and resume at any point — nothing is applied to your members until you reach Activate.

<Steps>
  <Step title="Choose a protocol">
    Pick **SAML 2.0** or **OpenID Connect**. Use SAML unless your identity provider does not offer it.
  </Step>

  <Step title="Configure the identity provider">
    <Tabs>
      <Tab title="SAML 2.0">
        Import the SAML metadata published by your identity provider, either by **Metadata URL** or by pasting the **XML**.

        Share Of Model parses the document and shows the detected settings before saving anything: entity ID, single sign-on URL, and the fingerprint and expiry of each signing certificate. It also detects the provider (Okta, Entra ID, Google) and pre-fills the matching attribute mapping.

        Open **Advanced** to adjust the attribute mapping — see [Attribute mapping](#attribute-mapping).
      </Tab>

      <Tab title="OpenID Connect">
        Enter the **issuer**, **client ID** and **client secret** of the application you registered in your identity provider, plus the **scopes** (`openid email profile` by default).

        The issuer is used to discover the provider endpoints through `/.well-known/openid-configuration`.

        <Note>
          The client secret is stored encrypted and never returned by the API or shown again. Leave the field empty when editing to keep the current secret.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Copy the service provider values">
    This step exposes the values your identity provider needs. Each field has a copy button, and the signing certificate can be downloaded.

    | Value                                | Pattern                                              |
    | ------------------------------------ | ---------------------------------------------------- |
    | Entity ID (also the metadata URL)    | `https://api.shareofmodel.ai/v1/sso/{slug}/metadata` |
    | Assertion consumer service (ACS) URL | `https://api.shareofmodel.ai/v1/sso/{slug}/acs`      |
    | Redirect URI (OIDC)                  | `https://api.shareofmodel.ai/v1/sso/{slug}/callback` |
    | Initiate login URI (OIDC)            | `https://api.shareofmodel.ai/v1/sso/{slug}/login`    |
    | Signing certificate                  | Downloadable X.509 certificate                       |

    The `{slug}` is derived from your organisation name and never changes. Always copy the exact values from the interface rather than typing them.
  </Step>

  <Step title="Add your email domains">
    Add every domain your members sign in with, for example `acme.com`. Each domain shows as **Pending** until the Share Of Model team verifies it, then as **Verified**.

    See [Email domains](#email-domains) for what verification gates.
  </Step>

  <Step title="Test the connection">
    Click **Test connection**. A secondary window opens on your identity provider and you authenticate as yourself.

    * **Success** — the window closes and the step lists every attribute received: email, first name, last name and groups. Check that the email matches the member's Share Of Model address.
    * **Failure** — the step shows a sanitised error. Fix the identity provider settings and test again.

    A test never issues a session and never creates a member. It is safe to run as often as needed, and it works before your domains are verified.
  </Step>

  <Step title="Activate">
    Review the summary — protocol, identity provider, domains — then click **Activate single sign-on**. Members can now sign in through your identity provider, while passwords and Google sign-in keep working.

    To make it the only way in, turn on [Require single sign-on](#require-single-sign-on).
  </Step>
</Steps>

## Identity provider guides

The same guides are available in the interface, in the Service provider step.

<Tabs>
  <Tab title="Okta — SAML">
    <Steps>
      <Step title="Create a SAML app integration">
        In the Okta admin console open **Applications**, choose **Create App Integration** and select **SAML 2.0**.
      </Step>

      <Step title="Paste the service provider values">
        Use the ACS URL as **Single sign-on URL** and the entity ID as **Audience URI**. Set the **Name ID format** to `EmailAddress`.
      </Step>

      <Step title="Add attribute statements">
        Map `email`, `firstName` and `lastName`. Add a group attribute statement if you want to use group mappings.
      </Step>

      <Step title="Import the Okta metadata">
        From the **Sign On** tab copy the metadata URL and import it in the identity provider step.
      </Step>

      <Step title="Enable the Share Of Model tile">
        Assign the application to your users, and set the **Default RelayState** to the Share Of Model path you want to open after sign-in.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Entra ID — SAML">
    <Steps>
      <Step title="Create an enterprise application">
        In Microsoft Entra ID open **Enterprise applications**, choose **New application** and create your own non-gallery application.
      </Step>

      <Step title="Configure single sign-on with SAML">
        Set the **Identifier** to the entity ID and the **Reply URL** to the ACS URL shown in the service provider step.
      </Step>

      <Step title="Review the claims">
        Keep `emailaddress`, `givenname` and `surname`. Add a groups claim if you want to use group mappings.
      </Step>

      <Step title="Import the federation metadata">
        Copy the **App Federation Metadata Url** and import it in the identity provider step.
      </Step>

      <Step title="Allow IdP-initiated sign-in">
        Assign users to the application so the Share Of Model tile appears in **My Apps**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Okta — OIDC">
    <Steps>
      <Step title="Create an OIDC web application">
        In the Okta admin console open **Applications**, choose **Create App Integration** and select **OIDC** with the **Web Application** type.
      </Step>

      <Step title="Register the redirect URIs">
        Paste the callback URL as **Sign-in redirect URI** and the login URL as **Initiate login URI**.
      </Step>

      <Step title="Copy the issuer and client credentials">
        Enter the Okta issuer, client ID and client secret in the identity provider step.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Entra ID — OIDC">
    <Steps>
      <Step title="Register an application">
        In Microsoft Entra ID open **App registrations** and create a web application.
      </Step>

      <Step title="Register the redirect URIs">
        Paste the callback URL as **Redirect URI** and the login URL as the **Front-channel login URL**.
      </Step>

      <Step title="Create a client secret">
        Under **Certificates and secrets** create a secret, then enter the issuer, application ID and secret in the identity provider step.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Attribute mapping

Share Of Model needs an email for every sign-in, and optionally a first name, last name and group list. Defaults are pre-filled from the detected provider and can be overridden under **Advanced**.

| Field      | SAML default | Entra ID (SAML)                                                      | OpenID Connect |
| ---------- | ------------ | -------------------------------------------------------------------- | -------------- |
| Email      | `email`      | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `email`        |
| First name | `firstName`  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    | `given_name`   |
| Last name  | `lastName`   | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      | `family_name`  |
| Groups     | `groups`     | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`     | `groups`       |

<Warning>
  The email is the only identifier Share Of Model trusts. For OpenID Connect the `email` claim is required and an `email_verified` claim set to false fails the sign-in — `sub`, `upn` and `preferred_username` are never used as fallbacks.
</Warning>

## Email domains

A domain can belong to only one single sign-on configuration across the whole platform, and personal email domains are rejected.

Domain verification is performed by the Share Of Model team. It gates two things:

* **Activation** of the configuration.
* **Requiring** single sign-on for those domains.

Testing does not require verification, since a test issues no session.

<Warning>
  Changing the domains of an active configuration resets verification, turns **Require single sign-on** off and sends the status back to **Tested**. Have the new domains verified, then activate again.
</Warning>

## Require single sign-on

The **Require single sign-on** switch on the status card forces members of your verified domains through your identity provider. Password and Google sign-in start returning an error that redirects them to your provider.

The switch stays disabled until the configuration is **Active** and the domains are **Verified**.

Two exemptions prevent the requirement from locking out accounts that are not yours:

* users who also belong to another organisation,
* Share Of Model staff.

<Warning>
  If your identity provider becomes unavailable while single sign-on is required, your members cannot sign in. Contact support — the Share Of Model team can disable the requirement for your organisation.
</Warning>

## Provisioning and roles

The **Provisioning** card controls what happens to a user who signs in successfully but is not yet a member.

| Setting                             | Effect                                                                                                                                                         |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Create members on first sign-in** | Just-in-time provisioning. When on, a successful sign-in from a configured domain creates the member. When off, unknown users are refused with `unknown_user`. |
| **Default organization role**       | Role given to members created on first sign-in, or provisioned without a mapped group. Guest, Viewer or Editor — never Owner.                                  |

Just-in-time provisioning still respects your organisation's user quota; sign-in fails with `quota_exceeded` once it is reached.

### Group mappings

Map a group sent by your identity provider to a Share Of Model role. Each mapping targets either the organisation or one workspace.

<Steps>
  <Step title="Send groups from your identity provider">
    Add the group attribute statement (Okta) or groups claim (Entra ID), and make sure the **Groups attribute** in the advanced mapping matches it.
  </Step>

  <Step title="Add a mapping">
    In the Provisioning card click the add button, enter the identity provider group name, choose **Organization** or **Workspace**, pick the workspace if needed, then pick the mapped role.
  </Step>
</Steps>

Groups sent without a mapping are recorded and ignored. A member who no longer matches any organisation-level mapping falls back to the default organisation role — the membership itself is not removed. Removing access is the job of [SCIM deprovisioning](/platform/getting-started/scim-provisioning) or of an Organization Owner.

## The sign-in experience

<Tabs>
  <Tab title="From Share Of Model">
    On the sign-in page, the member clicks **Continue with Email or SSO** and enters their email. If the domain is configured, a **Continue with SSO** button appears; if single sign-on is required, it is the only option offered.

    Members who last signed in with single sign-on land directly on a **Continue with SSO** screen, with **Choose another method** revealing the other options.
  </Tab>

  <Tab title="From your identity provider">
    With SAML, a member can also click the Share Of Model tile in their provider portal. Set the **Default RelayState** to the path you want to open — Share Of Model only honours it as a relative path, never as a full URL.

    If another account is already signed in on that browser, Share Of Model asks for confirmation before switching accounts.

    Identity-provider-initiated sign-in is enabled by default. It has no switch in the interface — contact support to turn it off for your organisation.

    OpenID Connect has no unsolicited response; providers use the **Initiate login URI** instead, which starts a normal sign-in.
  </Tab>
</Tabs>

## Maintenance

<CardGroup cols={2}>
  <Card title="Service provider certificate" icon="certificate">
    Generated by Share Of Model, valid for three years. **Rotate the service provider certificate** in the Danger zone issues a new key pair — upload the new certificate to your identity provider straight away.
  </Card>

  <Card title="Identity provider certificate" icon="rotate">
    Several signing certificates can be configured at once, so you can roll over on your side. Re-import the metadata after any change.
  </Card>
</CardGroup>

### Disable single sign-on

**Disable single sign-on** in the Danger zone sets the status to Disabled and turns off the requirement. Members sign in with a password or Google again. The configuration is kept, so you can activate it later without redoing the setup.

## Troubleshooting

Failed sign-ins come back to the sign-in page with an error code. The same codes appear in the connection test.

| Code                     | Meaning                                                                                                              | What to check                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `invalid_response`       | The response could not be parsed or is missing required elements.                                                    | Assertion encryption must be off; the email attribute must be present and match your mapping. |
| `signature_invalid`      | The signature does not match the configured certificates.                                                            | Re-import the identity provider metadata. SHA-1 signatures are refused.                       |
| `expired`                | The assertion is outside its validity window.                                                                        | Clock skew beyond two minutes, or an assertion lifetime over 12 hours.                        |
| `replayed`               | The assertion was already used.                                                                                      | Usually a page refresh or a replayed response; start a new sign-in.                           |
| `unknown_request`        | The response does not match a pending sign-in.                                                                       | Start the sign-in from Share Of Model rather than replaying an old response.                  |
| `unknown_user`           | The email is not a member and just-in-time provisioning is off.                                                      | Invite the member, or turn on **Create members on first sign-in**.                            |
| `account_disabled`       | The account is deactivated.                                                                                          | Reactivate the member, or re-provision through SCIM.                                          |
| `domain_not_allowed`     | The email domain is not in the configuration.                                                                        | Add the domain and have it verified.                                                          |
| `quota_exceeded`         | The organisation reached its user quota.                                                                             | Free a seat or contact your account manager.                                                  |
| `sso_disabled`           | The configuration is not active.                                                                                     | Activate it in the Sign-in section.                                                           |
| `idp_initiated_disabled` | A response from your provider portal arrived while identity-provider-initiated sign-in is off for your organisation. | Sign in from Share Of Model, or contact support to turn the option back on.                   |

## Limits

* **One identity provider per organisation.**
* **Encrypted SAML assertions are not supported** — leave assertion encryption off in your identity provider.
* **No SAML Single Logout.** Revoke access by deactivating the member, through SCIM or in Members.
* **Domain verification is manual**, performed by the Share Of Model team.
* **Not available for Pencil organisations.**

## What's next

<CardGroup cols={2}>
  <Card title="SCIM Provisioning" icon="user-plus" href="/platform/getting-started/scim-provisioning">
    Sync members and groups automatically from your directory.
  </Card>

  <Card title="User Roles & Workspaces" icon="users-gear" href="/platform/getting-started/user-roles-and-workspaces-management">
    The roles you can map groups to.
  </Card>

  <Card title="Security & Compliance" icon="shield" href="/platform/getting-started/understanding-security-and-compliance-in-share-of-model-platform">
    How identity and access are secured.
  </Card>

  <Card title="API Keys" icon="key" href="/platform/getting-started/creating-and-managing-api-keys">
    Programmatic access, separate from single sign-on.
  </Card>
</CardGroup>