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

# Configure SSO

> Set up single sign-on for your organisation in CRAFT using your existing identity provider.

Single sign-on (SSO) lets your team log in to CRAFT using their existing company credentials. Once SSO is configured, users are redirected to your identity provider when they access CRAFT — they do not need to set or remember a separate CRAFT password.

<Note>
  SSO configuration requires organisation owner permissions. If you do not see the SSO settings described below, contact your organisation owner.
</Note>

## Supported identity providers

CRAFT supports SSO via two standard protocols:

| Protocol                  | Compatible providers                                                                            |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| **OIDC** (OpenID Connect) | Microsoft Entra ID (formerly Azure AD), Google Workspace, Okta, and any OIDC-compliant provider |
| **SAML 2.0**              | Microsoft Entra ID, Okta, Ping Identity, and any SAML 2.0-compliant provider                    |

If your provider is not listed, contact Emergence support — CRAFT can be configured to work with any standards-compliant identity provider.

## Before you begin

You will need the following information from your identity provider administrator:

**For OIDC:**

* Discovery URL (also called the "well-known" endpoint), in the format `https://your-provider.example.com/.well-known/openid-configuration`
* Client ID and client secret (you will create an application in your identity provider and receive these)
* Redirect URL to enter in your identity provider: provided in the CRAFT SSO settings screen

**For SAML:**

* Identity provider metadata URL or XML file
* Redirect URL and SP entity ID to enter in your identity provider: provided in the CRAFT SSO settings screen

## Configure SSO in CRAFT

<Steps>
  <Step title="Open SSO settings">
    In CRAFT, navigate to **Settings** and select **Single Sign-On** from the sidebar.
  </Step>

  <Step title="Select your protocol">
    Choose **OIDC** or **SAML** depending on what your identity provider supports. If both are available, OIDC is recommended for simplicity.
  </Step>

  <Step title="Enter your identity provider details">
    Fill in the connection details for your provider:

    * **For OIDC**: enter the discovery URL, client ID, and client secret.
    * **For SAML**: upload the metadata XML file or enter the metadata URL.

    CRAFT will show you the redirect URL and any other values you need to enter in your identity provider's application configuration.
  </Step>

  <Step title="Configure your identity provider">
    In your identity provider's administration console, create an application or enterprise app for CRAFT and enter the values shown in the CRAFT SSO settings screen (redirect URL, entity ID, etc.).

    Refer to your identity provider's documentation for the specific steps:

    * [Microsoft Entra ID — OIDC app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
    * [Google Workspace — OIDC setup](https://developers.google.com/identity/openid-connect/openid-connect)
    * [Okta — OIDC app setup](https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/)

    For the engineer-side configuration details and Helm chart settings, see [SSO Integration Guide](/guides/sso-integration).
  </Step>

  <Step title="Test the connection">
    After saving your configuration, select **Test Connection**. CRAFT will attempt to authenticate with your identity provider. If the test succeeds, SSO is ready to use.

    <Tip>
      Test with your own account first before asking other users to switch to SSO login. This way you can confirm the configuration is correct without affecting your team.
    </Tip>
  </Step>

  <Step title="Enable SSO for your organisation">
    Once the connection test passes, toggle **SSO Enabled** to on. From this point, users will be redirected to your identity provider when they log in to CRAFT.
  </Step>
</Steps>

## What happens to existing users

When you enable SSO, existing users who log in with a CRAFT password are asked to re-authenticate via your identity provider. Their email address in CRAFT must match the email address in your identity provider — otherwise they will be treated as a new user.

If a user's email address in CRAFT does not match their identity provider email, contact Emergence support to merge the accounts.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Users see 'Access Denied' after logging in">
    The user's email address may not be in the group or application you configured in your identity provider. Check that the user has been assigned to the CRAFT application in your identity provider's admin console.
  </Accordion>

  <Accordion title="SSO redirect loops or blank screen">
    Check that the redirect URL in your identity provider exactly matches the value shown in the CRAFT SSO settings screen. A trailing slash or incorrect protocol (http vs https) will cause redirect failures.
  </Accordion>

  <Accordion title="Test connection fails with 'invalid client'">
    Double-check the client ID and client secret. If you recently rotated the client secret in your identity provider, you will need to update it in the CRAFT SSO settings.
  </Accordion>
</AccordionGroup>