Integrating with Azure AD

Integrating HYPR with Azure Active Directory (AD) lets you access your organization’s Azure-based applications (such as Office 365) using HYPR passwordless authentication instead of the standard username + password login.

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

1. Understand how the Azure login process changes for end users after you integrate with HYPR. See What Will Happen in Azure?.
2. Configure the Azure side of the integration. See Setting Up Azure.
3. Configure the HYPR side of the integration. See Connecting Azure to HYPR.
4. Choose the methods you want people to be able to use for passwordless authentication. See Allowing the Use of FIDO2 Authenticators.
5. Enroll your existing Azure users. See Enrolling Users Before the Integration Goes Live.
6. Turn the integration on. See Activating the Integration.

After the integration is live, you’ll carry out maintenance activities such as enrolling new hires or using the Audit Trail feature to monitor system events.

What Will Happen in Azure?

Login Flow

Once you activate the HYPR Azure integration, users will experience a different Azure login flow depending on whether they’re enrolled or non-enrolled.

Enrolled Users
Users who have been successfully enrolled via the HYPR Control Center will no longer need to provide a password to login to Azure. After providing their username on the Azure sign in screen, they’ll be redirected to the HYPR passwordless authorization flow. Essentially, HYPR intercepts the default Azure login process and replaces the password step with passwordless access.

Non-enrolled Users
Users who have not been enrolled via the HYPR Control Center will be prompted to enter their Azure password after they click Sign In on the HYPR login screen.

Behind the Scenes

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

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

What You'll Need

HYPR Control Center Account
Since you’re setting up the HYPR Azure 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 us at [email protected] and we’ll help you out.

Azure Global Admin Account
You must already have Azure AD set up and active for your organization before you start the integration. Some of the HYPR Azure integration is automated but you’ll need to login to Azure with a global admin account in order to perform the necessary setup steps.

📘

NOTE

Although not required, it’s easier to set up the integration if your HYPR Control Center username and your Azure admin account name are the same email address.

Setting Up Azure

Registering an Application

1. From the Azure home screen, select Azure Active Directory > App registrations > New registration.

2. Enter the application name 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 when configuring the integration in the HYPR Control Center:

Application (client) ID
Directory (tenant) ID

Granting Required API Permissions

1. From the Azure Active Directory screen, select App registrations and choose the HYPRAuthApp.

2. Select API permissions.
3. By default, the application will already have Microsoft Graph’s User.Read. 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.

5. Select Microsoft Graph.

6. Select Delegated permissions.

📘

NOTE

In some situations, Azure won’t display the option to choose Delegated or Application permissions and will automatically default to Delegated.

7. Select Directory.AccessAsUser.All and click Add Permissions.

8. Click Grant admin consent to apply the permissions and click Yes to confirm when prompted.

Setting Application-level Scope

1. From the Azure Active Directory screen, select App registrations and choose the HYPRAuthApp.
2. Select Expose an API, then click Set next to Application ID URI.

3. Accept the default Application ID URI setting by clicking Save.

4. Click Add a scope.

5. Enter the following values:

Scope name: User.Read

Who can consent: Admins and users

Admin consent display name: HYPRAuthApp User.Read Access

Admin consent description: HYPRAuthApp User.Read Access

State: Enabled

6. Click Add Scope to save the changes.

Creating a Client Secret

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

1. From the Azure Active Directory screen, select App registrations and choose the HYPRAuthApp.
2. Select Certificates & secrets, then click New client secret.

3. Enter a Description and an Expires date of 24 months.

4. Make a note of the client secret value now so you can use it later when connecting Azure to HYPR.

📘

NOTE

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

Creating a Service Account

You’ll need to provide a service user account name and password when you set up the integration in the HYPR Control Center.

🚧

onmicrosoft.com

The service account here must be created on onmicrosoft.com, not on the custom federated domain.

Create the account in Azure as follows:

1. From the Azure Active Directory screen, select Users.

2. Click New user.

3. Select Create user and enter the following values:

User name: hyprserviceaccount

Name: HYPR Service Account

Password: Let me create the password

Enter a temporary password and make a note of it so you can change it below.

4. Click Create to save the user account.
5. On the Profile screen for the new account, select Assigned roles.

6. Select Add Assignments.

7. Search for and add the following Directory roles:

Application administrator
Configures the HYPRAuthApp application to accept authentication via ROPC when the domain is federated. Needed when adding or deleting the HYPR Azure integration via the Control Center.

