AD FS Plugin: Manual Installation

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; this step is performed automatically if using the .msi installation method

Farm-Fresh

HYPR does not keep state on a server and can be used without additional requirements beyond baseline Microsoft requirements, such as with AD FS Server Farm. See Deploying a Federation Server Farm for Windows Server 2012 R2 AD FS | Microsoft Learn.

Configure HYPR for AD FS Plugin

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

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; this step is performed automatically if using the .msi installation method
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.

Configure `hypr.json`

The settings .json file looks like this.

  "ccUrl": "https://<your-hypr-tenant>",
  "appId": "XXXXX",
  "apiKey": "hypap-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
  "logFile": "C:\\HyprADFS\\HyprADFS.log",
  "logLevel": 5,
  "qrAuth": true,
  "qrFallback": false,
  "dynamicLink": true,
  "asyncReg": false,
  "desktopSSO": false,
  "authCompletionTimeout": 60,
  "proxyServer": "",
  "proxyBypass": "",
  "proxyAutoConfigUrl": "",
  "pluginName": "HYPR Authentication"
}

The values are as follows:

Field	Description
ccUrl	URL for the HYPR tenant to which this machine will connect. EX: https://{your-hypr-tenant}
appId	The rpAppId for the HYPR RP application HYPR Passwordless will access.
apiKey	The workstation installation access token. If will start with hypap and continue in the followinf format: hypap-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX
logFile	The path for where to generate the log. Default is C:\HyprADFS\HyprADFS.log.
logLevel	The amount of logging to be generated. Default is 5. See Logging and Log Levels for a full description of the Log Levels.
qrAuth	Enable QR Authentication? Defaults to true. [ true \| false]
qrFallback	Enable QR Fallback/Manual QR entry? Defaults to false. [ true \| false]
dynamicLink	Enable HYPR Mobile App to use dynamic links for this RP Application? Defaults to true. [ true \| false]
asyncReg	Enable Asynchronous Registration? Defaults to false. [ true \| false]
desktopSSO	Is HYPRSpeed enabled? Defaults to false. [ true \| false]
authCompletionTimeout	Time in seconds before the authentication attempt times out. Default: 60
proxyServer	Use a proxy server? Defaults to null. [ true \| false]
proxyBypass	Bypass the proxy server? Defaults to null. [ true \| false]
proxyAutoConfigUrl	The URL to auto-configure proxy settings. Defaults to null.
pluginName	The label that will appear in the AD FS Intranet and Extranet Primary Authentication Methods. Default: HYPR Authentication

Make a copy of the original before making edits. Make sure to save the edited file before continuing.

HYPR AD FS Plugin Installation (Powershell)

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 as described above.
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.
=================================================================================

HYPR AD FS Plugin Installation (MSI)

Login to your AD FS server machine as an administrator.
Locate the installation package that corresponds to the AD FS release you are using; the year is contained in the filename; EX: HyprADFS2016.msi.
Unpack and copy the contents of the HYPR for AD FS Plugin package to the desired folder. The contents will be a single .msi file (HyprADFS<year>.msi) and a hypr.json file.
Open C:\HyrpADFS\hypr.json in a text editor and enter the appropriate values as described above.
Double-click the HyprADFS<year>.msi file to launch the installation.
Check the box next to I accept the terms of the License Agreement, then click Next.
The Environment Settings dialog reflects the values from the hypr.json file.
Click Install.
Be patient as the progress bar advances.
Click Finish.

Post-installation

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

HYPR AD FS Plugin's toggling of the QR Authentication and Push Notification features can be controlled by changing the following registry settings:

Key	Description
`Computer\HKEY_LOCAL_MACHINE\SOFTWARE\HYPR\HYPRAuthentication\DoNotRefreshFeatureFlags`	Turns off the refresh of the QR Authentication and Push Notification features, which occurs based on the RefreshFeatureFlagsFreq setting. [ `true` \| `false` ]
`Computer\HKEY_LOCAL_MACHINE\SOFTWARE\HYPR\HYPRAuthentication\RefreshFeatureFlagsFreq`	How often does the HYPR AD FS Plugin refresh the feature toggles? Default is 5 minutes.

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.

HYPR AD FS Plugin will make this change when it is installed.

Obsolete Files

All installation files can safely be deleted once the installation is completed. Because AD FS Plugin .DLL files are registered with .NET Global Assembly Cache (GAC), they can be deleted with rest of the AD FS files.

Retain the uninstall script so the plugin can be removed if desired.

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, check the box next to 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.hb.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 at the path defined in the hypr.json file. The default path is C:\HyprADFS\HyprADFS.log.

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

In Windows Explorer, go to C:\Users<your USERNAME>\AppData\Local\Temp. The name of the new log file will be random, it will begin with 'msi' and have the file name extension as .log. You can further identify it by the date.

To set the log file location manually:

Make sure that your AD FS service is running.
Run the following command as an administrator:

CMD msiexec -i \<MSI file path\> -l*v "path to log file"

Installation​

Assumptions​

Configure HYPR for AD FS Plugin​

Configure hypr.json​

HYPR AD FS Plugin Installation (Powershell)​

HYPR AD FS Plugin Installation (MSI)​

Post-installation​

Enablement​

SSL Requirements​

Uninstalling HYPR AD FS Plugin​

Troubleshooting​