Single sign-on (SAML 2.0)

Kumkuat supports single sign-on (SSO) over SAML 2.0, so your people sign in with the identity provider (IdP) your organisation already runs, and your IdP's policies apply: multi-factor authentication, conditional access, device rules and offboarding. Any SAML 2.0 provider works. This page walks through Microsoft Entra ID (Azure AD) and Okta, and lists the values for any other provider.

Setting it up is self-service and takes about fifteen minutes. A workspace owner or admin configures it under Workspace settings → Single sign-on; someone with rights to create an enterprise application in your IdP does the other half.

What you get

• Sign in with your IdP. People enter their work email on the Kumkuat login page and are sent to your IdP. No Kumkuat password exists for them.
• Just-in-time membership. Someone who signs in through your IdP for the first time is added to your workspace automatically, with the role you choose. No invitations to manage.
• Enforcement. Once SSO is proven to work, you can require it: password sign-in and sign-up are refused for your email domains.
• Offboarding follows your IdP. Remove or disable a person in your IdP and they can no longer sign in.

How it works

Kumkuat is the service provider (SP). Your IdP authenticates the person and posts a signed SAML assertion back to Kumkuat; Kumkuat verifies the signature against the certificate you registered and signs the person in. The flow is SP-initiated: it starts from the Kumkuat login page or from the sign-in link below, which you can place on your intranet or in your IdP's application launcher.

Only the person's email address (as the SAML NameID) is required. Kumkuat does not read group claims, and it does not write anything back to your IdP.

Before you start

You need:

• an owner or admin role in the Kumkuat workspace;
• rights to create a SAML application in your IdP (Entra ID: Cloud Application Administrator or above; Okta: Application Administrator);
• the email domains your people sign in with, for example example.com and example.co.uk.

Open Workspace settings → Single sign-on in Kumkuat. The panel shows the values your IdP needs before anything is saved:

Value	What it is
Entity ID (Identifier, Audience URI)	https://app.kumkuat.ai/saml/<slug> where <slug> is the short name you choose for the sign-in link
Reply URL (Assertion Consumer Service URL)	https://auth.kumkuat.ai/__/auth/handler
Sign-on URL	https://app.kumkuat.ai/login?sso=<slug>
NameID format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Binding	HTTP-POST for the assertion; HTTP-Redirect for the request

Each value has a Copy button. The slug defaults to your workspace name; change it before creating the IdP application if you want a different one, because it is part of the Entity ID.

tip

The Reply URL is on auth.kumkuat.ai, not on app.kumkuat.ai. That host is Kumkuat's sign-in service, which runs on Google Cloud Identity Platform; a dedicated sign-in hostname is the usual arrangement. It is the same for every Kumkuat customer.

Step 1 — Create the application in your IdP

Microsoft Entra ID (Azure AD)

