Skip to main content

Set up Microsoft Entra ID (Azure AD) SSO

This guide walks a Microsoft Entra ID administrator through registering Oho as an application so your team can sign in with their Microsoft work accounts. It's the provider-specific companion to Set up SSO — read that first for how SSO configuration works in Oho and what changes for your team.

Who this is for

You'll need administrator access to your Microsoft Entra admin centre (formerly Azure Active Directory) with permission to register applications. Oho supports both OIDC and SAML with Entra; this guide leads with OIDC, the simpler option, and notes the SAML differences where they matter.

Step 1: Register the app​

  1. In the Microsoft Entra admin centre, go to Identity → Applications → App registrations and click New registration.
  2. Name it something recognisable, for example Oho.
  3. Under Supported account types, choose Accounts in this organizational directory only unless you specifically need guests from other tenants.
  4. Under Redirect URI, choose Web and enter the callback URL shown on Oho's SSO settings screen (Settings → Developer → Single Sign-On) — your Oho URL followed by /callback/oidc.
  5. Click Register.

Expected outcome: an Oho app registration exists, and you can see its Application (client) ID and Directory (tenant) ID on the Overview page.

Step 2: Create a client secret​

  1. In the app registration, go to Certificates & secrets → Client secrets and click New client secret.
  2. Give it a description and an expiry that suits your rotation policy, then click Add.
  3. Copy the secret Value straight away — Entra shows it only once.
Copy the Value, not the Secret ID, and copy it now

Entra displays the secret's Value only at creation. If you navigate away without copying it, you'll have to create a new one. The Secret ID is not the secret — Oho needs the Value.

Expected outcome: you have the client secret Value copied, along with an expiry date noted for future rotation.

Step 3: Set permissions and (optionally) group claims​

  1. Under API permissions, confirm the app has the delegated Microsoft Graph permissions openid, profile, and email (these are usually present by default). Grant admin consent if your tenant requires it.
  2. To let Oho place people into roles automatically from their Entra groups, go to Token configuration → Add groups claim, select the group types to include (for example, Security groups), and save. Entra will then include a groups claim in the token.

To use this, turn on Sync group membership in Oho's SSO screen and set the Groups Claim to groups — see Mapping groups to roles. Note that Entra emits group object IDs by default rather than names, so you'll be mapping those IDs; configure group names in the claim instead if your tenant supports it.

Expected outcome: the app has openid/profile/email permissions and, if you're using it, a groups claim.

Step 4: Enter the details in Oho​

Gather:

  • Application (client) ID — from the app's Overview page
  • Client secret Value — from Step 2
  • Discovery URI — your tenant's OIDC document, https://login.microsoftonline.com/<your-tenant-id>/v2.0/.well-known/openid-configuration, using the Directory (tenant) ID from the Overview page

In Oho, go to Settings → Developer → Single Sign-On, turn on Enable Single Sign-On, choose OpenID Connect, and paste in the client ID, secret Value, and discovery URI. For the Username Claim, Entra needs the full claim URI http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress (Oho's SSO screen notes this next to the field). Click Test connection, then Save.

Technical detail: doing this with SAML instead

Rather than an app registration, create an Enterprise application → Set up single sign on → SAML. Set the Reply URL (ACS URL) and Identifier (Entity ID) to the values shown on Oho's SSO screen (the ACS URL is your Oho URL followed by /callback/saml; the entity ID defaults to urn:oho:datahub). Map user.mail as the name identifier. Then, in Oho, pick SAML 2.0 and enter your App Federation Metadata URL in place of the client ID, secret, and discovery URI.

The client secret is a credential

Anyone holding the secret can impersonate the Oho app against your directory. Paste it straight into Oho's SSO screen rather than emailing or ticketing it, and rotate it in Entra if it's ever exposed — or before it expires, to avoid a sign-in outage.

Expected outcome: SSO is enabled in Oho with your Entra details, and the connection test passes.

Step 5: Test the first sign-in​

After the connection test passes and you've saved:

  1. Go to your Oho URL in a private/incognito window.
  2. You're redirected to Microsoft — sign in as a user in your directory.
  3. You're returned to Oho, signed in.

Expected outcome: a user in your directory can sign in to Oho end to end.

Common questions​

Sign-in fails with a redirect-mismatch error. The Redirect URI on the app registration doesn't exactly match the callback URL on Oho's SSO screen. Re-check it against the value shown there, including https:// and any trailing path.

Admin consent required. Some tenants block apps until an administrator grants consent. Grant admin consent for the openid/profile/email permissions under API permissions.

Sign-in suddenly stops working weeks later. Check whether the client secret has expired under Certificates & secrets. Create a new secret, paste the new Value into Oho's SSO screen, then remove the old one.