> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/organization-administration/sso-setup.md). # SSO setup Single sign-on lets members sign in through your organization’s identity provider. Configure the SAML application and StackAI settings, then verify an assigned user’s access. {% embed url="" %} ## Before you start Involve the identity administrator before enabling SSO. The rollout checklist below explains what the team manager supplies, what IT configures, and how to test access without closing the independent administrator session. You need administrator access in StackAI and permission to configure a SAML application in your identity provider. ## Prepare the rollout with your identity administrator This setup requires access to the organization's SSO settings and an identity administrator who can configure and assign a SAML application. SSO and provisioning are Enterprise features. If the settings are unavailable, ask the organization owner or administrator to check your plan and access before proceeding. The team manager should provide the organization name, deployment URL, intended email domains, pilot users, and the least-privileged starting role. IT should configure the SAML application, supply its metadata URL, assign the pilot users, and participate in the first sign-in check. Agree who owns recovery before enabling the configuration. | StackAI value | What IT does with it | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Metadata URL / Metadata Download URL under StackAI SAML Variables | Imports StackAI's service-provider metadata into the identity-provider application. Use the identifier contained in that metadata rather than inventing an audience value. | | Assertion Consumer Service URL | Maps to the provider's assertion-consumer, reply, or SAML sign-on destination field. Copy it exactly. | | Single Logout Service URL | Uses it for the provider's SAML logout field when configuring that integration. | | Metadata URL from the identity provider | Returns this application's identity-provider metadata URL to the StackAI administrator for the SSO Provider form. This is different from StackAI's own metadata URL. | Field labels differ between identity providers. Have IT confirm the mapping against the provider's SAML application configuration before enabling it. ## Understand Role, Domains, and provisioning **Role** is the default for new organization memberships created through SSO on first sign-in when SCIM is not managing provisioning. It does not replace every existing member's role. Choose the role after reviewing [Roles and permissions](/guides-and-quickstarts/organization-administration/roles-and-permissions.md). **Domains** determine which email domains are routed through SSO; they do not replace assigning users to the application in the identity provider. With SCIM enabled, SSO authenticates the user but does not create an unprovisioned organization membership. IT must provision an active membership first. An inactive membership remains denied; another successful identity-provider login does not reactivate it. Use [SCIM provisioning](/guides-and-quickstarts/organization-administration/scim-provisioning.md) to configure that lifecycle. Metadata URL, Role, and Domains are read-only in the SSO form after enablement. Double-check all three before confirming. ## Configure the identity provider Open SSO and Provisioning → SSO Setup and review StackAI SAML Variables. ![StackAI SAML Variables](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/8vqlLoTWkFD70IVeqUuR/assets/g093-g093-01-variables.png) Use the metadata and service URLs generated for your deployment. Configure the SAML application in your identity provider with the StackAI values. ![Identity-provider SAML application configuration](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/oGsV4ddPNe3h6Coz1m9G/assets/g093-g093-02-idp.png) Check the sign-on URL and audience fields for an exact match. Assign the intended users or groups to the identity-provider application. ![Identity-provider user and group assignments](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/aovKJcmR5qui1kg0LMQs/assets/g093-g093-03-assignment.png) Obtain that application's metadata URL for the StackAI configuration. ## Enable SSO in StackAI Enter the IdP Metadata URL, default Role, and authorized Domains in StackAI. ![StackAI IdP metadata, default role, and domains](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/JNpIVx2g4mH8459gce8b/assets/g093-g093-04-provider.png) Review the complete configuration before enabling SSO. Complete enablement and confirm the SSO Enabled status. ![SSO Enabled status](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/Xp8x0vfQXqeTc7zGg0rN/assets/g093-g093-05-enabled.png) Retain an independent administrator session while verifying the sign-in configuration. ## Verify sign-in Start the organization's SSO flow in a separate session with an assigned user. ![Assigned-user SSO sign-in](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/JLdipDZXAuhvaghsiJni/assets/g093-g093-06-login.png) Complete authentication through the configured identity provider. After sign-in, confirm the destination organization and the member's role. ![Destination organization and member role](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/J6UJU8dfRoOr0CJnPZ9B/assets/g093-g093-07-member.png) Successful identity-provider authentication alone does not confirm the correct workspace assignment. ## If the pilot sign-in fails Keep the independent administrator session open and pause the rollout. Ask IT to check the application's user assignment, exact ACS destination and identifier from the metadata, and the metadata URL supplied to StackAI. If authentication succeeds but the user cannot enter the organization, inspect the member's active status and SCIM provisioning result separately. If the saved StackAI SSO values are wrong, contact [Support and deployment diagnostics](/guides-and-quickstarts/personal-settings-and-support/support-and-deployment-diagnostics.md) from the retained administrator session; the enabled form does not provide an in-place edit for these fields. Include the deployment URL, organization, affected email domain, error text, time and time zone, and which stage failed. Do not send passwords, session tokens, or a full SAML assertion. If all administrators are locked out, have your organization's established support contact raise the same request externally. ## Important behavior Use the exact SAML URLs and identifiers supplied by your deployment. Incorrect values can prevent sign-in. Keep an administrator session open while you verify the new configuration. --- # 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://docs.stackai.com/guides-and-quickstarts/organization-administration/sso-setup.md?ask=&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.