Connect Microsoft Entra ID SSO
Connect your Microsoft Entra ID tenant as your organization's sign-in for Herd, from Settings, without waiting on Herd: register an app, test it on yourself, then turn it on.
Overview
Herd connects to Microsoft Entra ID over OpenID Connect. You set it up yourself in Settings → General → Access → Sign-in, in four steps:
Register the app in Entra.
Enter its credentials in Herd.
Test sign-in, on yourself.
Turn on SSO.
Nothing changes for your organization until step 4. If anything is wrong, your organization keeps signing in exactly as it does today.
Prerequisites
A Herd administrator account with permission to manage permissions (org.permissions).
In Microsoft Entra ID, a role that can register applications and grant admin consent (Cloud Application Administrator, Application Administrator or Global Administrator).
Your Directory (tenant) ID: Microsoft Entra admin center → Overview.
Step 1: Register the app in Entra
In Herd, open Settings → General → Access → Sign-in, choose Microsoft Entra ID and select Begin setup. Herd shows three values with copy buttons: the sign-in redirect URI, the front-channel logout URL and the Herd app URL. Keep the page open.
In the Microsoft Entra admin center:
Go to App registrations → New registration.
Name: Herd.
Supported account types: Accounts in this organizational directory only (Single tenant).
Redirect URI: platform Web, value: Herd's sign-in redirect URI (it ends in
/oauth2/idpresponse).Select Register.
Authentication: paste Herd's front-channel logout URL and save.
Branding & properties: paste the Herd app URL as the Home page URL, so the Herd tile in My Apps opens Herd.
Certificates & secrets → New client secret. Copy the secret's Value (not its Secret ID) right away; Entra shows it only once.
API permissions → Add a permission → Microsoft Graph → Delegated permissions: add openid, email and profile, then select Grant admin consent.
Token configuration → Add optional claim → ID: add email and xms_edov.
Entra's email attribute can be set to any address by your tenant's administrators, so Herd does not sign anyone in by it alone. It uses the email only when Entra marks it verified (
xms_edov, "email domain owner verified"), and the address must be on one of your organization's email domains. A sign-in without a verified email is not linked to anyone's Herd account; the user principal name is never used in its place. (Herd recordsxms_edovon the sign-in as its own attribute, apart from the account'semail_verified.)Go to Enterprise applications → Herd → Properties and set Assignment required? to Yes. Then, under Users and groups, assign the people and groups who may sign in to Herd, including yourself.
From the app registration's Overview, copy the Application (client) ID and the Directory (tenant) ID.
Back in Herd, select I've created the app.
Step 2: Enter its credentials
Issuer URL
https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0. Your <name>.onmicrosoft.com domain works in place of the tenant ID.
Client ID
The Application (client) ID.
Client secret
The secret's Value from step 1.
Scopes
Leave openid email profile.
Herd accepts only your own tenant's issuer. common, organizations and consumers are refused: they are multi-tenant, and would let any Microsoft account sign in.
Select Save and continue. Herd checks the issuer with Microsoft before saving anything.
Step 3: Test sign-in
Select Run test sign-in. A new tab signs you in through Entra, as yourself. Herd checks that Entra signed you in with your own email address, then shows the result in both tabs. Your organization's sign-in has not changed.
If the test fails:
Released no verified email address: add the optional email and xms_edov claims on Token configuration (step 1, item 6), then run the test again.
Not on one of your organization's email domains: Herd links sign-ins only on your organization's own domains. If the domain is yours, ask Herd support to add it.
Signed in as a different person: sign out of Microsoft in that browser, then sign in as yourself.
AADSTS50105 (user not assigned): assign yourself to the Herd enterprise application.
Step 4: Turn on SSO
Within an hour of a passing test, select Turn on SSO. From then on:
Everyone in your organization signs in to Herd through Microsoft Entra ID.
Sign-in security, MFA and Conditional Access included, is set in Entra, and Herd's own MFA setting is hidden.
Only users and groups assigned to the Herd enterprise application can sign in.
Who gets app access
Assigning someone to the Herd app lets them sign in. Whether that sign-in gives them the Herd app or only their own training depends on your access settings. See Who gets app access when they sign in. Usually every sign-in gets the app, as a learner who sees only their own training, or in your default group if you've set one (if that's Full Access, assign the Herd app only to people who should be admins). With the identity-provider switch on, the app role Entra sends decides, so give it only to people who should be admins. To let people who only take training reach it from the Herd tile in your app launcher, see Let People Reach Their Training from My Apps.
Send who gets the Herd app from Entra
To let Entra decide who gets the Herd app, add an app role to the Herd app and assign it to the people who should have it. Everyone with the role gets the app, as a learner or in your default group if you've set one; make admins by adding them to Full Access in Herd. Herd reads the role from the roles claim Entra puts in the ID token. For what Herd does with it, see Your identity provider decides.
In the Microsoft Entra admin center:
Go to App registrations → Herd → App roles → Create app role.
Display name: Herd app.
Allowed member types: Users/Groups.
Value:
herd-app.Description: anything you like, for example "Can use the Herd admin app".
Leave Do you want to enable this app role? ticked and select Apply.
Go to Enterprise applications → Herd → Users and groups. Select your admin group (or Add user/group to add it), choose Assign, and select the Herd app role. Assigning a group to a role needs Microsoft Entra ID P1 or P2; without it, assign the role to each person.
Make sure everyone else who signs in to Herd is assigned to the app, with the
learnerrole if Entra requires one (it does for new assignments once the app has a user-assignable role). Thelearnerrole is described below.
In Herd:
Open Settings → General → Access → Sign-in. Under Who your identity provider gives the Herd app, enter the claim name
rolesand the valueherd-app, then select Save. Herd shows App-access claim saved. This section appears once single sign-on is on.Sign out of Herd and sign in again through Entra, so your own sign-in carries the role.
On the same card, turn on Let the identity provider's app-access claim decide who joins the default group. Herd refuses if your own sign-in did not carry the role; see Turning it on.
Recommended: also create a second app role, Herd learner with value learner, and assign it to everyone else who signs in. When Entra sends a role for every person, someone whose Herd app role you remove loses the app at their next sign-in without depending on Entra leaving the claim out. Herd treats anything that is not herd-app as no app access.
People on another email domain
When Herd doesn't already know a person by their identity provider's id, it can only match them by email, and it links or creates their account only for an address on one of your organization's email domains. Herd support keeps that list for your organization: to add a domain (a contractor's company, an alias domain, a newly acquired company), contact Herd support. Until it is added, a person on that domain whom Herd doesn't already know is refused, and the sign-in page says:
Your identity provider signed you in, but your email's domain isn't set up for this organization in Herd. Ask your Herd admin to have it added, then sign in again.
The sign-in page never lists your organization's domains.
The domain list is not an access control: someone on another domain whom directory sync added, or who is already linked to your identity provider, still signs in. Control who can sign in at your identity provider.
Keep your user list current
SSO controls who can sign in. It never removes anyone from Herd. People you disable or delete in Entra, or remove from the Herd app, can no longer sign in, but they stay on Herd's Users list and keep receiving training until something tells Herd they left. Connect one of these:
Entra directory sync in Settings → Integrations → Microsoft Entra ID: Herd reads your Entra users and groups and removes the people Entra disabled. See Azure Active Directory user and group sync.
SCIM provisioning: Entra's provisioning service pushes each change to Herd. Create a token in Settings → General → SCIM provisioning and see SCIM Provisioning. On Okta, see Connect Okta SCIM provisioning instead.
Admin accounts that sign in with a Herd password
Herd never lets an identity provider take over a Herd admin account that signs in with a Herd password just because it sends the same email address.
You, the administrator running the setup, get through: your test sign-in proves which Microsoft Entra ID identity is yours, and your first Microsoft Entra ID sign-in after you turn SSO on (within 7 days of turning it on) moves your account.
Other admins who sign in with a password: once SSO is on, their first sign-in through it is refused, and the sign-in page says why and shows Sign in with your Herd password. They sign in that way, which takes them to the Single sign-on card, and choose Connect my account to SSO. That signs them in through your identity provider once, to prove which identity is theirs; their next sign-in through SSO, within 7 days, moves their account.
Accounts that are not admins follow the usual rules above.
Changing or turning off SSO
Test again re-runs the test against your live configuration without changing it.
Reconfigure stages new values (for example a rotated client secret). They are tested before they replace the live configuration.
Disable SSO returns everyone to Herd passwords. You need a Herd password yourself to do this.
If Herd set up your Entra SSO
Organizations whose Entra SSO Herd configured see it on the Single sign-on card as Microsoft Entra ID, Configured by Herd. Sign-in is unchanged. Test again and Reconfigure work as above: the tested copy takes over only when you turn it on, and the configuration Herd set up keeps working until then.
Turning the tested copy on moves everyone to a new Microsoft Entra ID identity, which Herd links to each person's account by the verified email address Entra releases. So Herd turns it on only after your test sign-in shows Entra releasing a verified email: add the optional email and xms_edov claims on Token configuration (step 1, item 6) before you test.
Last updated