Skip to main content
Version: 11.5.0

Console Sign-In With Microsoft Entra ID

This page connects the HYPR AgentPass™ console to Microsoft Entra ID, so your team signs in with their Entra ID accounts. It applies the general steps in Signing In to the Console to Entra ID.

You need:

  • Permission to register applications in your Microsoft Entra ID tenant
  • The recovery administrator credentials, to sign in to the console while SSO is off. See Recovery Administrator
Map an Admin value first

A new tenant has no role mappings, so anyone who signs in with SSO before you map a value to the Admin role gets the default role, Supervisor. Map the value before you turn on SSO. If you are already locked out of Settings, see Recover Access After SSO.

Register AgentPass in Entra ID​

  1. Copy the redirect URI from the console. Open Settings → Gateway settings, click the Authentication tab, and find the Redirect URI under Console SSO (OIDC). It has the form https://<your-gateway-host>/q/oidc/callback.
  2. In the Entra ID portal, go to Entra ID → App registrations → New registration.
  3. Name the app, for example HYPR AgentPass.
  4. For Supported account types, choose Accounts in this organizational directory only.
  5. Under Redirect URI, choose the Web platform, and paste the redirect URI from the console.
  6. Click Register.
  7. On the app's Overview page, copy the Directory (tenant) ID and the Application (client) ID.
The app's Authentication page in Entra ID, with the gateway's redirect URI registered for the Web platform

Add the Email Claim​

AgentPass identifies the person signing in by the console's Principal claim, and sends their email to the address in its Email claim. Both are email until you change them. Entra ID adds the email claim to the ID token only when you ask for it, so add it even if you choose a different principal claim later.

  1. In the app, go to Token configuration and click Add optional claim.
  2. For Token type, choose ID.
  3. Select email, and click Add.
The Add optional claim panel in Entra ID, with the ID token type and the email claim selected

Create a Client Secret​

  1. In the app, go to Certificates & secrets → Client secrets → New client secret.
  2. Enter a description, choose an expiry, and click Add.
  3. Copy the secret's Value. Entra ID shows it only once.
The Client secrets tab in Entra ID, listing the new secret with its value masked

The secret stops working when it expires. Before then, create a new one in Entra ID, and replace it in the console.

Connect the Console​

  1. In the console, open Settings → Gateway settings, click the Authentication tab, and find Console SSO (OIDC).
  2. In Issuer / auth-server URL, enter https://login.microsoftonline.com/<directory-tenant-id>.
  3. Click Fetch from well-known endpoints URL. AgentPass fills in the Entra ID endpoints.
  4. In Client ID, enter the application (client) ID.
  5. In Client secret, paste the secret value, and click Save secret.
  6. Check the claims. Email claim email and Display name claims name match Entra ID. For Principal claim, choose an identifier that stays the same for each person, such as sub, before your team starts signing in. See Connect the Console to Your Identity Provider.
  7. Click Save settings.
  8. Set Role claim to the Entra ID claim that carries your administrators' group or role, and map its value to the Admin role. See Connect the Console to Your Identity Provider.
  9. Turn on Enable SSO.

The sign-in page now offers Sign in with SSO. Sign in with an Entra ID account to confirm the connection before your team uses it. The recovery administrator stays available if Entra ID is unreachable.

The gateway sign-in page, offering single sign-on above the recovery administrator form

Next Steps​