NAV Navbar

Introduction

Notakey Authenticator plugin for AD FS is standard AD FS service plugin that integrates in your SSO Web based application authentication workflow.

System Requirements

OS Type Minimum Version
Server Windows Server 2012 R2

Compatible with AD FS 4 (Windows Server 2016) and AD FS 5 (Windows Server 2019).

Installation

Standard plugin distribution comes as MSI package NotakeyAdfsMfaPluginInstaller-<version>.msi and can be install normally by running msi or deployed automatically using distribution tools. MSI install is not registered automatically with AD FS, this has to be done by execution of install scripts. Power Shell install and uninstall scripts are included with package and are installed in program directory, normally in %ProgramFiles(x86)%\Notakey Latvia\Notakey AD FS MFA plugin.

You will be asked to apply MFA authentication policy and restart AD FS services during install. The script also creates the event log source Notakey ADFS that the plugin writes to.

Install service with PS> AdfsPluginInstall.ps1 from a user with administration privileges. Uninstall with PS> AdfsPluginUninstall.ps1.

Upgrade

Install the new MSI package over the installed version and run PS> AdfsPluginInstall.ps1 again. Do not uninstall first. This also applies to an upgrade from version 1.1.67 or older: do not run the old AdfsPluginUninstall.ps1, it clears the whole list of additional authentication providers of the farm. The new MSI package replaces the scripts. The script registers the new version and keeps the additional authentication providers that are enabled in the farm, including the Notakey provider if it was enabled.

In a farm keep this order:

  • Install the new MSI package and run PS> AdfsPluginInstall.ps1 on every secondary server. On a secondary server the script only installs the libraries. The old version stays in place next to the new one and keeps working. Do not restart AD FS services yet.

  • Install the new MSI package and run PS> AdfsPluginInstall.ps1 on the primary server. This registers the new version for the farm.

  • Restart AD FS services on the secondary servers after they have synchronized with the primary server (every 5 minutes by default, see LastSyncTime of PS> Get-AdfsSyncProperties). Until then they keep working with the old version.

In a farm with SQL Server every server reports itself as primary. Run PS> AdfsPluginInstall.ps1 -LibrariesOnly on all servers except one, then PS> AdfsPluginInstall.ps1 on the last server, then restart AD FS services on the others.

Before it registers a version, for an upgrade or for the first installation, the script asks whether the other servers of the farm already have it (-Force skips the question; only a farm that AD FS reports as having one server is not asked).

While the new version is being registered on the primary server (a few seconds), sign-ins that require MFA can fail.

The script remembers the version it registered in the registry value RegisteredAssembly under HKLM\SOFTWARE\Notakey\AdfsMfa and does not register the same version twice. The value belongs to one server, the registration to the whole farm. If another server registered a different version in between, for example after the primary role was moved, delete the value and run the script again.

The library of the old version stays in the GAC after an upgrade. It is not used any more and is removed by PS> AdfsPluginUninstall.ps1.

A sign-in that is waiting for the phone approval while a server is upgraded may show an error. The user has to start the sign-in again. In a farm this can happen until all servers run the same version.

Uninstall

PS> AdfsPluginUninstall.ps1 removes only the Notakey provider. Other additional authentication providers stay enabled. If Notakey is the only provider, the script says so and asks before it continues: without any provider, sign-ins that require MFA fail until a provider is enabled again.

In a farm keep this order, for the reason given in the warning in Upgrade:

  • Run the script on the primary server.

  • Wait until the secondary servers have synchronized with the primary server (LastSyncTime of PS> Get-AdfsSyncProperties).

  • Run the script on the secondary servers. The script shows the time of the last synchronization and asks before it removes the libraries.

In a farm with SQL Server run PS> AdfsPluginUninstall.ps1 on one server and PS> AdfsPluginUninstall.ps1 -LibrariesOnly on the others.

Workflow

  • User authenticates with standard username and password
  • If 2FA enabled per user group and zone (extranet, intranet) user is sent authentication request automatically
  • User approves authentication request on his mobile device
  • Logon is successful and AD FS redirects user to requested Service Provider

Issued claims

MFA plugin upon successful authentication request processing issues the following claim: “http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod” = “http://schemas.microsoft.com/claims/multipleauthn”

