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.
Install service with PS> AdfsPluginInstall.ps1 from a user with
administration privileges. Uninstall with PS> AdfsPluginUninstall.ps1.
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 on primary server with
PS> AdfsPluginInstall.ps1 -
Sync config on slave server with
PS> Set-AdfsSyncProperties -PollDuration 1200 -PrimaryComputerName <primary-server-name> -Role "SecondaryComputer" -
Verify sync status with
PS> Get-AdfsSyncProperties -
Promote slave server to master with
PS> Set-AdfsSyncProperties -Role PrimaryComputer -
Install MSI and run
PS> AdfsPluginInstall.ps1 -
Repeat steps above on the remaining servers in the environment
Installing on Windows 2019
Installing on AD FS 5 (shipped with Windows Server 2019) requires modification of CSP header, as plugin uses API calls directly from javascript, that are forbidden by default.
Set-AdfsResponseHeaders -SetHeaderName "Content-Security-Policy" -SetHeaderValue "default-src 'self' 'unsafe-inline' 'unsafe-eval' https://<your-nas-api-domain>; img-src 'self' data:;"
More information
Troubleshooting
Plugin writes error and status logs to Windows EventLog service, please check there for issues. All user errors are codified, please check with product support for details of specific encountered code.
Error codes
| Code | Description |
|---|---|
| 1122 | Authentication request cannot be created, invalid username or service ID |
| 1114 | Unable to connect to authentication server API |
| 1111 | Missing identityClaim value from AD FS |
| 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 | Authentication request response processing error |