Once you have configured a Shibboleth ‘Protected Application’ and enabled support for the Universal Prompt in the Duo Admin Panel (see also Duo Universal Prompt), you'll need to copy across your client ID, API hostname and client secret into the conf/authn/duo-oidc.properties file to form your Duo Integration. The client ID and secret will likely appear as integration key and secret key until you make your first request using the new AuthAPI i.e. actually use this plugin for authentication. Note, you may want to keep the client secret in credentials/secrets.properties for consistency with other IdP secrets

Next, you need to specify a redirection URI as per the OAuth2.0 specification (RFC6749). This is the endpoint the Duo Universal Prompt will redirect the end-users user-agent (browser) to after successful second-factor authentication. By default, Duo does not require you to pre-register redirect URIs (you can request this if desired),  instead taking one supplied by the IdP inside a signed JWT request object. This opens a few different possibilities depending on which of the two clients you choose. The simplest, supported by both clients, is to define a static idp.duo.oidc.redirectURL property in the conf/authn/duo-oidc.properties file:

Redirect URI

idp.duo.oidc.redirectURL = https://<hostname>:<port>/idp/profile/Authn/Duo/2FA/duo-callback

Where <hostname> and <port> match that of your running IdP - the port can be omitted if your IdP uses the standard HTTP/HTTPS port e.g. 80 and 443 respectively. You are free to change part of that path i.e. Authn/Duo/2FA by setting the idp.duo.oidc.externalAuthnPath property. Although in most cases there is little reason for doing so. The endpoint itself needs only be accessible by the end-user’s user-agent (browser).

Alternatively, you can let the plugin determine the redirect URI from the Host header sent from the client that issues the 'first' Duo 2FA request. To do so, comment out the idp.duo.oidc.redirectURL property and then, in order to prevent HTTP Host header injection attacks (and possibly leaking your authorization code to a malicious actor), declare one or more comma-seperated allowed 'origins' [RFC6454] in the property idp.duo.oidc.redirecturl.allowedOrigins. Each origin is a combination of scheme, host, and port. For schemes where the default port is used e.g. HTTPS on port 443, the port can be omitted. For example, assuming a production IdP has a hostname of prod.example.com using the HTTPS scheme over the default port, and a matching development IdP has a hostname of dev.example.com running on a custom port 8443, the following origins would be sufficient:

Allowed Origins

idp.duo.oidc.redirecturl.allowedOrigins = https://prod.example.com, https://dev.example.com:8443

This can be useful if you want to keep a single generic configuration between development, staging, and production servers, etc.

Further to this, if you are using the Shibboleth Nimbus client, the redirect URI will be created dynamically from the Host header per-request - there is no extra configuration for this, it works per-request by default. This could be useful, for example, if a single IdP instance is serving requests from more than one virtual-host, and each Duo 2FA request will need to be redirected back to the originating Hostname in order to successfully complete the request.

As an advanced configuration option, you can specify more than one Duo integration and use a runtime function to determine which is used per authentication request. 

Given that Duo's 'second-factor' authentication runs after a 'first-factor' authentication method, you will also need to enable the "idp.authn.MFA" module in addition to an appropriate first-factor (e.g., the Password flow module, "idp.authn.Password"), and typically will need to configure the MFA flow to make use of this one as a second factor.

The flow supports a secondary integration allowing use of the Duo AuthAPI for non-browser use cases such as SAML ECP. To enable support for the AuthAPI, you will need to define an additional integration with Duo. A second set of properties is defined to allow this.

Also, the default settings for this login flow mark it as not supporting non-browser use. This needs to be adjusted by setting the idp.authn.DuoOIDC.nonBrowserSupported property.

By default, a built-in HttpClient bean is used to communicate with the Duo AuthAPI with fairly vanilla TLS behavior that relies on the system defaults. It's possible to customize this heavily using a pair of beans. More advanced documentation is in the HttpClientConfiguration topic.

Here we describe an example MFA flow using both the MFA and Password flows (in addition to the new DuoOIDC flow). Of course, this example assumes you have also enabled those modules in addition to this plugin/module, as per their documentation pages.

