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.

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