Plugin configuration

All configuration is done using Windows registry. This allows flexible deployments using Group Policy, please look in documentation of GPO how to deploy registry values in domain on per-machine basis. Please note that changes in registry based configuration require AD FS service restart.

This can be done in PS using th following commands:

Stop-Service -Name adfssrv -Force
Start-Service -Name adfssrv

Configuration

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Notakey]

[HKEY_LOCAL_MACHINE\SOFTWARE\Notakey\AdfsMfa]
"ServiceURL"="https://demo.notakey.com/api/"
"ServiceID"="65af8d56-b7d9-49b9-86c6-595dc440d933"
"MessageTtlSeconds"=dword:0000001e
"MessageActionTitle"="ADFS Login"
"MessageDescription"="Proceed as {0}?"

Description of configuration options

Name Type Default Description
ServiceURL String <none> API endpoint URL. Has to end with /api/, this value must be present for service to function.
ServiceID String <none> Service ID as displayed in NAS dashboard, this value must be present for service to function.
MessageTtlSeconds DWORD 300 The validity duration of auth request in seconds.
MessageActionTitle String AD FS login request Title for auth request.
MessageDescription String Proceed with login for user {0}? The message body of auth request.
ApiBindTimeoutSecs DWORD 10 Timeout in seconds for API binding request.
ApiRequestTimeoutSecs DWORD 5 Timeout in seconds the MFA plugin waits for response from API.
DebugEnable DWORD 0 Set to 1 to enable detailed logging in Application EventLog.

Installing MFA plugin in AD FS farm

  • Install the MSI package and run PS> AdfsPluginInstall.ps1 on every secondary server. On a secondary server the script installs the libraries and does not change the AD FS configuration.

  • Set the plugin configuration in the registry on every server.

  • Install the MSI package and run PS> AdfsPluginInstall.ps1 on the primary server. This registers the provider for the farm.

  • Restart AD FS services on the secondary servers after they have synchronized with the primary server.

The secondary servers come first for the reason given in the warning in Upgrade. In a farm with SQL Server use PS> AdfsPluginInstall.ps1 -LibrariesOnly on all servers except the last one.

Content Security Policy on Windows 2019 and later

The plugin checks the status of the authentication request on the AD FS server. The sign-in page does not call the Notakey API from the browser, so the default Content-Security-Policy header of AD FS does not have to be changed.

While the user has not answered on the phone, the sign-in page submits its form to AD FS every 3 seconds, so a waiting sign-in shows as a series of POST requests in the AD FS and proxy logs. The page stops when the request is approved, rejected or expired, at the latest 30 seconds after the request lifetime (MessageTtlSeconds). If the Notakey API cannot be reached, the error page is shown after three failed status checks in a row.

Versions up to 1.1.67 required a modified header that allowed the Notakey API domain. If this header was set only for the plugin, restore the AD FS default after all servers in the farm are upgraded:

Set-AdfsResponseHeaders -SetHeaderName "Content-Security-Policy" -SetHeaderValue "default-src 'self' 'unsafe-inline' 'unsafe-eval'; img-src 'self' data:;"

More information

Troubleshooting

Plugin writes error and status logs to Windows EventLog service, please check there for issues. The sign-in page shows the user an error code only. The cause is written to the Application event log (source Notakey ADFS) of the server that handled the sign-in, in an entry that starts with the same error code and the AD FS context id of the sign-in. For codes 1114, 1122 and 5642 the entry also names the user.

The event log source is created by PS> AdfsPluginInstall.ps1, not by the MSI package. Run the script on every server, also after installing the package only to upgrade, and restart AD FS services afterwards: the plugin checks for the source when AD FS loads it and logs nothing without it.

Error codes

Code Description
1122 Authentication request cannot be created, the API returned no request
1114 Authentication request cannot be created: the user is not found in the service, the service ID is wrong or the API cannot be reached
1111 Missing identityClaim value from AD FS
1124 Error reported by AD FS during the MFA step
7678 Missing ServiceURL configuration value
9375,9376 Missing plugin configuration, configuration key not present
9377 Missing plugin ServiceURL,ServiceID or other mandatory configuration value
5642 The status of the authentication request cannot be checked: the API cannot be reached or does not know the request