Conditional Access administrator
Permits creation/updating for the HYPR Conditional Access Policy. Needed when adding, enabling, disabling, or deleting the HYPR Azure integration via the Control Center.

Directory writers
Allows the necessary group creation/update and also handles getting the user data for sync and the immutableID for authentication. Needed throughout the entire lifecycle of the HYPR Azure integration.

8. Click Add when done.

📘

Patience

Azure can be very slow to replicate these changes. You may need to refresh the page several times, or possibly add some of the settings more than once.

9. Confirm that all the roles were successfully assigned.

10. Open an incognito browser window and login to portal.azure.com as the new service account user so you can set the permanent password.

📘

One Condition

If the account gets prompted for MFA during this login, it means you have a Conditional Access Policy in place which will need to be updated to exclude the hyprserviceaccount user.

11. Enter an appropriate new password and make a note of it for later.

Creating a Custom Domain

If the domain you intend to secure with HYPR isn’t already set up and verified by Azure, you’ll need to add one. Note that it can take a couple of days for the DNS changes to propagate.

📘

Managed, Not Federated

If you already have a verified domain, make sure it isn’t already set to Federated in Azure AD. If it is, you must change it to Managed before you activate the integration (“Go-Live”) with HYPR.

1. From the Azure Active Directory screen, select Custom domain names then click Add custom domain.

2. Enter your domain in the Custom domain name field and click Add domain.

You’ll need create a new TXT or MX record with your domain name registrar. Azure provides the necessary information and allows you to verify the domain once it’s been created.

Connecting Azure to HYPR

Once Azure is set up, you can add the integration to HYPR.

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

3. To integrate HYPR and Azure, you just need to provide some basic information on the Integrations screen.

4. Click Add Integration to begin.
5. If the setup succeeds, you’ll see the Integration Added! confirmation dialog.

6. You can optionally now register to use HYPR Azure logins yourself by clicking Enroll Myself. You’ll be taken to the HYPR Device Manager where you can register your mobile device.

📘

NOTE

The Enroll Myself option is only available if your Azure username is the same as your HYPR Control Center username. If not, you can add yourself as a regular user later (see Enrolling Users before the Integration Is Live).

Once you’ve registered a device, you’ll see your username in the list of enrolled users.

Allowing the Use of FIDO2 Authenticators

FIDO2 is a set of standards defining the use of mechanisms such as security keys and biometric recognition in multifactor authentication. By default, the only mechanism your users can choose for logging into Azure is a mobile device. If you would like them to be able to login with a security key, you must enable FIDO2 settings for the integration.

Your organization must already have a FIDO2 server set up to perform this type of authentication. Please contact HYPR Support for assistance.

Complete these steps to enable the use of security keys for Azure logins:

1. Go to the Integrations screen in the HYPR Control Center and click the Azure AD integration.
2. Go to the FIDO2 Settings tab.

3. Slide the Enable Fido2 button to the On position.
4. Verify the Client Origin URL is correct. This URL is entered automatically as part of the integration setup, so you typically don’t need to edit it.

📘

Keep It Low

The Client Origin URL value must be all lowercase. If users are unable to pair FIDO2-based devices successfully, check that this URL does not contain any uppercase characters.

5. Click Save.

Enrolling Users before the Integration Goes Live

Before users in your company can start accessing their Azure applications with HYPR, you need to invite them to enroll. The enrollment process involves sending the users an email containing unique links they can use to register a device for passwordless login.

The link in each email can only be used once, and it can only be used by the person it’s sent to. The link expires if not used within seven days.

There are two ways to invite people in your company to enroll for passwordless login:

• In bulk or individually before the integration goes live.
• Individually after the integration goes live.

📘

There Can Be Only One

After the integration goes live, you can’t invite multiple users at once to enroll; you can only invite them individually. For this reason, we recommend you use the bulk method to enroll your users before you activate the integration.

This section describes how to enroll users before the integration is live. For information on enrolling them later, please see Enrolling Users after the Integration Is Live.

Inviting Users to Enroll before the Integration Goes Live

Before the integration is activated, you can invite multiple users to enroll at once, or you can invite users individually.

1. Go to the Integrations screen in the HYPR Control Center and click the Azure AD integration.
2. Display the User Management tab.
3. Click Enroll Users. You’ll see a User Directory list showing all the people in your company who are currently registered as Azure AD users and are not using HYPR to login to their Azure-based applications. The list is refreshed every time you access this screen but if it’s missing any names you expect to see, click Sync with Azure AD.