For testing, the credential store of the Password flow can be configured from a simple flat file of usernames/passwords, for example, using the HTPasswdCredentialValidator in conf/authn/password-authn-config.xml as shown below. If this file is missing, you have not yet enabled the "idp.authn.Password" module.

Example password validator

Or, you may already have configured a 'production' ready password validator e.g. using LDAP. Either way, your next step is to compose both these flows into a suitable multi-factor authentication flow. An example flow defined in conf/authn/mfa-authn-config.xml file is shown below. If this file is missing, you have not yet enabled the "idp.authn.MFA" module.

Example MFA configuration

In summary, the IdP will run the "authn/Password" flow followed by the "authn/DuoOIDC" flow. More complex business/orchestration logic can be added to the checkSecondFactor script if required, see the MFA page for a full discussion of the possibilities.

After configuring the MFA orchestration logic appropriately, you should consider how to represent the multi-factor authentication mechanism to the outside world.

As the DuoOIDC plugin typically runs after a first-factor authentication method orchestrated by the MFA flow, the MFA flow must present to the system a supportedPrincipals collection compatible with this type of authentication mechanism alongside any other factor(s) used.  In the SAML 2.0 world (and nowadays more generally, e.g., OpenID Connect) these are specified as an Authentication Context Class.

Those already set by default on the MFA flow are described by the idp.authn.MFA.supportedPrincipals property in the conf/authn/authn.properties file. (If your system has been upgraded from V4.0 or earlier, then you may not have migrated to the property-centric settings V4.1 allows, and may have the supported Principals enumerated in conf/authn/general-authn.xml.) Either way,these need to be adjusted to also include those that are also exposed by the "authn/DuoOIDC" flow.

This flow defaults to an example set defined by the idp.authn.DuoOIDC.supportedPrincipals property in conf/duo-oidc.properties. If not set, it will fall back to the definition of the idp.authn.Duo.supportedPrincipals property.

As for what these values should be:

For more advanced supportedPrincipal configurations, see below.

The plugin itself does not provide a native IdP view to customize because all second-factor authentication interactions occur on a Duo-hosted site to which the IdP redirects the user-agent (browser). See the Duo Admin Panel to see what customizations are possible on the Duo site. It is important to note that unsuccessful second-factor authentication terminates on the Duo site. The IdP will not receive notification of the failure, and hence authentication failure cannot be propagated further to the SP.

The non-browser variant has no UI and relies on a set of HTTP request headers from the client. Authentication relies on knowing the type of Duo factor to use, the device to use, and occasionally a passcode. Often none are needed and the whole process is automatic (the factor and device are defaulted to "auto"). Specifying a device is generally done using a name the user must associate with the device themselves. Some factors rely on a passcode being supplied.

The headers can be changed but default to:

• X-Shibboleth-Duo-Factor

• X-Shibboleth-Duo-Device

• X-Shibboleth-Duo-Passcode

Factor is one of "auto", "push", "phone", or "passcode". The "sms" factor does not work, but will fail while resulting in the issuance of codes via SMS for subsequent use.

By default, the Duo flow is designed to operate with a username derived from one of:

• a pre-existing session

• a previously executed login flow

Configuring it to run after a 'first-factor' flow will automatically satisfy this requirement, and allows you to supply a canonical username from a previous method into the Duo integration, which is typically the best approach.

If you need a more flexible approach, you can configure a bean named shibboleth.authn.DuoOIDC.UsernameLookupStrategy of type Function<ProfileRequestContext,String>, which can be defined in conf/authn/duo-oidc-authn-config.xml. The function returns the canonical username to use and can introspect the ProfileRequestContext if required.

Both plugin variants are, by default, configured with the same static set of ‘pinned’ root certificate authority certificates (trust anchors). As a result, the chain of trust associated with the end-entity certificate presented by the Duo API must be anchored by one of these root authorities and no other e.g. not the default set provided by the JDK. The current set of pinned root certificates are listed in the table below:

