> For the complete documentation index, see [llms.txt](https://help.distro.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.distro.so/settings/workspace-settings/saml-sso.md).

# SAML SSO

Workspace admins can connect an identity provider so members sign in through SAML.

<figure><img src="https://2442454418-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQA3GQNrIYVrPQ90NBwRa%2Fuploads%2FXLYOKTDL6m6gzNcGLLlJ%2FCleanShot%202026-09-10%20at%2021.19.21%402x.png?alt=media&amp;token=e2b1f6e4-eaff-424a-bd2f-5fbf4eac58f6" alt=""><figcaption></figcaption></figure>

## Configure the connection

1. Open **Settings → SAML SSO → Edit SAML SSO settings**.
2. Copy the **Assertion Consumer Service URL** and **Audience URI** shown by Distro into your identity provider's application settings.
3. Enter your **SSO domain**, **IdP entity ID**, **Single sign-on URL**, and **IdP certificate** in Distro.
4. Click **Save**.
5. Test SAML sign-in with a provisioned member before requiring it for the workspace.

Use the domain your members sign in with. Existing members can find their enabled SAML provider through Distro. For new users who start without an invitation, discovery and automatic provisioning also require the domain to be verified for your workspace. Entering an SSO domain alone does not establish that verification. Contact Distro if new users cannot find the workspace after setup. Invited users should follow their invitation.

Start sign-in from Distro and continue to your identity provider. Starting from an identity-provider application tile without a Distro sign-in request is not supported.

Distro supplies **RelayState** with each sign-in request. Your identity provider must return that value unchanged. The fixed **Relay State** value displayed in the setup dialog cannot replace it.

## Require SAML sign-in

Turn on **Only allow SAML login** in the **Enforce SAML SSO** section, then save that section. Members must use the identity provider. Google sign-in and password recovery do not bypass enforcement. The workspace owner retains emergency access unless another workspace they belong to requires SAML for them.

For an existing user, enforcement follows workspace membership. If they belong to several enforced workspaces, they can sign in through one of those workspaces' SAML providers.

## Create users at first sign-in

**Create new users from SAML** controls **Automatic account creation**. When enabled, new users from a verified domain can be created after successful SAML authentication. When disabled, invite new users before they sign in. Save this section separately from the enforcement setting.

If sign-in cannot find the workspace, check the email domain and **SSO domain**. If authentication fails after reaching the identity provider, review its application configuration and the saved IdP values.

If you already use Distro, you must be a workspace member or join through its invitation flow before using that workspace's SAML sign-in. Sign in to your existing account before accepting an invitation. A matching email domain or an invitation you have not accepted does not add membership by itself.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.distro.so/settings/workspace-settings/saml-sso.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
