Skip to main content
Version: 10.3.0

Entra ID: HYPR Enterprise Passkey in CC

Beta

Please note, this integration is in a beta phase. Please provide any feedback or enhancement requests to your HYPR Account Manager and these will be worked into our next release.

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. Once implemented, Entra will see any affected mobile devices as hard token passkeys.

HYPR Enterprise Passkey can be integrated with several different workstation setups, depending on your environment:

  • Non-domain-joined: the Windows workstation is not joined to any domain and is owned by the user; the user can login via a Microsoft account or an account local to the machine

  • On-premises Active Directory: the Windows workstation is joined to an on-premises Active Directory and is owned by the user; the user can login to any workstation joined to same domain with the user credentials on the domain controller

  • Entra Domain-joined: the Windows workstation is joined directly to the Entra cloud; the user can login to any workstation joined to Entra ID using the user account in Entra

  • Hybrid Entra Domain-joined: the Windows workstation is joined to both the on-premises Active Directory and to the Entra cloud; the user can login with the user credentials on the domain controller.

What's Your Status?

Use the following command to check the status of a Windows workstation:

dsregcmd /status

The command above will display the current status of your workstation and the name of the device it's running on.

Getting the HYPR Enterprise Passkey integration up and running requires the following basic steps:

  1. Understand how the Entra ID login process changes for end users after you integrate with HYPR. See What Will Happen in Entra?.

  2. Configure the Entra ID side of the integration. See Setting Up Entra ID.

  3. Configure the HYPR side of the integration. See Connecting Entra to HYPR.

  4. Configure and download the HYPR Passwordless desktop client. See Configure and Download the Desktop Client

The following HYPR Integration common tasks are explained on the Integrations main page.

Licensing

Enrolling and authenticating with passkeys (FIDO2) on Microsoft Entra ID don't require any particular license subscription, but requires at least a Microsoft Entra ID P1 subsription if you want to enforce its usage through Conditional Access policies. Please check your Microsoft subscription before proceeding with configuring the integration.

FIDO2 Provisioning API Public Preview

HYPR Enterprise Passkeys leverages Entra ID FIDO2 Provisioning API in order to seamlessly enroll users' passkeys into Entra. This feature has been launched as Public Preview in August 2024. Learn more about the launch in the FIDO2 provisioning API public preview announcement and the HYPR announcement.

What Will Happen in Entra ID?​

Login Flow​

Once you activate the HYPR Entra ID Enterprise Passkey integration, users will continue to have the usual Entra ID login flow.

Enrolled Users
Users who have been successfully enrolled via HYPR Passwordless are going to have their Enterprise Passkey automatically enrolled into Entra ID.

When signing in to Entra ID on the browser, after entering their username users can authenticate with HYPR Enterprise Passkey by selecting security key. When loggin into Windows, users will tap on their copmuter account on their HYPR Mobile application to sign in.

Behind the Scenes​

Once you create the integration, HYPR will handle as much of the back-end configuration in Entra ID as possible.

Non-enrolled Group Membership
Users who haven't registered a device with HYPR before you activate the HYPR Entra ID Enterprise Passkey integration will automatically be added to a “Users Not Yet Enrolled” Entra ID group created by HYPR during the setup process. They'll automatically be removed from the non-enrolled group as soon as they register a device.

What You'll Need​

  • Since you're setting up the HYPR Enterprise Passkey integration through the HYPR Control Center, you should have already registered for an account, paired your mobile device with HYPR, and used your new passwordless login to access the Control Center; if this isn't the case, please contact HYPR Support.

  • Make sure you have the Entra tenant available and an account that exists on the \*.onmicrosoft.com domain with Global Admin Access.

  • Enable FIDO2 Security Keys in the Entra tenant as referenced here or here. The Get started with phishing-resistant passwordless authentication deployment in Microsoft Entra ID guide provides a comprehensive walkthrough over enabling passkeys in Entra ID.

  • You should have an Intune account on the \*.onmicrosoft.com domain with Global Admin Access with Intune licenses.

  • Enable the FIDO2 Security Key Credential provider in Intune:

Workstation​

  • Currently the workstation/VM OS must be Windows, as macOS is not yet supported

  • Entra domain-joined or Entra hybrid-joined VMs or physical machines for testing

  • Ensure the Windows Workstation OS patch level requirements are met

  • The HYPR Passwordless client must be installed on the affected workstation(s)

  • Workstation support for FIDO2 security keys will vary depending on how the workstation is joined:

    • Microsoft does not support FIDO2 security keys for authentication to Active Directory joined workstations
    • Microsoft supports FIDO2 security keys for authentication to Hybrid Entra AD joined workstations
    • Microsoft supports FIDO2 security keys for authentication to Entra AD joined workstations

  • Hybrid joined workstations only:

