HYPR Documentation
HYPR User GuidePostman APILegacy WFALegacy SDK

Entra/Azure AD: HYPR Enterprise Passkey

Control Center Standard: Integrations

HYPR Enterprise Passkey (a.k.a. the FIDO2 Mobile Authenticator pattern) enables your HYPR Mobile App-enabled device to act as a FIDO2 security key when authenticating through Microsoft Entra/Azure AD.

What You’ll Need

  • Make sure you have the Entra/Azure tenant available and an account that exists on the \*.onmicrosoft.com domain with Global Admin Access
  • You should have an Intune account on the \*.onmicrosoft.com domain with Global Admin Access with Intune licenses
  • Entra/Azure domain-joined or hybrid-joined VMs or physical laptops with which to test
  • Currently the workstation/VM OS must be Windows, as macOS is not yet supported

Setting Up the Entra/Azure AD Tenant

Register Application

  1. From the Home screen, select Azure Active Directory > App registrations > New registration.
  1. Enter the application name: HYPRAuthApp.
    Select Accounts in this organizational directory only.
    Click Register when done.
  1. Save the clientId and tenantId. You will need these later for PowerShell and HYPR's UX configuration.

Grant Application Required API Permissions

  1. From the home screen, select App registrations and select the app you just made.
  1. While that app is selected, click API permissions. You will see that by default this application already has Microsoft Graph’s User.Read. This is not required, so remove it by clicking ... next to the entitlement and selecting Remove Permission. Click Yes during the confirmation prompt.
  1. Select API permissions, then Add a permission.
  1. Select Microsoft Graph.
  1. Select Delegated permissions.

    📘

    Delegated by Default

    Sometimes Entra/Azure will not display the option for Delegated or Application permissions, and will immediately assume Delegated as the choice. As no Application permissions are required, this works in your favor. However, after you grant Admin Consent later in the process, you will be able to confirm/see which type of permission they are.

  1. Add the permissions Directory.AccessAsUser.All and UserAuthenticationMethod.ReadWrite.All.
  1. Click Add Permissions when done.
  2. You must now Grant admin consent for the permissions to take effect.

Create Client Secret

  1. In the Application menu, select Certificates & secrets.
  1. Click New client secret.
  1. Enter a Description and an Expires date. Click Add when finished.
  1. HYPR will require the value of the secret during the integration flow. Save the value of the secret during this step, as it is not visible after. See the image below for an example.

Create Service Account

  1. From the Home page, Click Azure Active Directory, then Users.
  1. Click New user.

  1. Click Create user.

  2. In the User name area, type hyprserviceaccount.

  3. In the Name area, type HYPR Service Account.

  4. Click Let me create the password, then set and save the password.

  1. Next we must assign roles to the service account. Click Assigned roles.

  1. Click Add Assignments.

  2. Search for and add the following roles:

    • Directory Writers
      Allows the necessary group creation/update and also handles getting the user data for syncing entries to HYPR; needed throughout the entire lifecycle of the HYPR-Entra/Azure integration
    • Privileged Authentication Administrator
      Allows HYPR to manage the HYPR Enterprise Passkey on Entra/Azure; will be able to delete it when removed via phone or CC, and to have accurate data on the HYPR User Management list in the event it is deleted directly in Entra/Azure

  3. Click Add when done.

📘

Expect the Unexpected

This is the area in which Entra/Azure is very slow to replicate the changes. The Entra/Azure administrator may need to refresh the page many times for all to show up. Sometimes, they may need to add it twice. This is expected behavior.

📘

Service Account

At this time, the prospect must open up an incognito browser and log into portal.azure.com, as this service account. This is required to set the permanent password of the account.

📘

One Condition

If during this login, the account gets prompted for MFA, it means that a Conditional Access Policy must be updated to exclude the hyprserviceaccount.

Enable Security Keys in the Entra/Azure Tenant

  1. Login to portal.azure.com as a global admin account.
  2. Navigate to Entra/Azure Active Directory > Security > Authentication methods. Click FIDO2 security key.
  1. Here you can enable security keys and define allowed users. Include All users and leave the registration as Optional.
  1. On the Configure tab, make sure the settings are as depicted below. This is the only configuration we will support at this time.

👍

Enforced Attestation

