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.

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

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

1. Open SSO settings

   In CRAFT, navigate to Settings and select Single Sign-On from the sidebar.

2. Select your protocol

   Choose OIDC or SAML depending on what your identity provider supports. If both are available, OIDC is recommended for simplicity.

3. 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.

4. 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
   • Google Workspace — OIDC setup
   • Okta — OIDC app setup

   For the engineer-side configuration details and Helm chart settings, see SSO Integration Guide.

5. 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.

   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.

6. 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.

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

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.

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.

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.