OKY talks to Google with standard OpenID Connect. Your Workspace MFA, device rules and off-boarding apply automatically, and OKY only ever accepts accounts from your Workspace domain — a personal Google account with the same name cannot get in.
What you need
- Owner or admin role in your OKY organization, with your Workspace domain verified.
- Access to Google Cloud Console in a project that belongs to your Workspace organization (any project; a fresh one is fine).
- Your OKY organization slug (top of Sign-in & domains).
In Google Cloud Console
- Configure the OAuth consent screen
APIs & Services → OAuth consent screen. Choose Internal (only accounts in your Workspace can use it), name the app “OKY”, add support and developer e-mails, save. Internal apps need no verification.
- Create the OAuth client
APIs & Services → Credentials → Create credentials → OAuth client ID. Application type Web application, name “OKY sign-in”. Under Authorized redirect URIs add:
Authorized redirect URIhttps://api.oky.ai/auth/oidc/<your-slug>/callbackLeave Authorized JavaScript origins empty. Click Create and copy the Client ID and Client secret.
- Note on groups
Google does not include group membership in the sign-in token, so role mapping from Google Groups is not available with Workspace SSO. Assign admins in OKY (Members → Change role) — a one-time step for a handful of people. Leave Groups claim empty in OKY.
In OKY
Redirect URI to register at Google
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://accounts.google.com |
| Client ID | From Google (the OAuth client you created). |
| Client secret | From Google (same OAuth client). Stored encrypted; shown once. |
| Scopes | openid email profile |
| E-mail claim | email |
| Groups claim | Leave empty — Google does not send group membership in the sign-in token. |
| Group → role map | Not available with Google. Assign admins under Organization → Members → Change role. |
| Pin to tenant | Google hd = acme.com — choose Google hd and enter your Workspace domain; only tokens whose hd equals it are accepted |
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 Google; 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.
Google sends one hd per account — the Workspace domain it belongs to. The pin holds one value; if your Workspace has secondary domains and people on them are refused with an hd mismatch, add those domains as verified in OKY and write to support@oky.ai — we will widen the pin for your organization.
Troubleshooting
“Error 403: org_internal” at Google
The consent screen is Internal and the person signed in with an account outside your Workspace. That is the intended behaviour; ask them to use their work account.
“Access blocked: this app's request is invalid” / redirect_uri_mismatch
The redirect URI in the OAuth client differs from the one above — most often a missing api., an http:// or a wrong slug. Fix it in Credentials; Google applies it within a few minutes.
“Issuer mismatch”
The iss value inside the token from Google 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. Google marks Workspace accounts as verified; if you see this the account is probably a consumer Gmail — check the hd pin and the address.
“hd mismatch”
The signed-in account's Workspace domain (hd) is not the one you pinned. Either the person used a personal Google account, or they belong to a Workspace domain you have not listed. The pin protects you from someone signing in with a valid Google account from a different organization.
“Redirect URI mismatch” (shown by Google, not OKY)
The URI registered at Google 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 Google.
“Address is outside your verified domains”
The account signed in fine at Google, 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.
Nothing happens after signing in at Google
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.