This plugin does not depend on the use of the original Duo login flow and enabling that feature/module is not required in order to install and use this plugin. They can even theoretically co-exist, but this hasn't been extensively tested.
Quick Setup Guide
If you're looking for a quick reference guide that assumes a basic, default, configuration, see here. Note, you really should read this page first.
Overview
This authentication plugin (DuoOIDC) supports Duo’s strong two-factor authentication using their OIDC-based integration model introduced in 2021 (Duo OIDC Auth API). This includes both the traditional prompt and the new Universal Prompt. The Universal Prompt is a major UX redesign of the older in-page iFrame prompt. In both cases, the user is redirected, via a full-frame redirect, to a Duo-hosted site using the OIDC protocol to perform second-factor authentication, and the results are made available to the IdP as a form of an OIDC ID Token. Duo's support is compliant with OIDC with a few caveats.
Like the original integration based on their WebSDK V2, this plug-in is designed to be used as a second factor of authentication, so is therefore used in conjunction with an existing ‘first-factor', usually orchestrated by the MFA login flow (see MultiFactorAuthnConfiguration).
By default, the first-factor must produce an “official” username as part of post-login canonicalization which the DuoOIDC flow can use as the Duo username in the second-factor authentication request. In unusual cases it is possible to customize the source of the username.
The result of this flow is a Java Subject containing a DuoPrincipal as well as a custom set of additional Principals, typically representing SAML AuthenticationContextClassRefs.
Plugin Installation
There are two different DuoOIDC Auth API plugin implementations. Both share the majority of their codebase, the difference being how they interact with Duo’s OIDC Provider. One is based on the official Duo WebSDK v4, and one is based on a Shibboleth implementation using Nimbus’s JOSE-JWT handling - although it is worth noting that part of the common codebase uses the Nimbus library for certain tasks irrespective of which plugin you use.
In most cases, we would suggest trying the Nimbus-based plugin first, particuarly if you plan to make use of the OIDC OP plugin as well, as this avoids a number of duplicated code libraries in the IdP. Duo built their SDK on top of a different OIDC/JOSE library stack, whereas we used Nimbus, allowing more code to be shared across the different components.
Dependencies
This module depends on the Shibboleth OIDCCommon plugin which you must install first. The installer should prevent installation if this is not in place.
Plugin | Plugin ID | Module ID | Authentication Flow ID | Latest Version | Supported IdP Version |
|---|---|---|---|---|---|
Duo Universal Prompt via the Shibboleth Nimbus Client | net.shibboleth.idp.plugin.authn.duo.nimbus | idp.authn.DuoOIDC | authn/DuoOIDC | [4.1.2, 5.0.0) | |
Duo Universal Prompt via Duo WebSDK v4 Client | net.shibboleth.idp.plugin.authn.duo.sdk | idp.authn.DuoOIDC | authn/DuoOIDC | [4.1.2, 5.0.0) |
The following table highlights the differences in their technical specification to help you decide which to install. Note, their functional specification (how it works for the end-user) is the same for either.
Feature | Duo WebSDK v4 | Shibboleth Nimbus |
|---|---|---|
Based on the official SDK | X | |
Duo Endpoint and Configuration Health Check | X | X |
Duo 2FA result token signature (HMAC) checking | X | X |
Duo 2FA result token encryption handling (not provided by Duo) | ||
Duo 2FA result token claims verification | X | X |
Duo 2FA result token nonce verification | X | |
Customizable HttpClient implementation | X | |
Customizable TrustEngine implementation | X | |
HTTP Public Key Pinning | X | X |
Supports TLS Certification Revocation Checking | X | X |
Customisable JSON response mapper | X |
For a detailed guide on how to install plugins, see here.
In summary, use the plugin command that ships with the IdP to install the plugin from either a local file pre-downloaded, from a URL or by pluginId 4.2
Installation
C:>\opt\shibboleth-idp\bin\plugin.bat -I net.shibboleth.idp.plugin.oidc.whatever
or
$ /opt/shibboleth-idp/bin/plugin.sh -i http://shibboleth.net/downloads/identity-provider/plugins/pluginName/version/URL
or
$ /opt/shibboleth-idp/bin/plugin.sh -i <plugin.tar.gz>
If installing from a local file, you need to ensure the GPG detached signature (e.g. the .asc file) is placed alongside the main plugin archive on disk.
Listing Installed Plugins
$ /opt/shibboleth-idp/bin/plugin.sh -l
or
C:>\opt\shibboleth-idp\bin\plugin.bat -l
Enabling the Module
For a detailed guide on configuring modules, see the ModuleConfiguration topic. Once the plugin has been installed, its module should be enabled automatically for you:
Check Module Is Enabled
/%{idp.home}/bin$ ./module.sh -l
...
Module: idp.authn.DuoOIDC [ENABLED]
However, if you need to enable it you can using the module command:
Enable the module
/%{idp.home}/bin$ ./module.sh -e idp.authn.DuoOIDC
Either manual or automatic module enablement will copy across the following configuration files from the jar:
Configuration files
jar:duo-oidc-authn-config.xml -> conf/authn/duo-oidc-authn-config.xml jar:duo-oidc.properties -> conf/authn/duo-oidc.properties
Automatic Flow Registration
The flow definition, default beans, and authentication flow descriptor are loaded automatically from well-known location(s) from the plugin’s classpath. The default behavior configured in those files can be overridden via the two configuration files shown above.
Systems upgraded to V4.1 are also likely to require adding the idp.searchForProperties=true property to their idp.properties file, or else an explicit reference would have to be added to the new property file added by the module. It's best to clean up the property situation prior to using plugins that add their own.
Once installed and enabled, you will then need to start configuring the flow.