HYPR AD FS Plugin

🚧
Beta Version
HYPR AD FS Plugin is currently in beta development. Consequently, the content on this page may change in part or wholly and without warning.

HYPR AD FS Plugin allows HYPR passwordless authentication to be used instead of username/password for accessing applications protected by AD FS. HYPR AD FS Plugin gives users the ability to manage their own devices without the need for assistance or additional websites. For administrators, it grants the freedom to apply HYPR Control Center (CC) policies to any AD FS users across the entire federation.

Installation

This section describes how to integrate the HYPR AD FS Plugin into an AD FS 2019 environment.

Assumptions

AD FS 2019 is up and running supporting at least username/password authentication for domain users (see Standing up AD FS Section, below)
You have Administrator privileges to the AD FS 2019 machine
You have AD FS externally accessible
You have a valid SSL certificate - please see SSL Requirements
- You can use a wildcard certificate if you have one
You have Administrator privileges to the HYPR CC
You have obtained the installation package for the AD FS Plugin from HYPR
The AD FS service can access the HYPR CC server directly
The AD FS service user requires write access to the registry so HYPR AD FS Plugin can generate entries and assign permissions to the created keys and values

Configure HYPR for AD FS Plugin

The following processes must be completed before installing HYPR AD FS Plugin:

Enable QR Code Authentication: see the article, Example API, for cURL commands
Add an Application. Name it something meaningful, like ADFS. Record that value for later.
- Select the new Application from the Applications list
- Click App Settings (the gear) in the upper right corner of Control Center
- Copy the name next to APP ID and save it for later use
In the left navigation pane, under Advanced Config, click Login Settings
Ensure that Enable Push Notifications is off and QR Authentication is on

Generate an Access Token to be used for the AD FS Plugin:
- In Control Center, click ADVANCED CONFIG > Access Tokens
- In the Access Tokens page, click Generate Token
- Name the token (e.g., adfs) and select the API Token radio button; then click Next
- On the Permissions screen, check the Device Registration, Authentication, and User Management boxes; then click Next

