Students keep signing in with Microsoft. Entra checks the password, then hands the browser to HallKey for the second factor through an external authentication method. HallKey answers with a signed assertion and Entra treats multifactor authentication as satisfied.

Before you begin

Microsoft Entra ID P1 or P2 for the users in scope. Conditional Access requires it.
An administrator who can register applications, grant admin consent and edit authentication methods and Conditional Access, such as a Global Administrator.
A HallKey administrator who can add applications.
A pilot security group, for example HallKey MFA Users, and an administrator account outside it.

Work through the steps in order. Entra reads HallKey's discovery document while the external method is being created, and HallKey only publishes it once both Entra identifiers are saved.

Microsoft
School passwordHallKey
Grid card or app codeMicrosoft 365
Application access

1. Add the application in HallKey

In the HallKey console, go to Applications → New application, choose Microsoft 365 and select Create. Open Register in Entra on the new application's page: you will copy the Authorize endpoint, Discovery URL and Client ID from here.

HallKey new application form with Microsoft 365 selected

HallKey Register in Entra panel showing the discovery URL, client ID, authorize endpoint and issuer

2. Register an application in Entra

In the Microsoft Entra admin center, go to Entra ID → App registrations and select New registration. Use App registrations, not Enterprise applications.
Name it, for example HallKey MFA, and keep Single tenant only.
Under Redirect URI, choose Web and paste HallKey's Authorize endpoint.
Select Register.

Entra Register an application form with name HallKey MFA, single tenant and a Web redirect URI

The registration's Overview shows the Application (client) ID and Directory (tenant) ID. Keep this page open.

Entra app registration overview showing the application ID and directory ID

3. Enable ID tokens

Open Authentication → Settings, tick ID tokens (used for implicit and hybrid flows) and select Save. Leave Access tokens unticked and the front-channel logout URL empty.

Entra authentication settings with ID tokens ticked and saved

4. Add permissions and grant admin consent

Open API permissions → Add a permission → Microsoft Graph → Delegated permissions.
Under OpenId permissions, tick openid and profile, then select Add permissions.
Select Grant admin consent for your organization and confirm with Yes.

Both steps are required. Without the two permissions, the external method's consent fails with only Failed to request permission. Without admin consent, sign-in fails with AADSTS900491: Service principal not found.

5. Enter the Entra identifiers in HallKey

In HallKey's Entra registration panel, paste the Directory (tenant) ID and Application (client) ID from the registration's overview and select Set up. HallKey then starts publishing the discovery document Entra reads in the next step.

HallKey Entra registration panel with the directory ID and application ID entered

6. Add HallKey as an external method

In Entra, go to Entra ID → Authentication methods → Policies and select Add external MFA.
Enter a Name such as HallKey. The name cannot be changed later.
Paste HallKey's Client ID, HallKey's Discovery URL as the Discovery Endpoint, and the registration's Application (client) ID as the App ID. Request admin consent should show Admin consent granted.
Turn Enable on, then under Include choose Add target → Select targets and pick the pilot group.
Select Save.

Entra Add external multifactor authentication form with name, client ID, discovery endpoint and app ID filled in and admin consent granted

External method enabled and targeted at the HallKey MFA Users group

HallKey now appears under External in the authentication methods list.

Entra authentication methods list showing HallKey under External, targeted at one group and enabled

7. Require MFA with Conditional Access

Entra only calls an external method when a Conditional Access policy requires multifactor authentication. Without one, sign-ins succeed without HallKey, which looks like the integration being ignored.

Go to Conditional Access → Policies and create a policy, or review an existing one.
Under Users, include the pilot group.
Under Target resources, choose the applications to protect, for example All resources.
Under Grant, choose Grant access and tick Require multifactor authentication. Do not use Require authentication strength: authentication strengths, including the built-in MFA strength, are not satisfied by external methods.
Start with Report-only if you want to check the policy's impact first, then turn it On.

Conditional Access policy Require MFA with users set to the HallKey MFA Users group

Conditional Access Grant pane with Require multifactor authentication ticked and Require authentication strength unticked

8. Register HallKey for each user

Enabling and targeting the method is not enough: each user also needs it registered. An administrator can do this for a test user before the first sign-in, so any failure afterwards is clearly the integration.

Go to Users, open the user and select Authentication methods → Add authentication method.
Choose External MFA, tick HallKey and select Add.

Users can also add it themselves from Security info → Add sign-in method → External Auth methods. A user who has never registered it is sent to register security info instead, and may loop between Microsoft sign-in pages.

