Skip to main content
This page is for customer-managed installations. On Overcut Cloud, see Single Sign-On.
A self-hosted installation can send your team to your organization’s identity provider (Okta, Microsoft Entra ID, Google Workspace, ADFS, or any OIDC or SAML 2.0 provider). Users choose Continue with SSO on the login page, below Sign in with email, and the overcut CLI sign-in offers the same option. Email and password sign-in stays available, so the bootstrap admin can always get in. The Keycloak bundled with your installation brokers the login. You set up providers with the overcut-admin command in the server container, not in the Keycloak admin console.

​
Before you start

  • Overcut v1.3.0 or later, installed from the matching deployment kit.
  • Shell access to run kubectl exec (Kubernetes, AWS) or docker compose exec (Docker Compose) against the installation.
  • Admin access to your identity provider.
  • The workspace users should join, and the email domain or domains they sign in with. Public mailbox domains such as gmail.com are refused.
  • Keycloak must reach your identity provider over HTTPS. Behind an egress proxy or a TLS-intercepting proxy, configure the kit’s proxy and CA bundle settings first. On Kubernetes and AWS they apply to Keycloak too. On Docker Compose, Keycloak has its own proxy and trust store settings in standalone/.env.

​
How it works

  1. A user chooses Continue with SSO and enters their work email.
  2. Overcut looks up the email domain. If a provider is bound to it, the user goes to your identity provider.
  3. Your provider authenticates the user and returns their email, first name, and last name.
  4. An existing member is signed in. A user with an open invitation gets an account and joins the workspace. Anyone else is admitted only when auto-join is on for the provider, otherwise they are asked to request an invitation.
Users are matched by email: a person who already has a password account with the same email keeps it, and both sign-in methods work afterwards. Bind only domains your identity provider is authoritative for.

​
Set up single sign-on

The commands below run the overcut-admin command inside the server container. Use the form for your deployment (on Kubernetes, replace overcut with your namespace if you installed into another one):

Turn on single sign-on

Kubernetes and AWS: set global.sso.enabled: true in your values file (on AWS, helm-values/overcut-values.local.yaml) and run helm upgrade. On AWS, pass both helm-values/overcut-values.rendered.yaml and helm-values/overcut-values.local.yaml to the upgrade.Docker Compose: set SSO_ENABLED=true in standalone/.env and run docker compose up -d.The login page then shows Continue with SSO.

Pick an alias

Choose a short alias for the provider, using lowercase letters, digits, and hyphens, starting with a letter or digit (for example acme-okta). It appears in the URLs below as <alias>, and <domain> is your installation’s hostname.

Create the application in your identity provider

OIDCCreate a web application with:Note the issuer URL, client ID, and client secret.SAML 2.0Create a SAML application with:Add the attribute statements email, firstName, and lastName. Note the identity provider metadata URL. If your provider asks for Overcut’s SP metadata, it is served at https://<domain>/idp/realms/overcut/broker/<alias>/endpoint/descriptor once the provider exists.Assign the users or groups who should be able to sign in.

Write the provider spec

Save the provider details as JSON. For OIDC:
acme-okta.json
For SAML, {"saml": {"metadataUrl": "https://..."}}, or {"saml": {"metadataXml": "<EntityDescriptor ...>"}} when the metadata has no URL. If your provider sends attributes under other names (for example the long claim URIs of ADFS or Entra ID), add "attributes": {"email": "...", "firstName": "...", "lastName": "..."} at the top level, next to oidc or saml. If the OIDC discovery document is not at <issuer>/.well-known/openid-configuration, add "discoveryUrl" inside oidc. To sync teams from your provider’s groups, also add a groups key; see Sync teams from IdP groups. Unknown keys are rejected.The spec is read from standard input (--spec=-) or from a file (--spec=<path>), so the client secret never appears on a command line. Delete the file when you are done.

Create the provider

Find the workspace ID, then create the provider and bind it to the workspace and its email domains:
This creates the provider in the bundled Keycloak with Overcut’s settings and binds it in invitation-only mode (add --auto-join to start with auto-join on).

Check the setup

Each check prints [ok], [FAIL], or [??] (could not verify). Fix every [FAIL] and look into any [??] before going on. Then invite one person from your organization and have them sign in through Continue with SSO.

Roll out to the team