4. To invite everybody in the list, click Send Enrollment Emails to All. To invite a single user, click the Send Email link next to their name.
5. Click Send Enrollment Email(s) in the confirmation screen.
6. Click Done.
7. In the User Management screen, click Pending. You should see the names of the people you invited.

After the users in the Pending list successfully register a device, their names move to the Enrolled list.

What Users Do to Enroll

Users will receive the following enrollment invite via email.

When they receive the enrollment email, users should click the Get Started link. The link takes them to the HYPR Device Manager where they choose the device they want to use to perform passwordless login for their Azure applications.

📘

No Security Key Option

If Smartphone is the only option that appears and you want to allow security keys, you must configure the FIDO2 settings for the integration so this extra option appears. See Allowing the Use of FIDO2 Authenticators.

Users select the type of device they want, then pair the device following the on-screen instructions. (The process is similar to pairing a device with the Workforce Access Client for a workstation login; see Registering a New Device.)

After you activate the integration, the next time your users login to Azure they’ll see the new passwordless login option. See Login Flow for more information.

Changing the Device Used for Azure Logins

Currently, users of the HYPR Azure integration don’t have self-service access to the HYPR Device Manager after their initial device registration. Users who want to add another device for logging into Azure, or need to unpair an existing device, will need to ask a Control Center admin to send them a new enrollment invite granting them one-time access to the Device Manager.

Troubleshooting User Enrollment

If sending an email invite doesn’t work for one or more users, or the link they receive expires before they can use it, you can try one of the following:

• Resending the invite
• Manually generating a link and sending it to the user, for example through a separate email. (The link you generate in this case is called a magic link.)

Resending the Invite

To resend the invite, complete these steps:

1. Go to the Pending list.
2. Locate the user you want to invite again. Click Options in the Action column.
3. Click Resend Invite.
4. In the confirmation screen, click Resend Invite.

Generating a Magic Link

Magic links work the same way as the links included in the auto-created email invitations. To generate a magic link for a specific user, complete these steps:

1. Go to the Pending list.
2. Locate the user you want to invite again. Click Options in the Action column.
3. Click Generate Magic Link. You’ll see a warning message telling you other magic links will be invalidated. Generally this behavior doesn’t cause a problem. Magic links are unique to each user, so only links that were created previously for this user will be affected.
4. Click Generate New Magic Link.

6. Copy the link and send it to the user, for example through a separate email or other communication channel. They use it the same way they would use the link sent through the original enrollment process. Note, however, that magic links can only be used one time and also expire in 24 hours.
7. Click Close.

Removing a User’s Passwordless Access to Azure

If you accidentally invited a user to enroll and want to uninvite them, you can delete the user from the Pending list, which will invalidate the invitation.

📘

Taking a Pause

If you need to remove passwordless access to Azure for all users rather than just one, you can temporarily disable the integration for everybody. Please see Disabling the Integration for information.

To delete a user from the Pending list:

1. Locate the user you want to remove.
2. Click Options in the Action column.
3. Click Delete User.
4. In the confirmation screen, click Delete User.

If the user has already enrolled a device, you can remove their passwordless login access by performing the same steps in the Enrolled list.

1. Locate the user you want to remove.
2. Click Options in the Action column.
3. Click Delete User.
4. In the confirmation screen, click Delete User.

📘

Status Quo

In neither case are you removing the user from your Azure domain; you’re removing only their ability to complete the Azure login with HYPR passwordless authentication. If they could login before with a password, they’ll still be able to do so now.

Activating the Integration

When your users have completed the enrollment process, you can activate the integration.

📘

There Can Be Only One

After you activate the integration, the option to enroll users in bulk is not available; you can only invite users individually. For this reason, HYPR suggests you enroll as many users as possible through the bulk option before you turn on the integration.

Once you activate the integration, the Azure login flow will change for all enrolled users. Please review the What Will Happen in Azure section and make sure you’re ready to communicate the changes to your organization.

To activate the integration:

1. Go to the Current Integrations screen in the HYPR Control Center and click on the Azure AD integration.

2. Go to the Integration Settings tab and click Go Live in the Routing Rules section.

3. The Enable Integration dialog lists several PowerShell commands you’ll need to run in order to turn on the integration in Azure, with the appropriate values pre-populated where necessary. You can run these commands from any Windows machine.

4. After you’ve run the PowerShell commands, come back and click Go Live in the dialog.
5. Click Close.