Entra Add authentication method for a user with External MFA chosen and HallKey ticked

User authentication methods showing External MFA HallKey as a usable method

9. Check password reset registration

External methods cannot be used for self-service password reset. If password reset is enabled for HallKey users and Require users to register when signing in? is Yes, Entra interrupts them after HallKey with Let's keep your account secure and asks them to set up Microsoft Authenticator or another recovery method. Users can select Skip setup, but they are asked again at each sign-in.

Entra Let's keep your account secure prompt shown to the user after HallKey

Entra Install Microsoft Authenticator prompt with a Skip setup option

To stop the prompt, go to Entra ID → Password reset and either:

under Registration, set Require users to register when signing in? to No, or
under Properties, change Self service password reset enabled from All to Selected and choose a group that does not contain HallKey users.

Entra Password reset Registration with Require users to register when signing in set to Yes

Entra Password reset Properties with self service password reset enabled for All

The Authentication methods → Registration campaign nudge is a different prompt. Microsoft only shows it after SMS or voice-call MFA, so it does not appear after HallKey.

10. Create the user and issue a passcode grid

Each person who signs in needs a HallKey user and a credential. HallKey matches the sign-in by username: Entra sends john.doe@school.example, and HallKey looks for a user named john.doe@school.example, then john.doe. Make the username the part of the address before the @, or the whole address.

In HallKey, go to Users → New user.
Enter the Username, and optionally a Display name and the Email enrollment messages go to. Select Create.

HallKey New user form with username john.doe, display name John Doe and an email address

HallKey Users list showing john.doe as Active

Open the user and, under Passcode Grid, select Issue passcode grid. Choose the difficulty and expiry, then select Issue passcode grid. The preview shows a sample, not the user's grid.

HallKey Issue passcode grid dialog with difficulty, expiry and a sample card preview

HallKey user page showing the issued passcode grid as Pending with its serial number

Select Print card, choose the format, paper and language, and select Print. HallKey downloads a PDF of the card to print and hand to the student.

HallKey Print dialog with print format, paper and language options

Printed HallKey passcode grid card with five columns A to E, five rows, the serial number and instructions — Treat a printed card like a key: anyone holding it can answer the challenge. Issue a replacement if it is lost, which stops the old card working.

Test the sign-in

In a private browser window, go to myapps.microsoft.com and sign in as the test user with their Microsoft password.

Microsoft sign-in with john.doe@cyphercor-labs.com

Microsoft says it will redirect to HallKey. Select Continue.

Microsoft Verification Required page saying the user will be redirected to HallKey

HallKey shows the school's name and asks for three cells from the card. Columns are letters and rows are numbers, so C5 is column C, row 5.

HallKey challenge asking for cells C5, E4 and D3

HallKey challenge with three cells filled in

The browser returns to Microsoft and the user reaches My Apps. If Entra asks the user to set up another method first, see step 9.

Microsoft My Apps dashboard signed in as John Doe

In HallKey, Authentications records the approved sign-in.

HallKey Authentications list showing approved passcode grid sign-ins for john.doe

Then check:

Scenario	Expected result
Wrong code	HallKey refuses the second factor.
User outside the pilot group	Signs in as before, without HallKey.
Replaced card	HallKey refuses the old card.
Sign-in after rollback	The previous MFA path is restored.

Do not describe grid cards as phishing-resistant.

Troubleshooting

Symptom	Check
Failed to request permission when adding the external method	The registration is missing the delegated openid and profile permissions.
`AADSTS900491: Service principal not found`	Admin consent was not granted on the registration.
`IDSTS50161: Failed to validate authorization url`	The registration's redirect URI does not exactly match HallKey's authorize endpoint.
Entra cannot validate the provider when saving the method	HallKey's Entra registration panel was not saved yet, so the discovery URL is not published.
Users are asked to set up Microsoft Authenticator after HallKey	Password reset registration is required for them. See step 9.
Sign-in succeeds without HallKey	No Conditional Access policy requires MFA for that user, or the user is not in the method's target group.
Every sign-in under the policy is refused	The policy uses an authentication strength instead of Require multifactor authentication.
The browser loops between Microsoft sign-in pages	The user has not registered the HallKey method.

Roll back

Set the Conditional Access policy to Off or Report-only, or remove the pilot group from it, and turn the HallKey external method off. Check that a pilot user regains their previous MFA path and an unrelated user is unaffected.