Known Issues​

  • We recommend making yourself aware of known issues and FAQs—the most impactful is “Signing in or unlocking a Windows device with a security key containing multiple Microsoft Entra accounts”

Setting Up the Entra AD Tenant​

Registering the HYPR Entra ID Application using a Powershell script​

Run the following script, replacing the name of the app to match the one required by HYPR:

# Connect to Microsoft Graph with admin-level scopes
Connect-MgGraph -Scopes "Application.ReadWrite.All", "AppRoleAssignment.ReadWrite.All", "Directory.ReadWrite.All" -NoWelcome

# Define basic variables
$appName = "HYPRAuthAppTest"
$graphAppId = "00000003-0000-0000-c000-000000000000"  # Microsoft Graph API App ID
$redirectUri = "https://login.microsoftonline.com/common/oauth2/nativeclient"

# Define required permissions (delegated and application)
$requiredResourceAccess = @(
    @{
        ResourceAppId = $graphAppId
        ResourceAccess = @(
            # Delegated permissions (Type = Scope)
            @{ Id = "0e263e50-5827-48a4-b97c-d940288653c7"; Type = "Scope" }   # Directory.AccessAsUser.All
            @{ Id = "b7887744-6746-4312-813d-72daeaee7e2d"; Type = "Scope" }   # UserAuthenticationMethod.ReadWrite.All

            # Application permissions (Type = Role)
            @{ Id = "19dbc75e-c2e2-444c-a770-ec69d8559fc7"; Type = "Role" }    # Directory.ReadWrite.All
            @{ Id = "50483e42-d915-4231-9639-7fdb7fd190e5"; Type = "Role" }    # UserAuthenticationMethod.ReadWrite.All
        )
    }
)

# Create the App Registration
$app = New-MgApplication -DisplayName $appName `
    -Web @{ RedirectUris = @($redirectUri) } `
    -RequiredResourceAccess $requiredResourceAccess

Write-Host "✅ App Registration created. App ID: $($app.AppId)"

# Wait briefly for AAD to replicate
Start-Sleep -Seconds 10

# Create the service principal
$sp = New-MgServicePrincipal -AppId $app.AppId
Write-Host "✅ Service Principal created. Service Principal ID: $($sp.Id)"

# Get Microsoft Graph Service Principal
$graphSp = Get-MgServicePrincipal -Filter "appId eq '$graphAppId'"
$graphSpId = $graphSp.Id

# Assign **Application permissions** via AppRoleAssignments (delegated ones are not assigned this way!)
$appRoleAssignments = @(
    @{ AppRoleId = "19dbc75e-c2e2-444c-a770-ec69d8559fc7" }  # Directory.ReadWrite.All
    @{ AppRoleId = "50483e42-d915-4231-9639-7fdb7fd190e5" }  # UserAuthenticationMethod.ReadWrite.All
)

