Skip to main content

Set up single sign-on (SSO) with Okta

J
Written by JP Arredondo

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 offline_access.

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:

  • EU workspaces: https://sana-eu.myworkday.com/x-api/<workspace ID>/auth/oidc/callback

  • US workspaces: https://sana.myworkday.com/x-api/<workspace ID>/auth/oidc/callback

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-in default. 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 email scope returns the user's primary email. Nothing to configure, but the Okta profile must have one.

  • Custom server: confirm the openid, profile and email scopes exist, and that an email claim mapped to user.email is 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.

Did this answer your question?