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 Azure AD.

What Youโ€™ll Need

  • Make sure you have the Azure tenant available and an account that exists on the \*.onmicrosoft.com domain with Global Admin Access
  • Make sure you have the Azure licenses (P1) assigned to the test accounts
  • You should have an Intune account on the \*.onmicrosoft.com domain with Global Admin Access with Intune licenses
  • Azure domain-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 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 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-Azure integration
    • Privileged Authentication Administrator
      Allows HYPR to manage the HYPR Enterprise Passkey on 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 Azure
  3. Click Add when done.

๐Ÿ“˜

Expect the Unexpected

This is the area in which Azure is very slow to replicate the changes. The 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 azure.portal.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 Azure Tenant

  1. Login to portal.azure.com as a global admin account.
  2. Navigate to 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 Enforce attestation to ensure the FIDO2 authenticator is certified by them. They expect to add our AAGUID by end of February 2023. When that happens we can support this feature as Yes.

Enable Security Keys in Intune

Once security keys are enabled in 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 Azure-related data needed for HYPR to connect to the 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.
  • Domain Name: The domain where Azure AD is deployed, in the following format: mydomain.com
  • Client ID: The ID of the client/application in 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 Azure.
  1. You will be presented a popup box. Click Maybe Later.
  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 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 do the QR code pairing with HYPR, but cannot register or authenticate to Azure.

  2. Click Enable and a confirmation appears.

  1. Let the confetti fly, then click Close.
  1. Navigate to Login Settings. Here you can download the WFA client.
    Installation Guides and Access Control are currently being built.
  1. Select Download Desktop Client and a confirmation popup displays with some more details on the type of WFA. Select Download Now and and your browser will download the client and a hypr.json file in a .zip archive.
  2. Install the HYPR Workforce Access Client on an Azure domain-joined workstation.
  3. 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.

Now you are ready to pair with HYPR.

Pairing With HYPR

  1. Login to Windows as an Azure cloud-only account (i.e., [email protected]).
  2. Launch the HYPR Workforce Access Client.
  3. Click Start Pairing.
  1. HYPR Workforce Access Client presents a QR code. Using a device with the HYPR Mobile App installed and open, scan the QR code on the screen. You will be prompted to authenticate your device.

๐Ÿ‘

Going Mobile

You may see both the mobile device and the security key as options. Choose the mobile device for this operation; the security key will not work with this version of HYPR.

  1. Once the HYPR Mobile App is successfully paired, 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 WFA for the mobile device.
    They have โ€œPaired with HYPRโ€ but have not โ€œPaired with Azureโ€.

  1. Click the arrow next to the userId for instructions on how to finish the pairing.

The user will now appear in CC under User Management.

๐Ÿ‘

Paired with Whom?

In the next release, User Management will have tabs to indicate Paired with HYPR and Paired with Azure. Also the process to delete a pair is incomplete; so a delete in the CC may not be reflected on the HYPR Mobile App or Workforce Access Client.

Pairing With Azure

Back on the Azure VM:

  1. Login to https://aka.ms/mysecurityinfo. 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:

Mobile Application Changes

Now that you are paired with Azure, the HYPR Mobile App will change. When you open and close the application and navigate to My Security Keys, you see 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.

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!

๐Ÿ“˜

Note

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.