SSO with Okta — OKY Docs

OKY connects to Okta with standard OpenID Connect. Assign the app to the people (or groups) who should have OKY, choose which authorization server issues the tokens, and Okta's MFA, device trust and de-provisioning apply to OKY sign-in automatically.

What you need

Owner or admin role in your OKY organization, with your e-mail domain(s) verified.
Okta Super Admin or Application Admin in the Okta Admin Console.
Your OKY organization slug (top of Sign-in & domains) and your Okta org URL (e.g. https://acme.okta.com).
Optional, for role mapping: an Okta group such as oky-admins.

In the Okta Admin Console

Create the app integration
Applications → Applications → Create App Integration. Sign-in method OIDC – OpenID Connect, application type Web Application. Name “OKY”. Grant type: Authorization Code only (leave Refresh Token and Implicit unticked). Sign-in redirect URI:
Sign-in redirect URI
https://api.oky.ai/auth/oidc/<your-slug>/callback
Sign-out redirect URI: leave empty. Under Assignments choose who can use it — Limit access to selected groups is the usual choice. Save, then copy the Client ID and Client secret from the General tab.
Choose the issuer
Two options:
- Org authorization server — issuer https://acme.okta.com. Simplest; available on every Okta plan. Tokens carry email, email_verified and, if you add it (step 3), groups.
- Custom authorization server — issuer https://acme.okta.com/oauth2/default (or another server ID). Needed if you want custom claims or scopes; requires the API Access Management feature. Security → API → Authorization Servers shows the exact issuer URI.
Add the groups claim (for role mapping)
Org authorization server: Applications → OKY → Sign On tab → OpenID Connect ID Token → Edit → Groups claim type Filter, claim name groups, filter Starts with oky-. Save.
Custom authorization server: Security → API → your server → Claims → Add claim: name groups, include in ID Token (Always), value type Groups, filter Starts with oky-, include in any scope. Save.
Then create the groups (Directory → Groups): oky-admins, optionally oky-owners; add members and assign the OKY app to them. Skip this step if you will assign roles in OKY by hand.

In OKY

Redirect URI to register at Okta

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://<org>.okta.com` — or https://<org>.okta.com/oauth2/<server-id> for a custom authorization server; use your custom Okta domain if you have one (e.g. https://login.acme.com)
Client ID	From Okta (Applications → OKY → General → Client Credentials).
Client secret	From Okta (same place, Client secret). Stored encrypted; shown once.
Scopes	`openid email profile`
E-mail claim	`email`
Groups claim	`groups` (optional) — the claim name you configured in step 3
Group → role map	Optional, one per line, e.g. `oky-admins → admin`. Members without a matching group are employees.
Pin to tenant	`No pin` — Okta has no tenant claim to pin; your org URL in the issuer is the tenant

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 Okta; 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.

Okta issues tokens only to users the app is assigned to. Assigning the app to an “Everyone” or “All employees” group is the closest thing to auto-join; combine it with OKY's auto-join by verified domain and nobody has to be invited by hand.

Troubleshooting

“The redirect_uri parameter must be a Login redirect URI in the client app settings” (error 400)

The sign-in redirect URI on the app is not exactly https://api.oky.ai/auth/oidc/<your-slug>/callback. Fix under Applications → OKY → General → Edit.

“User is not assigned to the client application”

Assign the app to the person or their group under Applications → OKY → Assignments.

Groups claim empty

The filter (Starts with oky-) does not match your group names, or the claim was added to the access token instead of the ID token. OKY reads the ID token.

Custom domain: issuer mismatch

If your org uses a custom domain (login.acme.com), tokens are issued with that host. Use it in the OKY issuer field, not acme.okta.com.

“Issuer mismatch”

The iss value inside the token from Okta 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. Okta sends email_verified = true for verified primary e-mails. If you see this, the user's primary e-mail in Okta is unverified (Directory → People → the user) or the app is not sending the email scope — check the app's Sign On settings.

“Issuer mismatch”

With Okta the check is the issuer itself: the org or authorization server that signed the token must equal the issuer URL saved in OKY (org URL vs /oauth2/default is the usual mix-up). The pin protects you from someone signing in with a valid Okta account from a different organization.

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

The URI registered at Okta 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 Okta.

“Address is outside your verified domains”

The account signed in fine at Okta, 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 Okta sends ('groups', only present if you added the claim; check the filter actually matches your group names); 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 Okta

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.