Skip to main content

Set up single sign-on (SSO) with Microsoft Entra ID

J
Written by JP Arredondo

Who this is for: Organizations whose Sana workspace uses their own identity provider for sign-in, for example organizations moving from Sana Agents. If you access Sana through Workday, you sign in with Workday and don't need to set anything up.

Introduction

Single sign-on (SSO) lets your users sign in to Sana with the same account they use for your other company apps. Sana connects to your identity provider using OpenID Connect (OIDC).

Setting it up is shared between your IT team and Sana:

  1. Your Sana contact sends you the redirect URI for your workspace.

  2. Your IT team registers Sana as an app in your identity provider, following the steps in this article.

  3. Your IT team sends the app's details back to your Sana contact.

  4. Sana adds your identity provider to your workspace, and a sign-in button for it appears on your Sana sign-in page.

This article has step-by-step instructions for Microsoft Entra ID. For other identity providers, see Set up single sign-on (SSO) with Google Workspace, Set up single sign-on (SSO) with Okta and Set up single sign-on (SSO) with another OpenID Connect provider.

Note: Sana supports OpenID Connect only. SAML is not supported, so an XML metadata file or a signing certificate can't be used. If your organization used SAML with Sana Agents, you need to create a new OpenID Connect app.


Before you start

You need:

  • Admin access to Microsoft Entra ID, with permission to create app registrations.

  • The redirect URI for your Sana workspace, from your Sana contact. It is specific to your workspace and 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

Enter the redirect URI exactly as you receive it, with no trailing slash. A redirect URI that differs by a single character makes sign-in fail.

You need one app registration per Sana workspace.


Set up Microsoft Entra ID

Step 1: Create the app registration

In the Azure portal, go to Microsoft Entra ID → App registrations → New registration. Create the app here, not from Enterprise applications: the single sign-on option there sets up SAML, which Sana doesn't support.

On the Register an application screen:

Field

What to enter

Name

The name your users see on the Microsoft consent screen and in My Apps, for example Sana.

Supported account types

Single tenant only (in older versions of the portal: Accounts in this organizational directory only). Multi-tenant and personal Microsoft account options don't work with Sana.

Redirect URI

Platform Web, then the redirect URI from your Sana contact. The portal marks this field as optional, but Sana needs it.

Click Register.

Step 2: Check the authentication settings

Open Authentication on the new app registration. In the current portal it's called Authentication (Preview) and split into tabs; the settings are the same.

  • There should be one redirect URI with platform Web. If you didn't add it when registering, add it here with Add Redirect URI. Don't use Single-page application: sign-in fails with that platform type.

  • Leave implicit grant and hybrid flows unticked, the front-channel logout URL empty, and Allow public client flows turned off.

Step 3: Create a client secret

Go to Certificates & secrets → Client secrets → New client secret. Add a description and choose an expiry.

  • Copy the Value right away. Azure shows it in full only once.

  • The Secret ID next to it is not the secret. Sending the Secret ID instead of the Value is the most common reason sign-in fails, with error invalid_client.

  • Sign-in stops working when the secret expires (Azure allows at most 24 months). Note the expiry date and send your Sana contact a new secret before then.

  • Sana uses a client secret, not a certificate, so leave the Certificates and Federated credentials tabs empty.

Step 4: Add the email claim (required)

Go to Token configuration → Add optional claim, choose token type ID, and tick email. Tick given_name and family_name too, so users appear in Sana with their names instead of their email addresses. Click Add, and accept the Microsoft Graph email permission if you're asked.

Note: Without the email claim, users can sign in to Microsoft but Sana can't create their account. Entra ID fills the claim from the user's mail attribute, so users without an email address in Entra ID can't sign in to Sana.

Step 5: Grant permissions

Under API permissions, check that the delegated permissions openid, profile and email are listed. If your organization doesn't allow users to consent to apps themselves, click Grant admin consent for <your organization>, or the first sign-in fails with error AADSTS65001.

Step 6: Choose who can sign in

Registering the app also created an enterprise application with the same name. Open it from the Managed application in local directory link on the app's Overview page.

  • Under Properties, set Assignment required? to Yes to let only the users and groups you assign under Users and groups sign in. This is recommended. Anyone else is stopped by Microsoft with error AADSTS50105.

  • If you set it to No, anyone in your organization can sign in to your Sana workspace.

Conditional Access policies that apply to the app work as usual.

Step 7: Send the details to Sana

From the app registration's Overview page, send your Sana contact:

What to send

Where to find it

Directory (tenant) ID

Overview. Send the ID itself, not your domain name.

Application (client) ID

Overview. This is not the Object ID.

Client secret

The Value you copied in step 3.

Sign-in button name

The label your users will see on the Sana sign-in page, for example "Sign in with Microsoft".

Before you send them, check that Redirect URIs on the Overview page reads 1 web, 0 spa, 0 public client. If it doesn't, go back to step 2. You don't need the Object ID or anything from the Endpoints panel.

Your Sana contact will tell you how to share the client secret securely. Don't send it in a regular email or chat message.


After setup

  • A sign-in button with the name you chose appears on your workspace's Sana sign-in page. Your Sana contact gives you the sign-in URL for your workspace.

  • The first time each user signs in with SSO, Sana sends a confirmation link to their email address. They need to open it within 10 minutes to finish signing in.

  • If a user already has a Sana account with the same email address, confirming the link connects SSO to that account. Otherwise, a new account is created as a Member. Admin rights are assigned in Sana afterwards; they don't come from your identity provider.

  • To let users open Sana from Microsoft My Apps, ask your Sana contact for the app launch URL. Add it as the Home page URL under Branding & properties, and set Visible to users? to Yes in the enterprise application's Properties.

  • To replace a client secret without interrupting sign-in, create the new secret first, send it to your Sana contact, and delete the old one only after Sana confirms the switch.


Known limitations

  • No automatic user sync (SCIM). Users are created when they first sign in. Removing a user's access in Microsoft Entra ID stops them from signing in again, but doesn't deactivate their Sana account or end a Sana session they already have open.

  • No role mapping. Everyone who signs in through SSO starts as a Member, whatever their groups in your identity provider.

  • No email domain check. Sana doesn't check the email domain of people signing in through SSO, or whether their email address is verified. Anyone your identity provider lets through can join your workspace, so limit the app to the users who should have Sana, and be careful with guest and external accounts.

  • Sign-out is local. Signing out of Sana doesn't sign the user out of your identity provider, so their next sign-in may not ask for a password.

  • OpenID Connect only. SAML isn't supported, and client certificates can't be used instead of a client secret.


FAQ

Q: Can we use SAML?

A: No. Sana supports OpenID Connect only.

Q: Can we set up or change SSO ourselves in Sana?

A: No. Your IT team creates the app in your identity provider, and Sana adds it to your workspace. Contact your Sana contact for any change, such as a new client secret.

Q: Does Sana sync users and groups from our identity provider?

A: No. There is no SCIM sync. Users are created the first time they sign in, and everyone starts as a Member.

Q: What happens when a client secret expires?

A: Sign-in stops working for everyone using that identity provider. Send your Sana contact a new secret before the old one expires.

Did this answer your question?