Once the integration is live, you’ll see the status icons change on the Integration Settings page.

Enrolling Users after the Integration Is Live

When new hires join your company, you’ll need to invite them to enroll so they can use passwordless logins for Azure-based applications. The process you follow to enroll users if the integration is already live is different from the enrollment steps you perform before you activate the integration.

If you’ve secured your corporate email using Azure, new users won’t be able to access their email account until they’ve successfully registered a device with HYPR. In this case, you can optionally send the invitation to a personal email address instead.

📘

It's Not Personal

Even if the email goes to the user’s personal email address, they’ll still be enrolled using their corporate email account.

1. Go to the Integrations screen in the HYPR Control Center and click the Azure AD integration.
2. Go to the User Management tab and click Enroll Users.
3. Locate the user you want to invite. Either copy the default corporate email address or enter a personal email address.

5. Click Send.

Viewing the Audit Trail for the Integration

You can view user and system activity related to the integration through the Audit Trail feature. For example, you can see whether specific users have successfully enrolled or check the date and time the integration went live. HYPR Support may also ask you to verify activities or events by looking at the Audit Trail.

1. Go to the Integrations screen in the HYPR Control Center and click the Azure AD integration.
2. Go to the Audit Trail tab.
3. Use the calendar field to specify the time period you want to view.

A single activity can sometimes generate several Audit Trail events. In this case, the value in the Trace ID column will be the same, letting you see which events come from the same activity. In the image above, for example, the two events related to magic link creation have the same trace ID.

To see detailed information on a specific event, click the arrow next to the timestamp.

To export detailed information on all or selected events, check one or more boxes in the left column, then click Export Selected. The content is downloaded to your local machine as a .csv file.

Disabling the Integration

To temporarily deactivate the Azure AD integration:

1. Go to the Integration Settings page and click the Disable button under the Integration Status section.

2. The Disable Integration dialog lists several PowerShell commands you’ll need to run in order to disable the integration in Azure, with the appropriate values pre-populated where necessary. You can run these commands from any Windows machine.

3. After you’ve run the PowerShell commands, come back and click Disable in the dialog.

Disabling the integration has the following effect:

• The login flow for Azure-based applications reverts to username + password

The HYPR Control Center will remember which users were enrolled so you can reactivate the integration later if desired.

📘

Parting is Such Sweet Sorrow

Before disabling the integration, please make sure the enrolled users are aware that they’ll no longer be able to use their mobile devices to login, and must know their password to access their Azure-based apps.

Deleting the Integration

If you want to permanently remove the integration, go to the Integration Settings page and click the Delete Integration button under the Delete Azure AD Integration section.

To confirm, you’ll need to type AZURE on the Verify Integration Deletion dialog, then click Delete Integration.

📘

Tabula Rasa

The effects of deleting the integration are the same as disabling it (see Disabling the Integration). However, deleting the integration will also clear the list of enrolled users in the HYPR Control Center. If you decide to add the integration again later, you’ll need to re-enroll your users from scratch.

Frequently Asked Questions

Q: Should I enroll users before or after I make the integration live?

A: At the moment, you can only bulk enroll users before the integration goes live. After the integration is live, you must enroll users individually. For this reason, it may be more convenient to enroll as many users as possible before you make the integration live. They can register a device in preparation but will continue to login conventionally with their password until you turn the integration on. (Note that the ability to perform bulk enrollments for a live integration will be added in a future version.)

Q: Why are some users missing from the Enroll Users screen when I do Sync with Azure AD?

A: Once the HYPR Azure integration is live, new users added in Azure AD will need to be manually added to the “HYPR Group (Users Not Yet Enrolled)” group via the Azure admin portal in order for them to show up as enrollable in the HYPR Control Center. Each user must also have a First Name, Last Name, and Email address defined in Azure.

Q: What happens if users lose their mobile devices?

A: Users who no longer have access to their registered device will be unable to login until they register a new device. You’ll need to either send a login recovery email to their personal email address or generate a magic link that they can use to register a device. Both these options are available via the Enrolled list on the User Management screen.

Q: Why do users see an invalid link message when trying to register a device using a magic link?

A: For security purposes, you can ask HYPR Support to configure your magic links to only work once. However, if single use is turned on and you send the magic link to the user via a messaging app or other channel that attempts to preview the URL, the Control Center interprets the HTTP request as a registration event and will expire the link before the user has a chance to register. If this is the case, either send the link using a different method or format the link in such a way that the app doesn’t attempt to generate a preview.