This IFRAME-based integration with Duo Security is now deprecated at the request of the company, which is requiring that customers begin to migrate to their new integration strategy based on OpenID Connect and a full-frame redirect (effectively a proxied authentication via OIDC to Duo Security's servers).
The replacement feature is available as a plugin to V4.1+ of the IdP software and will not be shipped with it. This original integration will be removed at a future time not yet determined, as this will depend on Duo Security's timeline for retiring their support. We have no plans to remove the feature prior to Duo's retirement of the option. (The warning in the log does say "next major version" but that's an artifact of the standard method we invoke to log deprecations.)
The authn/Duo login flow is a native implementation of the Duo Security product's DuoWeb authentication interface that leverages an embedded IFRAME. Duo is a popular commercial solution for adding additional authentication factors to existing credentials. It is designed to be used in conjunction with an existing factor, usually a password. It is therefore implemented in a manner that assumes an earlier authentication step has already been completed, and is designed to be used in conjunction with the MFA login flow as part of a combined workflow.
The result of this flow is a Java Subject containing a DuoPrincipal. Note that no actual "username" is produced; it is assumed that one or more other login flows will contribute content to the Subject suitable for an existing subject canonicalization flow to operate on the aggregate result. All this means is that it assumes the Password login flow (or some other traditional mechanism) is used as part of an MFA workflow, and the result will normally be correct.
There is also support for the Duo AuthAPI in support of non-browser profiles like ECP. Similarly to the Password flow, it supports a set of HTTP request headers to communicate factor, device, and/or passcode values from a client to the IdP and the flow will consume them and attempt a native Duo authentication without use of the IFRAME. For normal profiles, the flow will "fall into" the IFRAME UI, much as the Password flow falls into an HTML form, but for non-browser profiles like ECP, the authentication simply succeeds or fails and the result is passed back.
Enabling Module (V4.1+)
For V4.1+, configuring and using this feature requires that you first enable the "idp.authn.Duo" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.
For a typical integration, configuration of the Duo flow itself is very simple: just fill in your Duo integration settings (they're in the Duo console if you have access to it, see below) in conf/authn/duo.properties. This assumes you have a single Duo integration, which is true for most sites. There are more advanced scenarios that can be accommodated, and details are included below.
The other important step is to define something to represent this mechanism to the outside "SAML" world as an authentication context class by adjusting the supportedPrincipals property on the Duo (and probably MFA) flow descriptors in conf/authn/general-authn.xml (V4.0) or the idp.authn.Duo.supportedPrincipals property (V4.1+).
There is no "standard" context class (or SAML 1 authentication method) to represent most forms of MFA, and moreover, experience has shown that it's a bad idea to create a strong coupling between applications and the exact technologies that you use for authentication.
As a result, the default configuration contains only a placeholder value to use that you will need to change, but there is currently no standard value to use. One possible choice to consider is the REFEDS profile, but your particular deployment may or may not satisfy its requirements. Regardless of specifics, the approach is a good one in general: a generic URI representing the use of MFA.
Whatever value is used, in most cases you can simply add it where needed, and the Duo flow will automatically contribute that value to the results it builds.
AuthAPI and Non-Browser/ECP Use
To enable support for the AuthAPI, you typically 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 removing the nonBrowserSupported property setter on the "auth/Duo" flow descriptor bean in authn/general-auth.xml (V4.0), or setting the idp.authn.Duo.nonBrowserSupported property (V4.1+).
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, but an example is included below under Advanced Configuration.
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:
Factor is one of "auto", "push", "phone", or "passcode". The "sms" factor does not work, but in V4.1+ it 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 API, which is typically the best approach.
If you need a more flexible approach, you can configure a Function<ProfileRequestContext,String> in a bean named shibboleth.authn.Duo.UsernameLookupStrategy, which can be defined in conf/authn/duo-authn-config.xml
Multiple Duo Integrations
In the event that you need to support multiple sets of Duo integration parameters, you can implement a Function<ProfileRequestContext,DuoIntegration> in Java or a script in a bean named shibboleth.authn.Duo.DuoIntegrationStrategy, which can be defined in conf/authn/duo-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 conjunction with the above feature, you can also cause the resulting Java Subject to carry Principals specific to a given Duo integration, which is useful if you want to segregate the integrations during SSO. That is, given two integrations A and B, you may want the use of A to satisfy a request that would require B, but you may not want that.
By default, since the Principals added into the result come from the underlying login flow descriptor for "authn/Duo", a request that uses either integration will produce a result that will be usable on any later request for Duo authentication. To prevent this, you need to do a couple of things:
Disable the addDefaultPrincipals feature for the Duo flow:
V4.0 – Create a bean in authn/duo-authn-config.xml named shibboleth.authn.Duo.addDefaultPrincipals set to Boolean.FALSE
V4.1+ – Set idp.authn.Duo.addDefaultPrincipals property in authn/authn.properties to false
Define separate Principal collections unique to each integration and associate them with the Duo integrations you define
Building on the previous example, the following shows how this might look. The approach is different in that the choice of Duo integration to use is implemented by evaluating each one to pick the first one that satisfies the request. This works in conjunction with triggering the integration to use based on SPs requesting the AuthnContextClassRef defined below (or setting it in a relying party override).
Multiple Integrations with Distinct Principal Sets
As a REST API, the AuthAPI requires an HTTP client to access the API and to secure it. Obviously this is a particularly sensitive API to rely on, and while the defaults should be relatively safe, that isn't a great thing to assume. It would be a sensible thing to explicitly control the TLS verification of the Duo API certificate so that there are no nasty surprises. Unfortunately this creates other maintenance responsibilities; companies like Duo don't think that blindly trusting 100 CAs or more is a problem and they change their CA any time they feel like it. Of course, it is a problem. All we can do is provide the tools to manage this more carefully, but we can't fix the web.
Assuming you want to do this, the following example to place in conf/authn/duo-authn-config.xml will ensure that the root CA used by Duo is a specific CA. It assumes you've pulled down and stored the CA certificate in a file, and it also assumes the subject name Duo uses continues to be the same wildcard, which seems likely. But if they change their CA, as they probably will someday, you won't know and it will break, so if that bothers you, you should speak to Duo about it.
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. Some suggestions are mentioned earlier under General Configuration.
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.