foreach ($role in $appRoleAssignments) {
    # Perform the role assignment silently (no output for each role assignment)
    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id `
        -PrincipalId $sp.Id `
        -ResourceId $graphSpId `
        -AppRoleId $role.AppRoleId | Out-Null
}

# Create a client secret
$secret = Add-MgApplicationPassword -ApplicationId $app.Id
Write-Host "`n🔐 Client secret created:"
Write-Host "ClientId: $($app.AppId)"
Write-Host "ClientSecret: $($secret.SecretText)"
Write-Host "TenantId: $((Get-MgContext).TenantId)"

# Generate the Admin Consent URL for the required permissions
$tenantId = (Get-MgContext).TenantId
$adminConsentUrl = "https://login.microsoftonline.com/$tenantId/adminconsent?client_id=$($app.AppId)&state=12345&redirect_uri=$redirectUri"

Write-Host "`n🚨 Please grant admin consent via the following URL in your browser:"
Write-Host $adminConsentUrl

Write-Host "`n🔑 Admin consent for the required permissions will need to be granted by an admin user."
Write-Host "Please copy and paste the URL into your browser and proceed with granting the required permissions."

Registering the HYPR Entra ID Application via the user interface​

  1. From the Entra ID portal home screen, select Entra Active Directory > App registrations > New registration.

  2. In the Register an application dialog, enter the application name as HYPRAuthApp and select Accounts in this organizational directory only.

  3. Click Register when done.

  4. On the Overview page, make a note of the following values which you'll need later for PowerShell and HYPR's UX configuration:

    • clientId

    • tenantId

Configure a Web Redirect URI​

  1. From the Entra ID screen, select App registrations and select the app you just made.

  2. In the menu pane on the left of the screen, select Authentication from the Manage drop-down menu.

  3. Select Add a platform.

  4. In the Configure platforms dialog that appears, select Web.

  5. In the Configure Web dialog, specify the following as a Redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient.

  6. Select Configure.

Grant Required API Permissions​

  1. From the Entra Active Directory screen, select App registrations and select your HYPR app.

  2. Select API permissions.

  3. By default, the application will already have Microsoft Graph's User.Read permission. This isn't required, so remove it by clicking the ... icon and choosing Remove permission. Click Yes, remove to confirm when prompted.



  4. Click Add a permission, and on the tiled choices, select Microsoft Graph.

  5. Select Delegated permissions.



    Delegated by Default

    Sometimes Entra ID will not display the option for Delegated or Application permissions, and will immediately assume Delegated as the choice. However, if you grant Admin Consent later on, you will be able to verify the permission type.

  6. Locate and add the following:

    • Directory.AccessAsUser.All

    • UserAuthenticationMethod.ReadWrite.All

  7. Next, click Add permissions.

  8. You must now Grant admin consent for the permissions to take effect:

  9. Below is a list of all permissions that should now be granted to the application:

Creating an application credential​

You'll need to provide a credential when you set up the integration in the HYPR Control Center, which is going to be used to interact with the Entra resources via the Graph API. You can use a client secret or a client certificate as this credential.

OAuth flow

The Entra ID External Authentication Method integration uses the OAuth 2.0 Client Credentials Grant flow to authenticate to Entra's Graph API.

Creating a client secret​

You’ll need to provide a client secret when you set up your integration in the HYPR Control Center. Generate the client secret in Entra as follows:

  1. From the Entra ID screen, select App registrations and choose your app.

  2. Select Certificates & secrets, then click New client secret.

  3. Enter a Description and an Expires date. Click Add when finished. Entra returns to the Certificates and Secrets list.

  4. Make a note of the client secret value now so you can use it later.



    One Time Only

    If you return to this screen later, Entra will mask the value and you won't be able to copy it.

Using a client certificate​

If you choose to use a client certificate, you can upload it in Entra as follows:

  1. From the Entra ID screen, select App registrations and choose your app.

  2. Select Certificates & secrets, then select Certificates and click Upload certificate.

  3. Enter a Description and click Add when finished. Entra ID returns to the Certificates and Secrets list.

Available certificate

You will need to have an X.509 certificate and its corresponding private key available if you decide to use client certificate-based authentication. The certificate can be a self-signed or signed by a Certificate Authority trusted by your organization.

For more information about the use of X.509 certificates in Entra ID applications refer to the corresponding guide. You can also check their guidance on usage of self-signed certificates.

Enable Security Keys in the Entra Tenant​

  1. Login to entra.microsoft.com as a global admin account.

  2. Navigate to Entra Active Directory > Security > Authentication methods.

  3. Click on the Passkey (FIDO2) authentication method policy.

  4. FIDO2 security key settings defaults to the Enable and Target tab. Here you can enable security keys and define allowed users. Select Include All users and leave the registration as Optional.

  5. On the Configure tab, make sure the settings are as depicted below. This is the only configuration we 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, you must enable the use of security key login on Windows. You can do this through Intune, which is a provisioning package. Refer to Microsoft's instructions on using Intune.

HYPR Control Center - Setting Up the HYPR Tenant​

When up and running, make sure HYPR has enabled the necessary features to support HYPR Enterprise Passkeys. The

  1. On a new tenant, go to the Integrations screen in the HYPR Control Center and click Add New Integration to show a list of available integration types.

  2. Select the Microsoft Entra ID integration.

  3. HYPR will present you with a choice; select Native Microsoft Entra Login Experience for the FIDO2 Mobile Authenticator, and click Next.

    1. You are presented a form which contains the HYPR Application Name and all of the Entra-related data needed for HYPR to connect to the Entra tenant. These are the items created/captured above; complete the fields as follows:


    FieldValue
    Application NameThe name you provide here will be used in three places:

    - For the web account name that users will see in the HYPR Mobile App

    - For the HYPR Device Manager page where users register their devices

    - For internal identification of this integration within the HYPR platform

    You can use any name you like, but it's best to go with something that indicates the purpose of the application. For example:

    passwordlessClientEntraSSO

    You can use numbers, spaces, dashes, hyphens, and underscores in the name but note that spaces will be stripped from the name used to internally identify the integration within the HYPR platform. The namespace is limited to 23 characters.

    Once set, the only way to change the Application Name is to delete and re-add the integration.
    Tenant IDThe ID of the tenant.

    If you didn't make a note of this earlier, you can retrieve it from the Overview page for the application in Entra (see Registering the HYPR Entra ID Application).

    Once set, the only way to change the Tenant ID is to delete and re-add the integration.
    Client IDThe ID of the client/application in Entra AD.

    If you didn't make a note of this earlier, you can retrieve it from the Overview page for the application in Entra ID (see Registering the HYPR Entra ID Application).

    Once set, the only way to change the Client ID is to delete and re-add the integration.
    Client SecretThe client secret associated with the client/application.

    If you didn't make a note of this earlier, you'll need to go back and generate a new one in Entra ID (see Using a Client Secret).
    Client CertificateThe X.509 certificate uploaded to the Entra ID application, if you decided to use a client certificate.

    You'll need to provide the certificate in PEM-encoded format.
    Client Private KeyThe private key of the client certificate uploaded to the Entra ID application, if you decided to use a client certificate.

    You'll need to provide the private key in PEM-encoded format.

  5. Click Add Integration to begin.

  6. If the setup succeeds, confirming all provided parameters are valid, which means HYPR can now connect to Entra, you'll see the Integration Added! confirmation dialog. Click Maybe Later.



    HYPR Groups in Entra

    When a new Enterprise Passkey integration is successfully created, HYPR automatically creates three groups in Entra. 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)

    • HYPR Group (Client Paired with Entra) - Users with Enterprise Passkey authentication

  7. With a new application in HYPR, you must make sure HYPR has enabled the necessary features; contact HYPR Support if you have not done so already to ensure full functionality.

  8. HYPR Control Center takes you to the Integration User Management page.

  9. Select the Integrations Settings tab. You will see a brief description of the Native Entra ID 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.

  10. Click Enable and a confirmation appears.

  11. 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 Windows Desktop Client.

  2. 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"

  3. Select Download Desktop Client and a confirmation popup displays.

  4. If you are unsure whether or not you should be downloading the HYPR desktop client for Windows 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.

  5. Unpack the archive. It contains two files:

  6. Install the HYPR desktop client on an Entra joined workstation by double-clicking WorkforceAccess-10.1.0_x64.msi. Complete the instructions for Windows in Installing with the UI.