The Duo WebSDK v4 plugin uses public-key hash pinning, whereas the Shibboleth Nimbus plugin pins the entire CA certificate. The set of pinned hashes/certificates can be overridden for each plugin by including one of the following beans in the conf/authn/duo-oidc-authn-config.xml file:

For the Shibboleth Nimbus plugin - the values in the list are any valid Spring Resource:

Override Shibboleth Nimbus Pinned Trusted Certificates

For the Duo WebSDK v4 plugin - the values in the list are the public key hashes of pinned certificates:

Override Duo WebSDK v4 Pinned Trusted Certificates

For a basic configuration, you set the supportedPrincipals property on both the "authn/MFA" and "authn/DuoOIDC" underlying AuthenticationFlowDescriptor objects. These are copied across as Principal objects to the resulting Java Subject after successful authentication. If you need greater granularity, you can configure custom Principal sets in the following ways:

• Directly on the DuoOIDCIntegration bean. This is useful if you have more than one Duo integration and want one to satisfy a request the other does not, usually due to different policies or factors supported on the Duo end. This works the same as the original Duo integration.

• Via a strategy function. This allows runtime decisions about Principal to be made from the Duo 2FA result token.

Both are described below.

Directly on the DuoOIDCIntegration

You can define Principal sets per Duo Integration. This is particularly useful if you have more than one integration, and want each to satisfy a different Authentication Context Class Reference requested by a Service Provider. In the examples, the bean properties set are purely examples, they could be set inline or rely on property names of your own choice.

Per Integration Supported Principals

Context to Principal Mapping Strategy

If you want to add Principals to the Java Subject based on runtime information received inside a Duo result (authentication) token, you can add a Java bean named shibboleth.authn.DuoOIDC.ContextToPrincipalMappingStrategy that could, for example, inspect the JWT ClaimsSet of the Duo token. The type of this bean is Function<ProfileRequestContext,Collection<Principal>> (input is the profile request context tree, and the output is the collection to inject into the Subject).

The following example script adds the ACR "http://example.org/ac/classes/mfa/strong" to the Java Subject if the 'duo_push' two-factor authentication method was used (this is not a commentary on the "strength" of push-based MFA, strictly an example).

Example Context To Principal Mapping Strategy

It is important to note that if the mapping strategy bean is defined, the default supportedPrincipals of the underlying flow descriptor are not added to the Java Subject irrespective of the value of the property idp.authn.DuoOIDC.addDefaultPrincipals. Instead, alongside those added by the Function, only a DuoPrincipal, and any Principals defined on the DuoOIDCIntegration itself are added.

The following JSON listing shows an example of the current Duo JWT ClaimsSet for reference when constructing a mapping strategy. Refer to Duo's documentation as the final word on the subject.

Duo JWT ClaimsSet

As is common for OIDC Providers, Duo presents an HTTP API for the IdP to communicate with directly as a callback. With the Shibboleth Nimbus plugin, you have the option to override the default HttpClient object used during that communication by specifying your own HttpClientFactoryBean bean named shibboleth.authn.DuoOIDC.nimbus.HttpClient.

It is then up to you what 'security' features you add to this client e.g. certificate trust, alongside standard connection properties such as connection timeouts.

The default client already contains enough sensible, overridable, defaults that it would only be in very unusual cases that you would want to override it but is a standard approach to allow for it.

If you need to support multiple sets of Duo integration parameters, you can implement a Function<ProfileRequestContext,DuoOIDCIntegration> in Java or a script in a bean named shibboleth.authn.DuoOIDC.DuoIntegrationStrategy, which can be defined in conf/authn/duo-oidc-authn-config.xml.

As an example let's say you want to create a table that maps certain services to a particular integration, and uses a separate default for everything else. You can implement this with a simple map and a script that operates on it. In the examples, the bean properties set are purely examples, they could be set inline or rely on property names of your own choice.

Multiple Duo Integrations

Neither plugin/client is configured by default to check the revocation status of the certificates presented during the TLS handshake. Generally, there are three options for this:

1. Revocation checking from a Certificate Revocation List defined in a local store.

2. Revocation checking from a Certificate Revocation List fetched from a distribution point defined in the certificate.

