OKY uses Entra ID's OpenID Connect endpoints. Register one app in your tenant, paste four values into OKY, and Conditional Access, MFA and off-boarding in Entra apply to OKY sign-in automatically.
What you need
- Owner or admin role in your OKY organization, with your e-mail domain(s) verified.
- An Entra role that can register applications (Application Administrator, Cloud Application Administrator or Global Administrator) in the Microsoft Entra admin center.
- Your OKY organization slug (top of Sign-in & domains) and your Tenant ID (Entra admin center → Overview).
- Optional, for role mapping: a security group such as
OKY Admins.
In the Microsoft Entra admin center
- Register the application
Identity → Applications → App registrations → New registration. Name “OKY”. Supported account types: Accounts in this organizational directory only (single tenant) — recommended, so only your people can even reach the sign-in. Redirect URI: platform Web, value:
Redirect URI (Web)https://api.oky.ai/auth/oidc/<your-slug>/callbackClick Register. Copy the Application (client) ID and the Directory (tenant) ID from the Overview page.
- Create a client secret
Certificates & secrets → New client secret. Description “OKY”, choose an expiry (12 or 24 months). Copy the secret Value immediately — it is not shown again. Put a reminder in your calendar for the expiry; sign-in stops when it lapses.
- Confirm the token claims
Token configuration → Add optional claim → token type ID → tick
email(andpreferred_usernameif you like). Under API permissions, the defaultsopenid,email,profile(Microsoft Graph, delegated) are enough; grant admin consent for the tenant so users are not prompted individually. - Optional: groups for role mapping
Token configuration → Add groups claim → Security groups, and for the ID token choose Group ID (default). Entra sends group object IDs, not names — you will paste the object ID of your “OKY Admins” group into the role map. (If your tenant is Entra ID P1+ and you prefer names, choose sAMAccountName / Cloud-only group display names where available.)
In OKY
Redirect URI to register at Entra ID
Replace <your-slug> with your organization slug (shown at the top of Sign-in & domains).
https://api.oky.ai/auth/oidc/<your-slug>/callbackFields in OKY — Organization → Sign-in & domains → OIDC
| Field | Value |
|---|---|
| Issuer URL | https://login.microsoftonline.com/<tenant-id>/v2.0 — replace <tenant-id> with your Directory (tenant) ID; do not use 'common' or 'organizations' |
| Client ID | From Entra ID (Application (client) ID on the app's Overview page). |
| Client secret | From Entra ID (the secret Value you copied under Certificates & secrets). Stored encrypted; shown once. |
| Scopes | openid email profile |
| E-mail claim | email — see the note below on email vs preferred_username |
| Groups claim | groups (optional) — only if you added the groups claim |
| Group → role map | Optional, one per line, e.g. 8f2c1e0a-… (group object ID) → admin. Members without a matching group are employees. |
| Pin to tenant | Entra tid = <tenant-id> — choose Entra tid and enter your Directory (tenant) ID; OKY accepts tokens only from this tenant, even if the app were ever made multi-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 Entra ID; 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.
email vs preferred_username. Entra puts the sign-in name (UPN) in preferred_username and the mailbox address in email — they differ in some tenants (e.g. j.doe@acme.onmicrosoft.com vs john.doe@acme.com), and email is only present if you added the optional claim (step 3) and the user has a mail attribute.
Use email when your users' primary SMTP address is on your verified domain (the usual case). Use preferred_username only if UPNs are on the verified domain and mail attributes are unreliable. Whatever you choose must land on a verified OKY domain, or sign-in is refused with “address outside your verified domains”.
Troubleshooting
AADSTS50011 — reply URL does not match
The redirect URI on the app registration is not exactly https://api.oky.ai/auth/oidc/<your-slug>/callback. Fix under Authentication → Web → Redirect URIs.
AADSTS700016 — application not found in the directory
The issuer tenant ID in OKY belongs to a different tenant than the app registration. Both must be your tenant.
AADSTS7000215 — invalid client secret
You pasted the secret's ID instead of its Value, or the secret expired. Create a new one and paste the Value.
“Need admin approval” shown to users
Grant admin consent under API permissions once, for the whole tenant.
Groups claim missing or truncated
Members of more than ~200 groups get a “groups overage” instead of the list; put the OKY groups in a small dedicated group and, if needed, restrict the claim to groups assigned to the application (Enterprise applications → OKY → Users and groups).
“Issuer mismatch”
The iss value inside the token from Entra ID 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. With Entra this appears when the address in the token comes from a domain your tenant has not verified in Microsoft 365 (Settings → Domains), or when the email optional claim is missing so OKY cannot confirm the address. Add the claim (step 3), make sure the user's primary address is on a Microsoft-verified domain, and run Test login again.
“tid mismatch”
The token's tenant (tid) is not the one you pinned — usually the issuer contains a different tenant ID than the pin, or someone signed in with a guest account from another tenant. The pin protects you from someone signing in with a valid Entra ID account from a different organization.
“Redirect URI mismatch” (shown by Entra ID, not OKY)
The URI registered at Entra ID 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 Entra ID.
“Address is outside your verified domains”
The account signed in fine at Entra ID, 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 Entra ID sends ('groups' with object IDs by default); 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 Entra ID
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.