Pairing a HYPR Enterprise Passkey​

See the section in HYPR Passwordless describing the user experience when pairing a HYPR Enterprise Passkey.

User Management for HYPR Enterprise Passkey​

Paired with HYPR and Paired with Entra​

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 Entra (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 account email.
UsernameThe Entra username.
NameThe user's full name, if entered.
Device CountThe number of devices registered.
Last ActiveThe last time this device was used.
ActionsHover on over Options; here you may Delete the account.

Expanding a user displays all registered FIDO2 devices, including the ones that may be registered with other Integrations or IdPs.



The labels here are as follows:

ColumnDescription
Device NameThe name of the device as assigned by the user. This may be the default manufacturer's label or a name given to the device by the user in Device Manager. Click this value to open Device Details for that device.
Last ActiveThe time this key was last in use.
DeleteClick the trash can icon to delete this device from this user account.

User Device Details​

For users that are Paired with HYPR, drilling into one of the Device Name values will open Device Details.

  • The Mobile Devices tab 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.
    DeleteClick the trash can icon to delete this device or domain. A confirmation will display before HYPR returns to this page.
    WorkstationsA list of workstations to which this HYPR Mobile App is paired.
    Workstation IDThe unique identifier for the workstation.
    Web DomainsThe fully qualified FIDO2 web domain.
    UsernameThe FIDO username, which may differ from the domain username.
    Domain IDThe unique identifier for the domain.

  • The Security Keys tab shows a few different properties associated only with passkeys

    The values not already defined that appear under Security Keys are as follows:

    ColumnDescription
    Device NameThe name of the device. This may be the factory label, or may have been changed by the user in Device Manager.
    FirmwareThe firmware version used by this device.
    Modelplatform: A security key built in to the machine; typically a biometric.
    Certificate Serial #The serialized number in the production series for this device.

  • On either tab, click Back to User Management to return to the main User Management pane.

Unpaired Users​

Users who are Paired with HYPR or Paired with Entra 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, accounts that are unpaired with Entra but still retain the HYPR pairing will be moved under Paired with HYPR.

Likewise, if an Entra account is suspended or removed, HYPR shows an icon indicating, "This user cannot be found in Microsoft Entra." HYPR calls Entra ID to confirm account statuses when this page is opened.

Enabling FIDO2 Passwordless Security Key on Windows

Enabling security key sign-in for Windows