Microsoft uses the Enforce attestation feature to ensure the FIDO2 authenticator is certified by the FIDO Alliance and approved by Microsoft's team. HYPR's AAGUID was added as an approved FIDO2 Authenticator on March 2023. HYPR supports this setting as either True or False.

Enable Security Keys in Intune

Once security keys are enabled in Entra/Azure, you must set a policy in Intune (i.e., Endpoint Manger) which will allow for security key login on Windows OS. Follow Microsoft’s instructions on setting up Intune policies for security key-enabled logins.

Setting Up the HYPR Tenant

When up and running, be sure to enable these Feature Flags:

  • AZURE_IDP_INTEGRATION
  • AZURE_NATIVE_LOGIN

To install a new Enterprise Passkeys integration in Control Center:

  1. On a new tenant, navigate to Integrations > Add New Integrations > Azure AD.

  2. You will be prompted to select your login experience. For the FIDO2 Mobile Authenticator, select Native Azure Login Experience, and click Next.

  1. You are presented a form which contains the HYPR Application Name and all of the Entra/Azure-related data needed for HYPR to connect to the Entra/Azure tenant. These are the items created/captured above; complete the fields as follows:
    • Application Name: Only alphanumeric, spaces, dash, underscores, or trailing - or _ are allowed; this is the same validation rule for all HYPR RP Application names (rpAppId); the namespace is limited to 23 characters
    • Client ID: The ID of the client/application in Entra/Azure AD
    • Tenant ID: The ID of the tenant
    • Client Secret: The secret associated with the client/application
    • Service Account Username: The user account with permissions which allow API calls
    • Service Account Password: The Service Account password
      When you are finished, click Add Integration; if Add Integration is successful, it confirms all of the parameters provided were validated and HYPR can now connect to Entra/Azure
  1. You will be presented a popup box. Click Maybe Later.

📘

HYPR Groups in Entra/AzureAD

When a new Enterprise Passkey integration is successfully created, HYPR automatically creates three groups in Entra/AzureAD. You do not need to take any action to maintain these, but may wish to apply policies specific to the HYPR Enterprise Passkey. They correspond to the different phases of pairing an Enterprise Passkey:

  • HYPR Group (Eligible for Pairing) - Users who have only been invited
  • HYPR Group (Client Paired with HYPR) - Users paired with HYPR authentication (but not Entra/Azure)
  • HYPR Group (Client Paired with Azure) - Users with Enterprise Passkey authentication

  1. With a new application in HYPR, you must update these two Feature Flags for this specific application. Do not set these flags at the global level.

    • FIDO2_MOBILE_AUTHENTICATOR
    • RP_APP_WORKSTATION_ENABLED

  2. CC takes you to the Integration User Management page.

  1. Select the Integrations Settings tab. You will see a brief description of the Native Azure Login Experience. Note it is DISABLED. When DISABLED, the expectation is the end-user can pair with HYPR using a QR code, but cannot register or authenticate to Entra/Azure.
  1. Click Enable and a confirmation appears.
  1. Let the confetti fly, then click Close.

