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

# Single Sign-On (SSO)

> Secure who can access your workspace

Single Sign-On (SSO) allows users to access Speckle using your organization's existing identity provider. Speckle supports any OIDC identity provider.

## Enable SSO

Admins can enable SSO under Settings -> Security.
Workspace members can see this section, but only workspace admins can change these controls.
In Settings -> Security, this control appears in the **Single Sign-On** section.

<Note>SSO is available on the Enterprise plan.</Note>

<Info>
  Need help setting up SSO? We're happy to jump on a call to walk you through the process. [Contact
  us](mailto:support@speckle.systems) to schedule a meeting.
</Info>

<Steps>
  <Step title="Create an OpenID Connect application">
    Set up a new **web application** using the OpenID Connect protocol in your identity provider's panel. This will generate the necessary settings for Speckle.

    When configuring the application, use this **Redirect URL** (callback):

    ```
      https://app.speckle.systems/api/v1/workspaces/{workspace-short-id}/sso/oidc/callback
    ```

    The value of `workspace-short-id` should be your workspace's unique short id.

    Set the application grant type to "authorization\_code" and configure these scopes:

    | Scope   | Resultant claims                |
    | ------- | ------------------------------- |
    | openid  | -                               |
    | profile | name, given\_name, family\_name |
    | email   | email                           |

    <Warning>
      You may need to explicitly configure your identity provider to provide user emails with the `email` claim. Some providers, like Azure AD, will omit or obscure this information by default.
    </Warning>
  </Step>

  <Step title="Configure SSO in Speckle">
    Fill in the SSO configuration form with details from your identity provider:

    * **Provider**: The label displayed on the login button in Speckle
    * **Client ID**: From your identity provider application
    * **Client secret**: Strictly confidential string of characters generated by your Identity Provider alongside the Client ID.
    * **Discovery URL**: The full URL where your Identity Provider's configuration metadata is hosted, given by your identity provider application. This almost always ends in `/.well-known/openid-configuration`. Example: `https://your-company.idp.com/.well-known/openid-configuration`
  </Step>

  <Step title="Enable SSO">
    Click **Add** to save your SSO configuration. Once SSO is enabled, all workspace members will be required to authenticate with SSO credentials the next time they access the workspace.
  </Step>
</Steps>

### When SSO is enabled

1. Users will see your organization's SSO option when they are invited to the workspace.
2. Existing workspace members will be prompted to authenticate with SSO the next time they access the workspace.
3. Users with the Guest role can still access the workspace without SSO, since this role is designed for external collaborators.

<Warning>
  SSO provides authentication but not automatic user provisioning. Users removed from your identity
  provider will still be in your list of members in Speckle until a Admin in Speckle has removed
  them.
</Warning>

<Info>
  If your organization uses SSO, you don't need to enable [domain
  protection](/workspaces/domain-protection) as SSO provides equivalent security controls.
</Info>

### Configure backchannel logout

Your Identity Provider (IdP) can automatically notify Speckle when a specific user session terminates. Upon receiving this notification, Speckle immediately logs the user out of the associated workspace.

This feature helps enforce strict security policies by ensuring immediate access revocation in scenarios where a user leaves your organization or a session is compromised.

To enable this feature, configure the backchannel logout URL within your IdP settings using the following endpoint:

```
  https://app.speckle.systems/api/v1/workspaces/{workspace-short-id}/sso/oidc/backchannel-logout
```

**Note:** Replace `{workspace-short-id}` with the unique short identifier for your specific Speckle workspace.

### Update SSO provider configuration

If you need to update the provider details for some reason ie.: the client secrets is about to expire, currently the graphql api needs to be used.

1. Open the api explorer at [https://app.speckle.systems/graphql](https://app.speckle.systems/graphql)
2. Query the existing SSO provider details with the query below, it will return the details of the existing provider.

```gql theme={null}
query ($slug: String!) {
  workspaceBySlug(slug: $slug) {
    id
    sso {
      provider {
        id
        clientId
        issuerUrl
        name
      }
    }
  }
}
```

3. update the provider details with the mutation and the input structure detailed below.

<Warning>
  Incorrectly updating the provider details may make your workspace inaccessible for your users.
  Make sure to double check the new values.
</Warning>

Mutation

```gql theme={null}
mutation ($input: WorkspaceSsoProviderUpdateInput!) {
  workspaceMutations {
    updateSsoProvider(input: $input)
  }
}
```

Input

```json theme={null}
{
  "input": {
    "clientId": "",
    "clientSecret": "",
    "issuerUrl": "",
    "providerId": "",
    "providerName": "",
    "workspaceId": ""
  }
}
```

4. the sso provider details should be updated if the mutation was successful.

## FAQ

<AccordionGroup>
  <Accordion title="With SSO enabled, do users still need an invite?">
    Existing workspace members can sign in with SSO without a new invite. First-time users still
    need a workspace invite so they can be granted a workspace role and access.
  </Accordion>

  <Accordion title="Why can a user sign in with SSO but still not access the workspace?">
    SSO authenticates identity, but workspace access still depends on workspace membership and role
    assignment. If a user has no workspace role, they cannot access workspace content even after
    successful SSO authentication.
  </Accordion>

  <Accordion title="Are Guests required to authenticate with SSO?">
    Not always. In current behavior, Guests can still access invited projects without being forced
    through the same SSO session requirement as workspace Members.
  </Accordion>

  <Accordion title="For how long will users be logged in with SSO?">
    The maximum duration of a user SSO session is 7 days in Speckle. After this, users will be
    required to re-authenticate through your identity provider. However, the actual session duration
    may be shorter if your provider terminates sessions sooner or if users log out manually
    (backchannel loggout). For custom session durations, you can contact us.
  </Accordion>

  <Accordion title="Can we get Multi-Factor Authentication (MFA)?">
    Multi-Factor Authentication (MFA) is an authentication method that requires two or more
    verification factors, such as something you know (password), something you have (authenticator
    app or hardware token), or something you are (biometric). MFA is managed through your SSO
    identity provider. Speckle offers user account verification at registration, but not a
    standalone MFA flow outside your identity provider.
  </Accordion>
</AccordionGroup>