Copy the store the generated token in a password manager for later
Create another API Access Token with administrator (all) privileges, which will be used in the next step for the cURL command:
- In Control Center, click ADVANCED CONFIG > Access Tokens
- In the Access Tokens page, click Generate Token
- Name the token (e.g., adfs) and select the API Token radio button; then click Next
- On the Create Token screen, click Select All
- Copy the store the generated token in a password manager for later use
- Enable QR Code Authentication by running this cURL command, replacing the following values:
  - <rp url> with your tenant URL (e.g., https://<tenant>.hypr.com)
  - <access token> with the admin token you just created
  - <app id> with the rpAppId of your Application (e.g., “adfs”)
```
curl  
--location  
--request PUT "<rp url>/cc/api/appconfig/devicemanager"  
--header "Authorization: Bearer <access token>"  
--header "Content-Type: application/json"  
--data-raw '{  
    "baseURL": "<rp url>",  
    "rpAppId": "<app id>"  
}'
```

Once all of these are completed, HYPR Control Center is configured and ready for the AD FS Plugin Installation.

HYPR AD FS Plugin Installation (Provided by HYPR)

Login to your AD FS server machine as an administrator.
Create the folder, c:\HyrpADFS.
Unpack and copy the contents of the HYPR AD FS Plugin package to C:\HyrpADFS.
Select everything in this folder and copy the contents to C:\HyrpADFS.

Open C:\HyrpADFS\hypr.json in a text editor and enter the appropriate values. For example:

{
    "ccUrl": "https://hypr28112.gethypr.com/",
    "appId": "aDFS",
    "apiKey": "hypap-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
    "logFile": "C:\\HyprADFS\\HyprADFS.log",
    "logLevel":  5,
    "qrAuth": true,
    "proxyServer": "",
    "proxyBypass": "",
    "proxyAutoConfigUrl": ""
}

Open PowerShell as an administrator.
Change directory to C:\HyrpADFS and run .\Install\InstallADFSHyprProvider2019.ps1. The output of the script should look something like the following. Note this output is from the pre-production release of HYPR AD FS Plugin:

PS C:\HyprADFS> .\install\InstallADFSHyprProvider2019.ps1
For better protection of the ApiKey which is stored in
HKLM\Software\HYPR\HYPRAuthentication\Config registry key, make sure that
a user used to run 'Active Directory Federation Services' service has full
access right to this registry.


Please modify this script for your particular ADFS deployment.
=================================================================================
Are you Sure You Want To Proceed:: y
=================================================================================
=================================================================================
1. Save HYPR configuration to registry ...
=================================================================================
=================================================================================
2. Adding HYPR binaries to Global Assembly Cache ...
=================================================================================
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


No assemblies found matching: HyprADFSPlugin2019
Number of assemblies uninstalled = 0
Number of failures = 0
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


Assembly successfully added to the cache
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.


The Global Assembly Cache contains the following assemblies:
  HyprADFSPlugin2019, Version=1.1.2.2162, Culture=neutral, PublicKeyToken=3cab6fe929ebf634, processorArchitecture=AMD64


Number of items = 1
=================================================================================
3. Register HYPR Authentication provider ...
=================================================================================
WARNING: PS0114: The authentication provider was successfully registered with the policy store. To enable this
provider, you must restart the AD FS Windows Service on each server in the farm.
=================================================================================
4. Restarting ADFS service ...
=================================================================================
The Active Directory Federation Services service is stopping.
The Active Directory Federation Services service was stopped successfully.


The Active Directory Federation Services service is starting..
The Active Directory Federation Services service was started successfully.


=================================================================================
Please refer to the product documentation to complete the AD FS configuration.
=================================================================================

After installation, some of the configuration information is stored in the registry under Computer\HKEY_LOCAL_MACHINE\SOFTWARE\HYPR\HYPRAuthentication\Config.

📘
Federation Rules
If you are running the Active Directory Federation Services service under a service account, that account must have full access rights to this registry entry.

📘
Obsolete Files
All installation files can safely be deleted once the installation is completed. Because AD FS Plugin DLLs are registered with .NET Global Assembly Cache (GAC), they can be now deleted with rest of the AD FS files.
Retain the uninstall script so the plugin can be removed if desired.

Post-installation Enablement

The installation script does not enable the HYPR AD FS Plugin authentication, as each AD FS deployment has its own environmentally dependent authentication requirements. HYPR Authentication must be enabled in the AD FS Server Manager.
The steps here are an example of a very plain AD FS authentication flow. Even if you have a default AD FS flow similar to the one presented here, you will still need to adapt your specific post-installation configuration.

Start the AD FS Server Manager, expand Service, select Authentication Methods, and click Edit Primary Authentication Methods… on the right.
You will see HYPR Authentication as an unchecked option. Scroll down to find it if necessary.
Under both Intranet and Extranet, select HYPR Authentication according to your authentication policies. Click OK when finished.

Restart the AD FS server using the Services application.

Make sure the Allow additional authentication providers as primary option is checked.

SSL Requirements

AD FS requires a certificate for Secure Socket Layer (SSL) server authentication on each federation server in your federation server farm. The same certificate can be used on each federation server in a farm. You must have both the certificate and its private key available. For example, if you have the certificate and its private key in a .pfx file, you can import the file directly into the Active Directory Federation Services Configuration Wizard. This SSL certificate must contain the following:

The subject name and subject alternative name must contain your federation service name, such as fs.contoso.com
The subject alternative name must contain the value enterpriseregistration that is followed by the User Principal Name (UPN) suffix of your organization; for example, enterpriseregistration.corp.contoso.com

Uninstalling HYPR AD FS Plugin

The HYPR AD FS Plugin can be removed by running the uninstall PowerShell script, as follows:

Login to the AD FS server as an administrator.
Verify the AD FS server is running the Active Directory Federation Service.

In the AD FS Server Manager, right-click Service > Authentication Methods and choose Edit Primary Authentication Methods….

Uncheck HYPR Authentication in the listings, so the plugin is no longer used.

Open a PowerShell terminal as an administrator.

Change directory to C:\HyprADFS and run the uninstall script:

PS C:\Users\Administrator> cd C:\HyprADFS
PS C:\HyprADFS> .\Install\UninstallADFSHyprProvider2019.ps1
Please modify this script for your particular ADFS deployment.
=================================================================================
Are you Sure You Want To Proceed:: y
=================================================================================
=================================================================================
1. Unregistering HYPR Authentication ...
=================================================================================


Confirm
Are you sure you want to perform this action?
Performing the operation "PS0061: Remove external authentication provider: 'HYPRAuthentication'." on target
"HYPRAuthentication".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): A
WARNING: PS0103: The authentication provider was successfully unregistered from the policy store. Restart the AD FS
Windows Service on each server in the farm.
Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.




Assembly: HyprADFSPlugin2019, Version=1.1.2.2162, Culture=neutral, PublicKeyToken=3cab6fe929ebf634, processorArchitecture=AMD64
Uninstalled: HyprADFSPlugin2019, Version=1.1.2.2162, Culture=neutral, PublicKeyToken=3cab6fe929ebf634, processorArchitecture=AMD64
Number of assemblies uninstalled = 1
Number of failures = 0
=================================================================================
2. Restarting ADFS service ...
=================================================================================
The Active Directory Federation Services service is stopping.
The Active Directory Federation Services service was stopped successfully.


The Active Directory Federation Services service is starting...
The Active Directory Federation Services service was started successfully.


=================================================================================
3. Removing HYPR registry  ...
=================================================================================

Confirm the registry entry has been removed. When the plugin is installed, you will see Computer\HKEY_LOCAL_MACHINE\SOFTWARE\HYPR\HYPRAuthentication\Config.

Troubleshooting

It is important to note the location of the log files for HYPR AD FS Plugin, as they are currently the primary method of troubleshooting. The log files can be found in C:\HyrpADFS\hypr.json. The full path by default is C:\HyprADFS\HyprADFS.log.

HYPR Audit Trail Events will log normally through the HYPR AD FS Plugin.

HYPR AD FS Plugin

🚧
Beta Version

Installation

Assumptions

Configure HYPR for AD FS Plugin

HYPR AD FS Plugin Installation (Provided by HYPR)

📘
Federation Rules

📘
Obsolete Files

Post-installation Enablement

SSL Requirements

Uninstalling HYPR AD FS Plugin

Troubleshooting

🚧Beta Version

Installation

Assumptions

Configure HYPR for AD FS Plugin

HYPR AD FS Plugin Installation (Provided by HYPR)

📘Federation Rules

📘Obsolete Files

Post-installation Enablement

SSL Requirements

Uninstalling HYPR AD FS Plugin

Troubleshooting

🚧
Beta Version

📘
Federation Rules

📘
Obsolete Files