Configure and Download the Desktop Client

  1. Navigate to Login Settings. Here you can restrict domains and download the HYPR Passwordless client. Installation Guides and Access Control are currently being built.
  1. To accept any domain name, leave the toggle off for Restrict Domains. To limit acceptable domains, toggle the switch to the On position. The dialog expands.
    • Click +Add Domain and type the domain name (without https://) in the resulting field. Press Tab or Enter to add another
    • To remove a domain from the list, click the x next to it
    • Click Save when you are finished adding accepted domains; a confirmation message appears: "Restrict Domains saved successfully"
  1. Select Download Desktop Client and a confirmation popup displays.
  2. If you are unsure whether or not you should be downloading the HYPR Passwordless client in your environment, click Back and contact your support. Otherwise, click Download Now, and your browser will download a .zip archive containing the client installation file and a hypr.json file.
  1. Unpack the archive. It contains two files:
  2. Install the HYPR Passwordless client on an Entra/Azure domain-joined workstation by double-clicking WorkforceAccess-8.3.0_x64.msi. Complete the instructions in Installing on Windows.

Pairing a HYPR Enterprise Passkey

🚧

Single Access

Once enabled in Passwordless client, HYPR strongly recommends against adding other passkeys or login methods for this particular integration type until future releases of HYPR.

Pairing a workstation to a HYPR Enterprise Passkey will add the user to an Entra/Azure group (HYPR Group (Client Paired with HYPR)) that indicates they still need to pair their passkey with Entra/Azure. Administrators may wish to use this group for policy changes or email reminders to complete pairing. To help users through the Azure pairing afterward, notifications will show up in the HYPR Mobile App and HYPR Passwordless Device Manager screens with instructions and links.

Pairing with HYPR on a Domain-joined Workstation

🚧

Do This First

Change the CC UX to Advanced and navigate to the rpApp you created, then Workstation Settings. Disable the following:

  • Enable Security Key
  • Enable Offline Mode
  • Recovery Mode

You will not need these settings. If they remain in their default state, you will see a security key option when you pair with HYPR (which will not work) and the Audit trail will report failures regarding the other two settings. Make sure to Save at the bottom of the page before continuing.

  1. Login to Windows as an Entra/Azure cloud-only account (i.e.,carol.shaw@highlands_azure.com).
  2. Launch the HYPR Passwordless client.
  3. Click Start Pairing.
  1. The HYPR Passwordless client reminds you to open Microsoft Azure AD and pair your phone as a security key after pairing with HYPR. Click Continue.
  1. The HYPR Passwordless client presents a QR code. Using a device with the HYPR Mobile App installed and ready to scan a QR code, click Begin Pairing.
  1. Scan the QR code on the screen. You will be prompted to authenticate on your device.
  1. Once you are paired successfully, click Continue.
  1. Choose the method by which you will connect this machine to the HYPR Mobile App device.
  1. Verify your connection (see Pairing Using Windows Bluetooth) is paired and the HYPR Mobile App is open. The web connection confirmation dialog remains unchanged, verifying that you are connected to the same wireless network as the workstation. This example uses the Bluetooth connection confirmation dialog.
  1. A prompt appears to remind you to continue the process in Azure. Click Continue in AD to open https://mysignins.microsoft.com/security-info (see Pairing with Azure, below) licking View More Instructions opens this article).
  1. HYPR Passwordless client returns to the main screen , now displaying your paired device. The device’s HYPR Mobile App menu now includes a section for My Security Keys. Open it. Here you will see the same Azure cloud-only account with which you logged into Windows.
  1. The warning icon next to it indicates the user has not yet completed the pairing. Until pairing is completed, a Pairing incomplete warning will display in the HYPR Passwordless client for the mobile device, and the account shown in the HYPR Mobile App will bear a Pairing incomplete icon. The indicates the user is Paired with HYPR but not yet Paired with Azure. Clicking the red warning icon will re-open the Phone pairing almost complete! dialog.

📘

Cache Returns

HYPR Passwordless client may not display a completed pairing right away. It may be necessary to close and restart the HYPR Passwordless client for the warnings to disappear.

  1. On the HYPR Mobile App, tap the arrow next to the userId for instructions on how to finish the pairing.

The user will now appear in the integration under User Management's Paired with HYPR tab. Continue to Pairing with Azure to complete your passkey registration.

See Integration User Management in the main Integrations article for how to navigate User Management.

Pairing With HYPR on a Hybrid Azure/Entra Workstation

  1. Login to Windows as an Azure cloud-only account (i.e.,carol.shaw@highlands_azure.com).
  2. Launch the HYPR Passwordless client.
  3. Click Start Pairing.
  1. The HYPR Passwordless client reminds you to open Microsoft Azure AD and pair your phone as a security key after pairing with HYPR. Click Continue.
  1. If your workstation has FIDO keys enabled, you will be prompted to Select Your Device to Continue. Choose Smartphone. Otherwise, proceed to the next step.
  1. The HYPR Passwordless client presents a QR code. Using a device with the HYPR Mobile App installed and ready to scan a QR code, click Begin Pairing.
  1. Scan the QR code on the screen. You will be prompted to authenticate on your device.
  1. You are Successfully paired. Click Maybe Later if you want to complete pairing at another time. Clicking Maybe Later will return you to the HYPR Passwordless client home dialog. To complete the pairing using Entra/Azure, click Continue.
  1. Choose the method by which you will connect this machine to the HYPR Mobile App device.
  1. Verify your connection (see Pairing Using Windows Bluetooth) is paired and the HYPR Mobile App is open. The web connection confirmation dialog remains unchanged, verifying that you are connected to the same wireless network as the workstation. This example uses the Bluetooth connection confirmation dialog.
  1. A prompt appears to remind you to continue the process in Azure. Click Continue in AD to open https://mysignins.microsoft.com/security-info (see Pairing with Azure, below) licking View More Instructions opens this article).
  1. HYPR Passwordless client returns to the main screen , now displaying your paired device. The device’s HYPR Mobile App menu now includes a section for My Security Keys. Open it. Here you will see the same Azure cloud-only account with which you logged into Windows.
  1. The warning icon next to it indicates the user has not yet completed the pairing. Until pairing is completed, a Pairing incomplete warning will display in the HYPR Passwordless client for the mobile device, and the account shown in the HYPR Mobile App will bear a Pairing incomplete icon. The indicates the user is Paired with HYPR but not yet Paired with Azure. Clicking the red warning icon will re-open the Phone pairing almost complete! dialog.

📘

Cache Returns

HYPR Passwordless client may not display a completed pairing right away. It may be necessary to close and restart the HYPR Passwordless client for the warnings to disappear.

  1. On the HYPR Mobile App, tap the arrow next to the userId for instructions on how to finish the pairing.

The user will now appear in the integration under User Management's Paired with HYPR tab. Continue to Pairing with Azure to complete your passkey registration.

See Integration User Management in the main Integrations article for how to navigate User Management.

Pairing Using Windows Bluetooth

With the addition of Bluetooth pairing, a new set of dialogs comes into play if you use Bluetooth to connect to your network. The pairing process may refer to Windows flows for connecting your device to your computer via Bluetooth; we have included this flow here for reference.

Following are the screens presented by Windows when using Bluetooth to register a security key for the first time.

After seeing these notifications, you will continue with the Entra/Azure FIDO portion of pairing.

👍

Back to Whence You Came

In the middle of pairing? Jump back to continue.

Pairing With Azure

Back on the Azure VM:

  1. Login to https://mysignins.microsoft.com/security-info. This will take you to the screen below.

  2. Select UPDATE INFO.

    📘

    Get the Edge

    If you do this using Microsoft Edge, you should not need to manually login. Edge will have a desktop SSO-like experience where you are not prompted. Chrome and FireFox will prompt you.

  3. Here you see all of the authenticators registered for the user. Azure traditionally requires at least one authenticator, which depends on how the tenant is configured. Usually it will be phone and/or text. Click Add sign-in method.

  1. The Add a method options will depend on the configuration of the tenant, but in this case, select Security key, then click Add.

👍

Note

Microsoft may require MFA depending on how you logged in initially. You need to complete MFA to change authentication methods (add/delete).

  1. Confirm the Security key type; select USB device.
  1. Microsoft then prompts you to have your key ready. Open the HYPR Mobile App on your device. This is required for the HYPR Mobile App to virtually connect to the USB on the VM/workstation. Once the HYPR Mobile App is open, click Next.

The next few prompts come from the browser and the Windows operating system as part of the FIDO2 protocol.

  1. If the browser version supports passkeys, this will appear. Click External security key or built-in sensor.
  1. On the Security key setup dialog, click OK.
  1. On the Continue setup dialog, click OK.
  1. Now Microsoft prompts you to touch your security key. You will see a verification screen to add this device on the HYPR Mobile App. Touch Accept.

🚧

Virtually Blind

If you see this message from Microsoft instead, it means that the VM did not discover the mobile device. You will not be able to continue until this is resolved.

  1. HYPR Mobile App will prompt you to register a biometric. Follow those instructions.

👍

Separate Biometrics

This biometric is specific to Azure; it is not the same biometric requested for the HYPR QR code scan.

  1. Once the biometric is registered, Microsoft will ask you to name the new security key. Have at it.

All set. You now are able to leverage HYPR’s FIDO2 Mobile Authenticator as a Security Key in Azure, and you will see it listed as an available authenticator:

HYPR Mobile App Changes

Now that you are paired with Azure, the HYPR Mobile App will change. There are no changes on the HYPR Mobile App if the workstation is Azure AD Joined.

If the workstation is Hybrid Azure AD Joined, when scanning HYPR’s QR code the HYPR Mobile App will display the workstation pairing under the My Computers section.

Navigate to the Device Manager, and tap My Security Keys.

When you tap My Security Keys, the warning icon next to the username is now gone.

Selecting the arrow at right now shows the details of the pairing and allows you to rename it, delete it, or view the login activity; similar to My Computers or My Web Accounts.

While the Integration is DISABLED, if a user attempts to pair with HYPR, the HYPR Mobile App will issue a warning.

Likewise, if domains have been restricted in the Desktop Client tab, and the user is not part of an accepted domain, HYPR Mobile App will issue the following warning:

Invitation Emails

Unlike other integrations' enrollment processes, HYPR Enterprise Passkey does not send invited users a link to pair with Device Manager. Instead, the email is informational only, and the link provided connects to Pairing with HYPR in this article.

User Management for HYPR Enterprise Passkey

Paired with HYPR and Paired with Azure

Due to the infrastructure underpinning the HYPR Enterprise Passkey, in addition to the Pending state shown in other Integrations, users may be either Paired with HYPR (awaiting Enterprise Passkey pairing completion) or Paired with Azure (fully paired as a HYPR Enterprise Passkey), instead of Enrolled.

The information shown under each tab is the same as described here.

ColumnDescription
EmailThe Entra/Azure account email.
UsernameThe Entra/Azure username.
NameThe user's full name, if entered.
Device CountThe number of devices registered.
Last ActiveThe time of their last activity.
ActionsHover on over Options; here you may Delete the account.

User Device Details

For users that are Paired with HYPR, their Device Details Mobile Devices tab now shows the FIDO2 web domain and the FIDO2 username which were paired.

The following additional columns appear in this list:

ColumnDescription
ModelThe model of the Enterprise Passkey mobile device.
Mobile OSThe operating system (OS) of the Enterprise Passkey mobile device.
Device IDThe deviceId attribute assigned to this device.
FIDO IDA unique number for the FIDO credential.
Date CreatedThe time at which the device pairing was made for the device or machine in question.
AuthenticatorsIcons matching applied authenticators from Policy Management appear here.
WorkstationsA list of workstations to which this HYPR Mobile App is paired.
Workstation IDThe unique identifier for the workstation.
Web DomainsThe FIDO2 web domain.
UsernameThe FIDO username, which may differ from the domain username.
Domain IDThe unique identifier for the domain.

Unpaired Users

Users who are Paired with HYPR or Paired with Azure who unpair their devices will be moved to the Pending tab of User Management; a warning icon appears next to the Email field. Hovering over the icon, the text appears, "This user unpaired from HYPR."

Likewise, if an Entra/Azure account is suspended or removed, HYPR shows an icon indicating the Azure pairing no longer exists. HYPR calls Entra/Azure to confirm account statuses when this page is opened.

Logging In with HYPR Enterprise Passkey

Logging In to Windows

Lock the VM or workstation and then unlock it. Windows defaults to the last account and method used to successfully log in. The example shown here used a Windows Hello PIN, so that's what Windows is putting forth:

  1. Open HYPR Mobile App and select Sign-In options.
  2. Tap the security key icon.
  3. Microsoft will send the user presence (UP) verification to the HYPR Mobile App. On the HYPR Mobile App, tap Accept.
  1. Complete the biometric prompt (User Verification).

Once this is completed, you will be logged into Windows!

📘

State Dependency

The Windows login experience depends on the state of the Windows OS.

Sometimes it will behave like above. Other times as soon as you wake it, it will start the FIDO authentication process and send the user presence (UP) verification to the mobile device for “Other User”. This is perfectly fine; after HYPR Mobile App’s Accept and biometric authentication, Microsoft will recognize for whom the FIDO keys are, and switch the username to the correct one.

Logging In to Azure Protected Content (Like O365.com)

  1. Login with the paired user account in Chrome to ensure you get a login prompt (Edge will use SSO).
  1. You may get the default login screen with password or you may just get the FIDO2 prompt. It all depends on the browser and what Microsoft has recorded. If you see the password prompt, select Other ways to sign in.
  1. Select Use Windows Hello or a security key.
  1. Open the HYPR Mobile App and select Security key.
  1. Go through the motions for FIDO UP and User Verification (UV), and you are now in Microsoft Office.

Logging In Using Windows Bluetooth

With the addition of Bluetooth authentication, a new set of dialogs comes into play. Following are the screens presented by Windows when using Bluetooth to authenticate a security key.

After seeing these notifications, you will continue with the FIDO portion of authentication.

Updated 1 day ago