Invite the rest of the team, or turn on auto-join so anyone on the bound domains can sign in without an invitation:
Workspace admins can also switch auto-join and the provider on or off under Security → Single sign-on.

​
Sync teams from IdP groups

Team sync puts people in Overcut teams based on their groups in your identity provider; see Sync teams from IdP groups for how it works. On a self-hosted installation, you turn on group import in the provider spec. It needs Overcut v1.4.0 or later.

Send groups from your identity provider

Configure your provider to include the user’s groups at sign-in, as described in Set up team sync. For example, on Okta (OIDC), set a Groups claim named groups on the application’s Sign On tab, with a filter for the groups Overcut should see.

Import groups into Overcut

Add a groups key to the provider spec, next to oidc or saml:
acme-okta.json
  • claim: the OIDC claim or SAML attribute that lists the groups. Defaults to groups.
  • scope (OIDC only): an extra scope to request when your provider sends groups only for that scope. Okta authorization servers need groups; Microsoft Entra ID needs none.
  • overageClaim (OIDC only): on Microsoft Entra ID, set it to _claim_names.groups so that a user in too many groups for the token keeps their teams instead of losing them.
Then apply the spec. For a provider that already exists, use sso update; the spec replaces the stored one, so include the client secret or SAML metadata again:
For a new provider, pass the same spec to sso create.

Check which groups arrive

Have one user sign out of Overcut, then sign in again with SSO. Open their page under Security → Users. The Identity provider groups section shows the exact values your provider sent.

Turn on sync and link groups to teams

Turn on Sync team memberships from IdP groups in the provider’s settings dialog under Security → Single sign-on, or run sso update --alias=acme-okta --group-sync=true. Then open each team under Security → Teams and add its groups under Identity provider groups.
Turn on sync only after the groups show up on a user’s page. With sync on, a user whose provider sends no groups is removed from every linked team at their next sign-in.

​
Operate

sso delete removes the binding first, then the provider in Keycloak. If the second part fails, run sso delete --alias=<alias> --idp-only to finish. To switch a provider between OIDC and SAML, delete it and create it again; sso update cannot change the protocol. Upgrades keep your providers. Each upgrade brings the Keycloak realm up to date and leaves users, passwords, and identity providers alone.

​
Troubleshooting

  • SSO_LOGIN_ENABLED is true on the server: single sign-on is not turned on. Repeat the first setup step.
  • Realm has the “first broker login auto-link” flow or Client “overcut-web” maps the identity_provider claim (on Kubernetes and AWS, also Client “overcut-cli” maps the identity_provider claim): the realm is from an older release and was not brought up to date. Upgrade to the current kit and check the realm update ran: kubectl -n overcut logs job/keycloak-config-cli or docker compose logs keycloak-sync.
  • exists in Keycloak or uses the “first broker login auto-link” flow: the provider was created or changed by hand. Re-apply it with sso update --alias=<alias> --spec=- < spec.json.
Keycloak fetches the OIDC discovery document or SAML metadata itself. A timeout or TLS error means Keycloak cannot reach your identity provider: check the kit’s proxy settings and, behind a TLS-intercepting proxy, that the proxy’s CA is in the kit’s CA bundle.
No enabled provider is bound to the domain of the email the user entered, or single sign-on is turned off for the installation. Check for a typo, sign in with email instead, bind the domain with sso update --alias=<alias> --domains=..., or turn the provider on.
The user sees “Your organization uses single sign-on, but <email> has not been invited to the <provider name> workspace yet. Ask a workspace admin to invite you.” The provider is in invitation-only mode and the user has no open invitation. Invite them, or turn on auto-join.
The provider was turned off, or single sign-on was turned off for the installation, while the user was signing in. Turn it back on with sso update --alias=<alias> --enabled=true or under Security → Single sign-on.
The application on your provider’s side does not match: check the redirect or ACS URL, that the user is assigned to the application, and for SAML that the certificate has not expired and assertions are signed. For SAML also check that the Overcut server’s and the identity provider’s clocks are in sync. For OIDC, if your provider asks how the client authenticates, choose the client secret sent in the request body (client_secret_post).

​
Limitations

  • No single logout. Signing out of Overcut does not sign you out of your identity provider.
  • One workspace per domain. A given email domain can be bound to a single workspace.
  • Providers are managed with overcut-admin. There is no screen for adding a provider; workspace admins can only switch auto-join and the provider on or off.