Before setup
Ask your Sana contact for the redirect URI of your Sana workspace.
Setup
Create an OIDC app integration in Okta, then send its domain and client credentials to your Sana contact. The redirect URI is specific to your Sana workspace, so you need one registration per Sana workspace.
1. Start a new app integration
Okta Admin Console → Applications → Applications → Create App Integration.
Sign-in method: OIDC - OpenID Connect. Not SAML, which Sana doesn't support.
Application type: Web Application, the confidential client Sana needs. A SPA or native app has no usable client secret.
Next opens the New Web App Integration screen, which is the whole of step 2.
2. Fill in the New Web App Integration screen
Top to bottom, as Okta lists them:
Field on this screen | What to put |
App integration name | Internal only, for example Sana. Users see the sign-in button name you send to Sana instead (see After setup). |
Proof of possession | Leave Require DPoP header in token requests unchecked. Sana doesn't send DPoP proofs, and the token exchange fails if it's required. |
Grant type | Authorization Code only. It is ticked by default. Leave Client Credentials, Refresh Token and everything under Advanced unticked; Sana doesn't request |
Sign-in redirect URIs | The redirect URI from your Sana contact, exactly as you received it, with no trailing slash. Leave Allow wildcard * unchecked. It looks like this:
|
Sign-out redirect URIs | Leave empty. Sana's sign-out is local: it never calls Okta to close the session, so Okta would never use this. |
Trusted Origins — Base URIs | Leave empty. As the field says, these are for self-hosting the Okta Sign-In Widget; Sana redirects to your Okta-hosted sign-in page and makes no browser calls to Okta's API. |
Controlled access | Allow everyone in your organization, or Limit access to selected groups to pilot with a few people. Skip group assignment for now is fine too, but nobody can sign in until you assign someone on the app's Assignments tab. |
Click Save.
3. Copy the client credentials
Saving lands you on the app's General tab. Under Client Credentials:
Client ID is shown in full.
Client secret sits under CLIENT SECRETS; reveal it and copy the value. Punctuation in a secret is safe: Sana sends the raw bytes as HTTP Basic.
Client authentication must stay Client secret. Require PKCE as additional verification can stay on: Sana always sends an S256 code challenge.
To rotate, add the new secret in Okta first and send it to your Sana contact. Deactivate the old one only after Sana confirms the switch, so sign-in isn't interrupted.
4. Decide which authorization server issues the tokens
Sana needs to know which one you use, and Okta has two kinds with different issuers:
Org: issuer
https://<your-domain>. Exists on every org, returns the standard OIDC claims, and is the right default for signing in to an app.Custom: issuer
https://<your-domain>/oauth2/<id>, for example the built-indefault. Needs API Access Management; the ID is listed under Security → API → Authorization Servers.
Use your Okta domain (acme.okta.com), the one in your Okta URL. Never use the acme-admin.okta.com console host, which serves no discovery document.
5. Check the email claim (required)
Sana needs an email claim in the ID token. Without it, the user signs in at Okta and is then rejected by Sana with error EMAIL_MISSING.
Org server: the
emailscope returns the user's primary email. Nothing to configure, but the Okta profile must have one.Custom server: confirm the
openid,profileandemailscopes exist, and that anemailclaim mapped touser.emailis in the ID token (its Claims tab).
After setup
Send your Sana contact:
Sign-in button name: the label your users see on the Sana sign-in page, for example "Sign in with Okta".
Okta domain (from step 4).
Authorization server: Org or Custom, and for Custom its ID (from step 4).
Client ID and Client secret (from step 3).
Your Sana contact will tell you how to share the client secret securely; don't send it in a regular email or chat message.
