SSO with Keycloak

Keycloak is a full OpenID Connect provider, so the integration is the plain OIDC one: OKY discovers your realm's endpoints from the issuer URL and verifies tokens against the realm's keys. Works with Keycloak 18+ (and Red Hat build of Keycloak) — the screenshots differ by version, the settings do not.

What you need

Owner or admin role in your OKY organization, with your e-mail domain(s) verified.
Realm admin access to your Keycloak (https://<host>/admin/). The realm must be reachable from the internet over HTTPS — OKY's servers fetch its discovery document and keys.
Your OKY organization slug (top of Sign-in & domains).
Users in the realm must have a verified e-mail on your OKY-verified domain.

In the Keycloak admin console

Create the client
Select your realm → Clients → Create client. Client type OpenID Connect, Client ID oky, Name “OKY”. Next: turn Client authentication ON (confidential client), leave Standard flow ticked, untick Direct access grants. Next: set Valid redirect URIs to:
Valid redirect URI
https://api.oky.ai/auth/oidc/<your-slug>/callback
Web origins
https://api.oky.ai
Save. Open the Credentials tab and copy the Client secret.
Check the e-mail scope and verified addresses
Client scopes → the client should have email and profile as default scopes (they are, unless someone removed them). OKY requires email_verified = true: either mark users' e-mails as verified in Users → Details, or enable Verify email in Realm settings → Login so users confirm it themselves.
Add a groups mapper (for role mapping)
Clients → oky → Client scopes → oky-dedicated → Add mapper → By configuration → Group Membership. Name groups, Token Claim Name groups, Full group path OFF (so the value is oky-admins, not /oky-admins), Add to ID token ON, Add to userinfo ON. Save.
Then create the groups (Groups → Create group): oky-admins, optionally oky-owners; add members. Skip this whole step if you will assign roles in OKY by hand.
Note the issuer
Realm settings → General → Endpoints → OpenID Endpoint Configuration. The issuer in that JSON is what you paste into OKY: https://<host>/realms/<realm>. Older Keycloak (before 17, or with the legacy /auth context path) uses https://<host>/auth/realms/<realm> — copy whatever the JSON says.

In OKY

Redirect URI to register at Keycloak

Replace <your-slug> with your organization slug (shown at the top of Sign-in & domains).

Authorized redirect URI

https://api.oky.ai/auth/oidc/<your-slug>/callback

Fields in OKY — Organization → Sign-in & domains → OIDC

Field	Value
Issuer URL	`https://<host>/realms/<realm>` — exactly the issuer value from the realm's OpenID configuration; https, no trailing slash
Client ID	From Keycloak (Clients → oky → Client ID).
Client secret	From Keycloak (Clients → oky → Credentials). Stored encrypted; shown once.
Scopes	`openid email profile`
E-mail claim	`email`
Groups claim	`groups` (optional) — the Token Claim Name of your Group Membership mapper
Group → role map	Optional, one per line, e.g. `oky-admins → admin`. Members without a matching group are employees.
Pin to tenant	`No pin` — Keycloak has no tenant claim to pin; isolation comes from the realm issuer and your verified domains

Test login

Save the configuration. OKY fetches the provider's discovery document and keys; a red banner here means the issuer URL is wrong.
Press Test login. A new window opens at Keycloak; sign in with your own work account.
OKY shows what came back — verified e-mail, subject, groups if any, and the pin check — without changing your session or your role.
When the test passes, switch Sign-in method to SSO. Keep work e-mail code fallback on until a second admin has also tested, then turn it off if you want SSO-only.

Keycloak in front of Active Directory or LDAP? Nothing changes for OKY — federated users still get an email claim; just make sure the LDAP mapper marks e-mails verified (or turn on Verify email), and use group mappers to expose AD groups under the groups claim.

Troubleshooting

“Invalid parameter: redirect_uri” at Keycloak

Valid redirect URIs on the client does not contain https://api.oky.ai/auth/oidc/<your-slug>/callback. Add it exactly (a wildcard https://api.oky.ai/* also works but is broader than needed).

“Invalid client or Invalid client credentials”

Client authentication is OFF (public client), or the secret was regenerated after you saved it in OKY. Turn client authentication ON and paste the current secret.

OKY cannot fetch the discovery document

The realm is not reachable from the internet, or the certificate is self-signed / from an internal CA. Expose the realm over a public HTTPS name with a publicly trusted certificate (a reverse proxy in front of Keycloak is fine).

Groups arrive as “/oky-admins”

The mapper has Full group path ON. Turn it off, or write the map as /oky-admins → admin.

“Issuer mismatch”

The iss value inside the token from Keycloak does not equal the Issuer URL you saved. Copy the issuer exactly as this guide shows it — same scheme, host and path, no trailing slash unless the provider includes one. OKY also checks that <issuer>/.well-known/openid-configuration resolves.

“E-mail not verified”

OKY requires email_verified = true in the token. In Keycloak this means the user's e-mail is not marked verified. Users → the user → Details → Email verified ON, or enable Verify email in Realm settings → Login.

“Issuer mismatch”

With Keycloak the check is the issuer itself: the realm that signed the token must match the issuer URL saved in OKY. The pin protects you from someone signing in with a valid Keycloak account from a different organization.

“Redirect URI mismatch” (shown by Keycloak, not OKY)

The URI registered at Keycloak must be exactly https://api.oky.ai/auth/oidc/<your-slug>/callback — https, the api. host, your slug, no trailing slash. Changing the slug means updating the URI at Keycloak.

“Address is outside your verified domains”

The account signed in fine at Keycloak, but its e-mail is on a domain that is not verified in your organization (a personal address, a partner domain, an alias domain you have not added). Add and verify the domain under Sign-in & domains, or ask the person to use their primary work address.

Roles from groups are not applied

Check three things: the groups claim name in OKY matches what Keycloak sends (the mapper's Token Claim Name, 'groups' in this guide; check Full group path is OFF); the group value in the map matches exactly (case-sensitive); and the person actually signed in again after you saved the map — roles are recomputed at login.

Nothing happens after signing in at Keycloak

Usually a browser blocking third-party cookies or a corporate proxy rewriting the redirect. Retry in a normal window; if it repeats, send the time and the address to support@oky.ai and we will read the log for that attempt.