SSO and SCIM
The setup order for company account (IdP) sign-in and automatic user sync.
Connecting Keural to your company's IdP (Okta, Microsoft Entra ID, Google Workspace, and others) lets employees sign in with their company accounts. They join the organization automatically on their first sign-in.
For the specification for IdP administrators and developers, see the SSO·SCIM integration spec.
Prerequisites
| Item | Why |
|---|---|
| An owner account for the Keural organization | Only owners can change SSO settings. |
| IdP administrator permission | Create the Keural application in your IdP. |
| DNS management permission for the company domain | Domain ownership is verified with a TXT record. |
Supported methods
| Method | Purpose |
|---|---|
| OpenID Connect (OIDC) | Sign in with a company account |
| SAML 2.0 | Sign in with a company account. The authentication request uses Redirect, and the response is received over HTTP-POST. |
| SCIM 2.0 | When you add or deactivate users in your IdP, the changes are reflected automatically in Keural accounts |
Choose either OIDC or SAML. If your IdP supports both, OIDC is recommended because its setup is simpler.
Setup order
- Verify your company domain
- Create an application in your IdP
- Enter the values in Keural and save
- Turn on SSO and test sign-in
- Connect SCIM (optional)
All settings are made under Organization management → SSO.
1. Verify your company domain
Verify ownership of the email domain you will use for SSO first. A domain that is not verified cannot be saved in step 3.
Enter your company domain (for example, acme.com) under Organization domains, and press Add domain.
On the domain's row, press Verify. Copy the TXT record value (keural-verify=…) shown in the Verify domain window.
On your DNS management screen, add a TXT record to that domain, and paste the copied value. The host (name) is the domain itself (usually @).
Go back to Keural and press Confirm verification. When Verified appears, you are done. DNS changes can take tens of minutes to take effect, so if it fails, press the button again after a while.
If you have more than one company domain, add and verify each one. Public email domains such as gmail.com cannot be used.
2. Create an application in your IdP
At the top of the SSO settings, choose OpenID Connect (OIDC) or SAML 2.0 under Protocol. The Keural values to register in your IdP are displayed. Enter these values in your IdP application, and copy the values your IdP issues.
| Direction | Item | Details |
|---|---|---|
| Keural → IdP | Callback URI | Enter it in the redirect URI of your IdP application. |
| IdP → Keural | Issuer URL | The issuer address of your IdP. |
| IdP → Keural | Client ID · Client Secret | The values issued when you create the IdP application. |
Sign-in works only if your IdP is configured to send the user's email address.
| IdP | Where to create it | Field for the callback URI | Issuer URL |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<Okta domain> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI (Web) | https://login.microsoftonline.com/<tenant ID>/v2.0 |
| Google Workspace | Google Cloud console → APIs & Services → Credentials → OAuth client ID (Web application) | Authorized redirect URIs | https://accounts.google.com |
- Microsoft Entra ID: The Client Secret is the Value of the secret you create under Certificates & secrets. Under Token configuration, add the
emailoptional claim to the ID token. - Okta: In the application's Assignments, specify the users or groups who will use Keural.
3. Enter the values in Keural and save
- Enter the IdP values you received in step 2.
- Under Email domains, enter the domain you verified in step 1, separating multiple domains with commas. When someone signs in with an email from this domain, they are taken to the company sign-in screen.
- Configure Auto-create users on first login (JIT). If it is on, an account is created the first time an employee without a Keural account signs in through SSO. If it is off, only people who already have an account can sign in.
- Press Save.
For OIDC, if your IdP does not provide the standard addresses (discovery), enter the endpoints directly under Show advanced settings. Most IdPs can leave this empty.
4. Turn on SSO and test sign-in
- Turn on Enable SSO and press Save.
- Press Test login. The company sign-in screen opens in a new window.
- Sign in with your company account and return to Keural. If you return successfully, the connection is complete.
Test login works only when SSO is turned on. If there is a problem, turn off Enable SSO and press Save. In the meantime, employees on that domain sign in with the email link.
Employee sign-in
- Enter your company email on the Keural sign-in screen to go to the company sign-in screen. After you sign in, you return to Keural.
- In the desktop app, sign in with the email link instead of the company sign-in screen.
- An employee who signs in through SSO for the first time joins the organization as a Member. Admin roles are assigned separately under Organization management.
In the following cases, sign-in succeeds but the user does not join the organization automatically.
- All seats purchased by the organization are full.
- The account already belongs to another organization.
5. Connect SCIM (optional)
When SCIM is connected, adding or deactivating users in your IdP is reflected in Keural accounts immediately. Set it up after completing the SSO connection.
Under SCIM provisioning, turn on Enable SCIM provisioning.
Press Issue token, and copy the token. The token is shown only once.
In the provisioning settings of your IdP, enter the SCIM Base URL (Tenant URL) and the token. The authentication method is a Bearer token.
| IdP | Where to enter it |
|---|---|
| Okta | Application → Provisioning → SCIM connector base URL. Authentication Mode is HTTP Header. |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
Changes made in your IdP are reflected in Keural as follows.
| In your IdP | In Keural |
|---|---|
| Assign a user | An account is created and added to the organization. The username is the email address. |
| Deactivate a user or remove the assignment | The account is suspended and sign-in is blocked. Data is not deleted. |
| Reactivate | The suspension is lifted. |
| Add to or remove from the Keural Admins group | The user is promoted to admin or demoted to member. The owner does not change. |
If you lose the token, press Re-issue token and enter the new token in your IdP. The existing token becomes invalid immediately.
Troubleshooting
| Symptom | Action |
|---|---|
| The email domain is not saved | Check that you completed domain verification in step 1, and that the domain is not a public email domain. |
| Domain verification fails | Check that you entered the whole TXT value from keural-verify= onward, wait for DNS to update, and then press the button again. |
| The company sign-in screen does not open when you press Test login | Check that you turned on Enable SSO and saved. |
| After company sign-in, you return to the Keural sign-in screen | For OIDC, check the callback URI, Issuer URL, Client Secret, and email claim. For SAML, check the SP EntityID, ACS URL, certificate, and email attribute. |
| Sign-in is refused because no account exists | Auto-create users on first login (JIT) is off. Turn it on, or invite the employee first. |
| Sign-in works, but the organization workspace is not visible | Check whether seats are still available and whether the account belongs to another organization. |
| Sign-in fails when you open the app from the IdP portal (SAML) | Start from the Keural sign-in screen with your company email. |
| The SCIM connection test fails | Enter the Base URL and token again. If you re-issued the token, replace it with the new one. |