Section 3.94. <AuthBy DUO>

3.94.1. Hostname, SecretKey and IntegrationKey

API Hostname, secret key, and integration key are assigned by Duo. These are mandatory parameters and there are no default values. SecretKey and IntegrationKey support special formatting characters. The formatting is done once during the module activation.

Hostname api-aabbcczz.duosecurity.com
SecretKey aaaabbbbccccddddeeeeffffgggghhhhiiiijjjj
IntegrationKey kkkkllllmmmmnnnnoooo

3.94.2. DefaultFactor

If the user does not specify a valid password or factor, this will be the factor requested from Duo. May be one of "push", "sms", "phone", "auto". Defaults to "auto".

DefaultFactor push

3.94.3. PreAuth

This optional flag specifies whether a pre-authentication is done for the user. Default is to do pre-authentication.

Duo security Auth API /preauth endpoint determines if the user is authorised to log in and returns the available authentication factors for the authorised user.

# Turn off pre-authentication
PreAuth no

3.94.4. Address

Address specifies what details in the incoming request will be used in the 'Address' field sent to Duo. The contents of the field will show up in the Duo logs. It does not actually have to be an address (which in any case is not usually available until after authentication is complete), and the default of Calling-Station-Id might be a sensible option.

Address %{Calling-Station-Id}

3.94.5. SSLVerify, SSLCAFile and SSLCAPath

The SSL* parameters allow controlling how the Duo server's certificate is verified. By default no SSL* parameters are set and the system defaults are used. SSLVerify, SSLCAFile and SSLCAPath behave as described in <AuthBy IMAP>. For more information, see Section 3.59. <AuthBy IMAP>.

3.94.6. SSLVerifyCNName and SSLVerifyCNScheme

SSLVerifyCNName sets the name which is used when verifying the hostname against the certificate presented by Duo's server. SSLVerifyCNScheme controls how the verification is done, for example, if wildcards are allowed. For more information, see IO::Socket::SSL

.

The following allow wildcard certificate name *.duosecurity.com to match.

SSLVerifyCNName duosecurity.com
SSLVerifyCNScheme http

3.94.7. SSLCertificateVerifyHook

Further certificate checks can be added with a custom hook. For more information, see SSL_verifycn_name

. The hook should return 0 or 1 for fail and pass respectively. The hook is called once for each certificate in the certificate chain.

The following arguments are passed to the hook:

$_[0] is a true or false value indicating what OpenSSL's view of the cert.
$_[1] is a C-style memory address of the certificate store.
$_[2] is a string containing certificate's issuer and owner.
$_[3] is a string containing any errors encountered or 0 if there were no errors.
$_[4] is a C-style memory address of current certificate in the chain.

3.94.8. PollTimerInterval

Number of seconds between checking for replies from the Duo Auth API server. Defaults to 1 second.

3.94.9. CheckTimerInterval

Number of seconds between checking that the Duo Auth API server is alive and responding. Defaults to 5 seconds. When set to 0, checks are disabled and FailureBackoffTime is used to control how long API is considered dead.

# Use one minute alive check interval
CheckTimerInterval 60

3.94.10. FailureBackoffTime

Number of seconds to consider the Duo Auth API server as dead after an API failure. This parameter is only used when CheckTimerInterval is set to 0 to turn off periodic API checks. When FailureBackoffTime is set to 0, API is always considered alive. Defaults to 60 seconds.

# Do not use alive polling. Allow API to remain in failed state for two minutes
CheckTimerInterval 0
FailureBackoffTime 120

3.94.11. Slots

Specifies the maximum number of simultaneous requests outstanding to the DUO Auth API server, and the maximum number of HTTP connections to the server. If more than this number of requests are waiting, then subsequent requests will be queued and sent after a reply a received from an outstanding request. Defaults to 20.

If the total number of requests that are waiting and queued exceeds 2 * Slots, a warning is logged and the API is marked dead to prevent further overload.

3.94.12. Timeout

Specifies the maximum number of seconds to wait for the start of a reply from the Auth API server. The Auth API server can take up to 60 seconds to reply. Default is 100 seconds. You should not need to change this.

3.94.13. MaxRequestTime

Specifies the maximum number of seconds to wait for a complete reply from the Auth API server. The Auth API server can take up to 60 seconds to reply. Default is 120 seconds. You should not need to change this.

3.94.14. Failmode

This optional parameter specifies whether to reject, accept, or ignore authentication when a Duo API problem occurs. Possible problems are: API call fails, API response returns an error, API response can not be parsed or API call times out. Default is to ignore. Format specifiers, such as %{GlobalVar:name}, are evaluated when the configuration is loaded. The possible values are:

accept
ignore
reject

# Reject, instead of ignore, when timeout or other API problem occurs
Failmode reject

3.94.15. ProxyHost

Specifies the name of a HTTP proxy to use to contact the Auth API server. The default is not to use any proxy.

3.94.16. ProxyPort

Specifies the port on the ProxyHost to use to contact the Auth API server.

3.94.17. EndpointPrefix

The prefix for the Auth API. Defaults to /auth/v2. You should not need to change this. See goodies/duo.cfg for how to set EndpointPrefix when using the Auth API simulator duosim.cgi.

3.94.18. Protocol

The protocol to use to connect to the Auth API server. Defaults to https. Usually there is no need to change this.