3. Revocation checking from querying an Online Certificate Status Protocol (OCSP) endpoint defined in the certificate.

To configure revocation checking with the Duo WebSDK v4 plugin, use the normal Java Trust Manager system properties (see the CertPathDocs).

To enable revocation checking with the Shibboleth Nimbus plugin, you will need to set the property idp.duo.oidc.nimbus.checkRevocation to true in the conf/authn/duo-oidc.properties file *and* do one or more of the following:

1. Add one or more 'approved' (issuer and signature verified) static CRLs as Resources to a list bean named shibboleth.authn.DuoOIDC.tls.CRLs to the conf/authn/duo-oidc-authn-config.xml file.

2. Enable CRL checking from an online distribution point via the system property com.sun.security.enableCRLDP (as described in the CertPathDocs)

3. Enable OCSP via the security system property oscp.enabled (as described in the CertPathDocs)

Note that Duo does not support OSCP stapling, so this is not an option at this stage.

Before each Duo 2FA request, a back-channel lookup is made to Duo’s health check endpoint to determine if the Duo servers are accessible and accepting requests. If for some reason they aren’t, the 2FA attempt fails but the IdP’s authentication flows resume. This is a standard part of Duo’s 2FA workflow. The benefit of this approach is, it occurs before the URL redirect in the browser, and if the Duo 2FA endpoint were not available the IdP remains in control of the authentication process. Otherwise, the user’s browser might timeout during the 2FA request, or the user might get stuck on an error page of some kind.

However, this involves an extra, frequent, back-channel network lookup and as such is subject to the same reliability/availability issues as the actual 2FA request. From investigation, it appears possible to bypass this check and still have the 2FA proceed as normal. Consequently, from v1.3.0 onward we have included a property (idp.duo.oidc.healthcheck.enabled) that allows the deployer to turn off this check.

Since v1.3.0 it is possible to enable audit logging for Duo2FA interactions by setting the property idp.duo.oidc.audit.enabled to true in /conf/authn/duo-oidc.properties. From v1.4.0 onward you also need to enable the general authentication audit logging on the IdP using the property idp.authn.audit.enabled in /conf/authn.properties.

Once enabled, audit log statements are routed through a logger named Shibboleth-Audit.DuoOIDC. From v1.4.0 onward, you can change the name of this logger using the property idp.duo.oidc.audit.category in /conf/authn/duo-oidc.properties.

Without further configuration, the audit statements will appear in the normal idp-audit.log log file. This may be sufficient for your needs, if not and you would rather those exclusively appear in a new audit log file, you will need to add a new Logback appender and logger to the logback.xml file, for example:

Audit Format

The default audit format is shown below (the fields are described in the table underneath).

Custom Audit Format V1.3.0

For version 1.3.0, the audit format can be adjusted by specifying your own bean, shibboleth.authn.DuoOIDC.AuditFormattingMap, in /conf/authn/duo-oidc-authn-config.xml.

Custom Audit Format V1.4.0+

For version 1.4.0+, the audit format can be adjusted using the idp.duo.oidc.audit.format property in /conf/authn/duo-oidc.properties.

Audit Logging Fields

These beans are specific to the Duo WebSDK-based plugin only:

These beans are specific to the Nimbus-based plugin only:

These beans refer to the Duo Auth API (non-OIDC) which supports non-browser flows.

The DuoOIDC-specific properties defined in conf/authn/duo-oidc.properties follow:

The below table are properties that only apply to the Shibboleth Nimbus plugin:

The general properties configuring this flow via authn/authn.properties are:

As a non-password based flow, the supportedPrincipals property defaults to the following XML: 

In property form, this is expressed as:

idp.authn.DuoOIDC.supportedPrincipals = saml2/http://example.org/ac/classes/mfa, saml1/http://example.org/ac/classes/mfa

However, this default is (obviously) intended purely as an illustrative example of how to define your own values, as there are no standard ones to use.

To replace the internally defined flow descriptor bean, the following XML is required:

In older versions and upgraded systems, this list is defined in conf/authn/general-authn.xml. In V4.1+, no default version of the list is provided and it may simply be placed in conf/global.xml if needed.