1. In the Microsoft Entra admin center, open Identity → Applications → Enterprise applications → New application → Create your own application. Name it Kumkuat, choose Integrate any other application you don't find in the gallery (Non-gallery), and create it.
2. Open the application, go to Single sign-on → SAML.
3. Under Basic SAML Configuration, edit and set:
   • Identifier (Entity ID): the Entity ID from Kumkuat (https://app.kumkuat.ai/saml/<slug>), marked as default
   • Reply URL (Assertion Consumer Service URL): https://auth.kumkuat.ai/__/auth/handler
   • Sign on URL: https://app.kumkuat.ai/login?sso=<slug>
   • Leave Relay State and Logout URL empty.
4. Under Attributes & Claims, edit the Unique User Identifier (Name ID) claim: set Name identifier format to Email address and Source attribute to user.mail (use user.userprincipalname only if UPNs are the addresses your people sign in with). Keep the default additional claims; Kumkuat ignores them.
5. Under SAML Certificates, download Certificate (Base64). Copy Login URL and Microsoft Entra Identifier from the Set up Kumkuat section. They look like:
   • Login URL: https://login.microsoftonline.com/<tenant-id>/saml2
   • Microsoft Entra Identifier: https://sts.windows.net/<tenant-id>/
6. Under Users and groups, assign the users or groups who may sign in. Only assigned people can use the application unless you turn assignment off in Properties.

Azure Government (GCC High / DoD)

If your tenant is in the US Government cloud, the endpoints differ: the Login URL is on login.microsoftonline.us and the identifier on https://sts.windows.net/<tenant-id>/ as shown in your portal. Copy whatever the Set up Kumkuat section displays; Kumkuat has no fixed expectation of the host.

Okta

1. In the Okta Admin Console, open Applications → Applications → Create App Integration, choose SAML 2.0, and name it Kumkuat.
2. Under Configure SAML, set:
   • Single sign-on URL: https://auth.kumkuat.ai/__/auth/handler (keep Use this for Recipient URL and Destination URL ticked)
   • Audience URI (SP Entity ID): the Entity ID from Kumkuat
   • Name ID format: EmailAddress
   • Application username: Email
3. Finish the wizard. On the Sign On tab, open View SAML setup instructions (or More details) and copy the Identity Provider Single Sign-On URL, the Identity Provider Issuer, and download the X.509 Certificate.
4. On the Assignments tab, assign the people or groups who may sign in.

Google Workspace

Google Workspace is a SAML identity provider in its own right, so you do not need any extra product to use it here.

1. In the Google Admin console, open Apps → Web and mobile apps, then Add app → Add custom SAML app. You need to be a super administrator.

2. App details: name it Kumkuat. A logo is optional. Click Continue.

3. Google Identity Provider details: this screen shows what Kumkuat needs. Copy the SSO URL and the Entity ID, and click Download certificate for the X.509 certificate. They look like:

   • SSO URL: https://accounts.google.com/o/saml2/idp?idpid=<your-idp-id>
   • Entity ID: https://accounts.google.com/o/saml2?idpid=<your-idp-id>

   Keep this tab open, or paste the three values somewhere for the next step. Click Continue.

4. Service provider details: enter the values from the table above.

   • ACS URL: https://auth.kumkuat.ai/__/auth/handler
   • Entity ID: the Entity ID from Kumkuat, https://app.kumkuat.ai/saml/<slug>
   • Start URL (optional): https://app.kumkuat.ai/login?sso=<slug>
   • Leave Signed response unticked. Google signs the assertion either way, which is what Kumkuat verifies.
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email

   Click Continue.

5. Attribute mapping: nothing is required. Kumkuat reads the Name ID only. Click Finish.

6. Turn the app on. This is the step people miss. Open the app you just created, click User access, and set it to ON for everyone, or ON for the organisational units and groups that should reach Kumkuat. Save. Changes usually apply within minutes.

Then register the three values in Kumkuat as described in Step 2 below: the Entity ID becomes Identity provider Entity ID (Issuer), the SSO URL becomes Sign-on URL, and the downloaded file is the signing certificate.

Google-specific gotchas

• "This account cannot be accessed because the app is not enabled" means step 6 was skipped, or the person sits outside the organisational units you granted.
• Google's certificate downloads as a .pem or .cer file. Open it in a text editor and paste the whole thing, -----BEGIN CERTIFICATE----- line included.
• Google rotates this certificate only when you ask it to, under the app's Google Identity Provider details. When you do rotate, paste the new certificate alongside the old one in Kumkuat first, then remove the old one.

Any other SAML 2.0 provider

Create a SAML service-provider entry with the four values from the table above. Then collect three things from the IdP: its Entity ID / Issuer, its SSO URL (where SAML requests are sent; HTTP-Redirect binding), and its signing certificate (X.509, PEM or Base64). Kumkuat does not currently import IdP metadata XML, so copy these values by hand.

Step 2 — Register the IdP in Kumkuat

Back in Workspace settings → Single sign-on:

1. Display name: what the login button says, for example Continue with Example Corp.
2. Sign-in link slug: keep the one you used for the Entity ID.
3. Identity provider Entity ID (Issuer): the Entra identifier or Okta issuer.
4. Sign-on URL: the Entra Login URL or Okta SSO URL.
5. Signing certificate: paste the certificate you downloaded. Both PEM (-----BEGIN CERTIFICATE-----) and bare Base64 are accepted.
6. Email domains: every domain your people sign in with, comma-separated. Sign-ins from these domains are routed to this provider.
7. Add new users automatically and the role they receive (member by default; viewer for read-only, admin if your IdP group already controls who administers Kumkuat).
8. Leave Require single sign-on off for now.
9. Click Save and enable.

The panel now shows Enabled · not yet verified by a sign-in.

Step 3 — Test

1. Open a private browser window and go to https://app.kumkuat.ai/login.
2. Enter a work email on one of your domains and click Continue with single sign-on. Your IdP's sign-in opens in a popup (or redirects if popups are blocked).
3. Sign in. You land in the workspace. If this is a new person, they appear under Workspace → Members with the default role.

The Single sign-on panel now shows the date of the last successful sign-in.

If the IdP rejects the request, the most common causes are: the Entity ID in the IdP does not match Kumkuat's exactly (trailing slashes count); the Reply URL was typed rather than copied; the person is not assigned to the application; or the certificate pasted is not the signing certificate the IdP currently uses.

Step 4 — Require single sign-on (optional)

After at least one successful sign-in, tick Require single sign-on for these domains and save. From then on:

• password sign-in for those domains is refused with a prompt to continue with SSO;
• password sign-up for those domains is refused;
• existing members with a Kumkuat password keep their account but must sign in through the IdP.

Enforcement is deliberately locked until a real sign-in has succeeded, so a mistyped IdP setting cannot lock everyone out.

Day-to-day

• Join, roles and removal. New people join with the default role on first sign-in. Change roles afterwards under Workspace → Members, as for any member. Removing someone from the IdP application stops new sign-ins; remove them from the workspace too to end an active session and their API keys.
• Password sign-ups never auto-join. Only a sign-in through your IdP admits someone. A person who creates a Kumkuat password account with one of your addresses is not added to your workspace.
• Addresses outside your domains are refused even when the IdP vouches for them, so a misconfigured IdP cannot admit guests.
• Certificate rotation. Paste the new certificate alongside the old one and save; both are accepted during the changeover. Remove the expired one afterwards. Up to three certificates can be active.
• Pause. Untick Enabled to stop routing sign-ins to the IdP without deleting the configuration.
• Remove. Remove single sign-on deletes the provider. People keep their accounts and can set a password from Forgot password.
• People only type their email once. After someone signs in through your provider, that browser remembers it and the button goes straight there next time. They can enter a different address to switch, or use Use a different account to clear it. Email and password sign-in stays available on the same page throughout, which matters if anyone holds both a company account and a separate one.
• Your domain works on its own. People can type example.com instead of their full address; either finds your provider.
• Sign-in link. https://app.kumkuat.ai/login?sso=<slug> opens the login page with your provider pre-selected and starts the sign-in. Use it for an app-launcher tile or an intranet link. IdP-initiated sign-in (starting from the IdP's portal without this link) is not supported; a tile that opens this link behaves the same for your users.
• Several workspaces. A domain can be routed to one workspace's provider. If your organisation has several Kumkuat workspaces, configure SSO on one of them and invite the same people to the others, or ask your Kumkuat contact about the best arrangement.

Security notes

• Assertions must be signed by the registered certificate; unsigned or differently signed assertions are rejected by the sign-in service.
• Kumkuat reads the NameID (email) and standard email attributes only. Group, role and custom claims are ignored.
• The IdP certificate is public key material. Nothing secret about your IdP is stored in Kumkuat.
• Kumkuat's sign-in service is Google Cloud Identity Platform; assertions terminate there and never reach a browser page. See the Security overview.

Troubleshooting

Symptom	Likely cause
No single sign-on for this domain on the login page	The email's domain is not in the panel's Email domains, or SSO is disabled.
This sign-in provider is not enabled	The provider was removed or is paused. Check the panel, or that Identity Platform is enabled for the deployment.
IdP error mentioning the audience or issuer	Entity ID mismatch. Copy the Entity ID from the panel again and compare character by character.
IdP error mentioning the reply URL	The Reply URL must be exactly https://auth.kumkuat.ai/__/auth/handler.
Your identity provider did not send an email address	The NameID is not the email. In Entra set the Name ID source to user.mail with format Email address; in Okta set Name ID format to EmailAddress.
Signed in, but landed in a personal workspace or No workspace yet	Add new users automatically is off, or the person's address is outside the configured domains.
Popup is blocked, or Single sign-on did not complete	The button opens your IdP in a popup; a blocked popup falls back to a full-page redirect. Browsers that partition third-party storage (Safari, Firefox in strict mode) can drop the redirect result, so allow popups for app.kumkuat.ai and click Continue with single sign-on again.