Skip to main content

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 with Keycloak

CRAFT uses Keycloak as its identity provider, supporting Single Sign-On (SSO) via both OIDC and SAML 2.0 protocols. This guide covers configuring SSO for enterprise identity providers including Microsoft Entra ID (Azure AD), Okta, Google Workspace, and PingFederate.

​
Prerequisites

Before you begin, ensure you have:
  • Administrative access to the Keycloak admin console
  • Administrative access to your enterprise identity provider (IdP)
  • The Keycloak realm ID for your organization (realm ID = organization ID)
  • Network connectivity between Keycloak and the IdP (HTTPS required)

​
How SSO Works in CRAFT

Each organization in the platform maps to a Keycloak realm. When SSO is configured:
  1. Users navigate to the platform login page
  2. Keycloak redirects to the enterprise IdP for authentication
  3. The IdP authenticates the user and returns claims to Keycloak
  4. Keycloak issues a JWT containing org_id (from the realm) and group memberships
  5. The platform uses the JWT for authorization via OpenFGA
Per-tenant SSO configuration means each organization can connect to a different identity provider. One organization might use Okta while another uses Entra ID.

​
Configure OIDC SSO

OIDC is the recommended protocol for most identity providers.
1

Register an application in Entra ID

  1. Navigate to Azure Portal > Microsoft Entra ID > App registrations > New registration
  2. Set the Redirect URI to: https://<keycloak-host>/realms/<org-id>/broker/entra-id/endpoint
  3. Note the Application (client) ID and Directory (tenant) ID
  4. Under Certificates & secrets, create a new client secret and note the value
2

Configure group claims

  1. In the app registration, go to Token configuration > Add groups claim
  2. Select Security groups and set the token type to ID
  3. Ensure the groups claim format is set to Group ID
3

Add the IdP in Keycloak

  1. Log in to Keycloak Admin Console
  2. Select the realm matching your organization ID
  3. Navigate to Identity Providers > Add provider > OpenID Connect v1.0
  4. Configure the following:
FieldValue
Aliasentra-id
Authorization URLhttps://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
Token URLhttps://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
Client IDYour Entra ID application client ID
Client SecretYour Entra ID client secret
Default Scopesopenid email profile
4

Map groups to Keycloak roles

In the IdP configuration, add an Attribute Importer mapper:
  • Mapper Type: Attribute Importer
  • Claim: groups
  • User Attribute Name: groups

​
Configure SAML 2.0 SSO

For identity providers that prefer SAML, Keycloak supports SAML 2.0 as well.
1

Export the Keycloak SAML descriptor

Download the SAML metadata from your Keycloak realm:
https://<keycloak-host>/realms/<org-id>/protocol/saml/descriptor
Upload this XML to your IdP as the service provider metadata.
2

Configure the IdP

In your SAML IdP, configure the following:
FieldValue
Entity IDhttps://<keycloak-host>/realms/<org-id>
ACS URLhttps://<keycloak-host>/realms/<org-id>/broker/<alias>/endpoint
Name ID formaturn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
3

Add the SAML IdP in Keycloak

  1. Navigate to Identity Providers > Add provider > SAML v2.0
  2. Import the IdP’s SAML metadata XML or manually configure:
    • Single Sign-On Service URL
    • Single Logout Service URL (optional)
    • Signing certificate
  3. Set NameID Policy Format to email

​
Just-In-Time User Provisioning

Keycloak supports JIT provisioning by default. When a user authenticates via SSO for the first time:
  1. Keycloak creates a local user account in the realm
  2. User attributes (email, name) are synced from the IdP
  3. Group memberships are mapped from IdP claims to Keycloak groups
  4. OpenFGA relationships are established based on group-to-role mappings
JIT provisioning eliminates the need to pre-create user accounts. Users are provisioned automatically on their first SSO login.

​
Enforce SSO (Disable Password Login)

To require SSO for all users in an organization:
  1. In the Keycloak admin console, select the organization’s realm
  2. Navigate to Authentication > Flows
  3. Edit the Browser flow to remove or disable the Username Password Form
  4. Ensure the Identity Provider Redirector is enabled and set to your SSO provider
Keycloak client credentials for service accounts remain available even when password login is disabled. This ensures CI/CD pipelines and machine-to-machine integrations continue to function.

​
Session Management

Configure session behavior for your organization:
SettingLocationDescription
SSO Session IdleRealm Settings > SessionsIdle timeout before re-authentication (default: 30 min)
SSO Session MaxRealm Settings > SessionsMaximum session duration (default: 10 hours)
Remember MeRealm Settings > LoginAllow users to extend their session

​
Group-to-Role Mapping

Map IdP groups to OpenFGA roles for authorization:
IdP GroupKeycloak GroupOpenFGA Role
Platform-Adminsadminsadmin
Developersdevelopersdeveloper
Data-Analystsmembersmember
Viewersviewersviewer
The mapping pipeline flows: IdP groups -> Keycloak groups -> OpenFGA relations. See RBAC Configuration for setting up the OpenFGA side.

​
Troubleshooting

Verify the redirect URI in your IdP matches the Keycloak broker endpoint exactly, including the protocol (HTTPS) and realm ID. Check for trailing slashes.
Ensure group claims are configured in the IdP and a group mapper is set up in the Keycloak identity provider configuration. Verify the claim name matches between the IdP and the Keycloak mapper.
Groups must be mapped from the IdP through Keycloak to OpenFGA. If the group-to-role mapping pipeline is not configured, users will authenticate but have no permissions. See the Group-to-Role Mapping section above.

​
Next Steps

RBAC Configuration

Configure OpenFGA roles and permissions to complete the authorization setup.

Authentication Deep Dive

Learn about OIDC flows, token management, and machine-to-machine authentication.

SCIM Provisioning

Automate user provisioning with SCIM 2.0 for SOC 2 compliance.

Multi-Tenancy

Understand how SSO integrates with the multi-tenant architecture.