> ## 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>