Set up single sign-on with Microsoft Entra ID

Step 1

Prove your domain in Spoofhound

Do this first — the rest of the settings are not offered until it is done.

1. In the Spoofhound dashboard, go to Admin → Single Sign-On.
2. Under Domains this covers, type the domain your people’s email addresses use and press Add.
3. Publish the TXT record it shows you — the name is _spoofhound-sso.yourdomain.com and the value is a 24-character string.
4. Wait for DNS to propagate, then press Verify now.

Leave that record published. It is re-checked, and removing it stops sign-ins for the domain.

Step 2

Create the three groups in Entra

In the Microsoft Entra admin centre, go to Groups → All groups → New group. Create three, each with Group type: Security:

• SpoofhoundAdmins
• SpoofhoundAnalysers
• SpoofhoundViewers

Open each one and copy its Object ID — a UUID. That is what Spoofhound matches on, not the name, because a name can be changed by somebody who cannot change the id.

Put your own account in SpoofhoundAdmins now. You will need it in step 8.

Step 3

Register the application

Applications → App registrations → New registration.

• Name: Spoofhound SSO (only your own admins see this)
• Supported account types: Accounts in this organizational directory only
• Redirect URI: platform Web, and the address of the instance your account is on:

Use the one that matches the address bar when you are signed in to Spoofhound. Add more than one only if you have accounts on more than one instance.

Press Register, then from the Overview page copy the Application (client) ID and the Directory (tenant) ID.

Step 4

Give the app a credential

The application needs one credential so Spoofhound can authenticate as it. There are three ways to provide one and you only need one of them. The first is the easiest by some distance, and the one to use unless you have a reason not to.

# 1. Private key — unencrypted PKCS#8 (this is the file you paste into Spoofhound)
openssl genpkey -algorithm RSA -out spoofhound-key.pem -pkeyopt rsa_keygen_bits:2048

# 2. Self-signed public certificate, valid two years (this is the file you upload to Entra)
openssl req -new -x509 -key spoofhound-key.pem -out spoofhound.crt -days 730 -subj "/CN=Spoofhound"

Step 5

Put the groups into the login token

In the application, Token configuration → Add groups claim.

• Select Groups assigned to the application.
• Under ID, choose Group ID.
• Press Add.

Choose “assigned to the application” rather than “Security groups” on purpose. If somebody is in more than about two hundred groups, Entra stops listing them in the token and sends a link instead — and that person would look to us like somebody in no groups, and be refused. Sending only the groups assigned to this application avoids that entirely.

Step 6

Assign the groups to the application

This is the step people miss. Step 5 says “send the groups assigned to this application”. Until you actually assign them here, that is none of them — the token arrives with no groups in it and everybody is refused.

Applications → Enterprise applications, open Spoofhound, then Users and groups → Add user/group. Add the three groups you created in step 2.

While you are there: under Properties, setting Assignment required to Yes means only people in those groups can even reach the sign-in. Worth doing.

Step 7

Put it all into the Spoofhound dashboard

Back in the Spoofhound dashboard — not the app registration in Entra — under Admin → Single Sign-On:

If you used a certificate: paste both the Certificate and the Private key, or neither — one without the other is no use. Leave Client secret blank. You do not enter a thumbprint: Spoofhound works it out from the certificate and shows it back, so you can check it matches the one Entra lists.

You can supply a secret or a certificate, not both — whichever credential you supply last is the one that gets used. One slip to avoid: pasting the private key into the Certificate box. Spoofhound refuses it, but it is an easy mistake to make in a hurry.

Save. Nothing has changed yet for anybody signing in: single sign-on is not switched on by saving this form.

Step 8

Sign in, which switches it on

Sign out, then sign in with your work address. You are sent to Microsoft, you authenticate as normal, and you come back signed in to Spoofhound with the role from your group — Admin, Analyser or Viewer.

That first successful sign-in by an admin is what switches single sign-on on. From that moment everyone at your proved domains signs in through Entra, and passwords, passkeys and authenticator apps stop working for this tenant — apart from anybody you name as an exception (step 9).

It works this way round deliberately. Saving the form could not switch it on, because one wrong value there would lock out everybody at your business including whoever typed it. That one sign-in proves the issuer, the credential and — because it has to be an admin — the admin group mapping all work, which is what says somebody can still run this tenant afterwards.

You land on the Enforcement panel rather than the dashboard, saying it has happened. Every other admin on the tenant is emailed at the same time, so nobody finds out by having their own password refused.

To switch it off again, use your recovery credential.

Step 9

Anybody who cannot use Entra

Some people have no account in your directory at all — a contractor, or somebody at another company you have invited to read reports. They cannot sign in through Entra, so they need naming as an exception: they keep their password, passkey or authenticator.

Under Admin → Single Sign-On → Enforcement, choose the member and say why. Everybody excused is listed there with who excused them and when, so you can always see exactly who is not coming through Entra. That visibility is the point: an exception added for a fortnight is easy to forget about for two years.

Your own people do not need inviting

Once single sign-on is on, put somebody in one of your three groups in Entra and they appear on the member list the first time they sign in, with the role that group gives them. There is nothing to invite and no account to create. Spoofhound refuses an invite to a domain you have proved, and says so — an invite would have them choose a password that then would not work.

Inviting somebody at any other domain still works, and accepting the invite excuses them automatically, because otherwise the invite would mean nothing. The invite page says so before you send it, and they appear in the exceptions list like everybody else.

Roles come from Entra now

For anybody signing in through Entra the member list shows SSO/OIDC-managed instead of a role, and there is no role to set: it is read from their groups every time they sign in. Move them between groups in Entra instead. Exceptions still have a role you set in Spoofhound, because nothing re-reads theirs.

When something goes wrong

Somebody is refused with “you are not in any of the groups”

The message in full: “You are not in any of the groups your organisation uses to grant Spoofhound access. Ask an administrator to add you to one.” Their token carried none of the three groups. Add them to one — and if nobody can sign in this way, it is almost certainly step 6: the groups are not assigned to the enterprise application.

Sign-in stopped working one morning, for everybody

Almost always the client secret or certificate expiring. Create a new one (step 4) and paste it in. If single sign-on is switched on, nobody can sign in to do that — use your recovery credential first, which puts passwords and passkeys back.

Entra ID is down

Go to /sso/recover on your Spoofhound dashboard — it works without signing in, which is the point of it. Paste your recovery credential and passwords, passkeys and authenticator apps work again for everyone. It does not sign you in: you still sign in as yourself afterwards. It works once, and everybody on the tenant is emailed the moment it is used. Issue a replacement once you are back in.

Somebody says their password has stopped working

Expected, if single sign-on is on: they sign in through Entra now. The message says so and tells them their password is not the problem. If they genuinely cannot use Entra — a contractor, say — name them as an exception (step 9).

An invite was refused

You invited an address at a domain you have proved. Those people arrive by signing in; add them to one of your three groups in Entra instead and they appear on the first sign-in. Invites still work for anybody outside your directory.

You cannot change somebody’s role

The member list shows SSO/OIDC-managed rather than a role for anybody signing in through Entra, and there is no control to change it. Their role is read from their groups at every sign-in, so anything set in Spoofhound would be overwritten. Move them between groups in Entra.