Versions Compared

Old Version 255

changes.mady.by.user Scott Cantor

Saved on

compared with

New Version 256

changes.mady.by.user Philip Smart

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleCertificate Revocation Checking

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.

Expand
titleDuo2FA Audit Logging (1.3.0)

Since v1.3.0 it is possible to enable audit logging for Duo2FA interactions. To enable audit logging, set the property idp.duo.oidc.writeaudit to true. Once enabled, audit log statements are routed through a logger named Shibboleth-Audit.DuoOIDC.SSO using the format below(the fields are described in the table underneath):

Code Block
%AAF|%a|%T|%DuoU|%DuoReqS|%DuoRespS|%DuoTXID|%DuoDID|%DuoDN|%DuoR|%DuoF

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:

Code Block
<appender name="IDP_DUO2FA_AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <File>${idp.logfiles}/idp-duo2fa-audit.log</File>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${idp.logfiles}/idp-duo2fa-audit-%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <maxHistory>${idp.loghistory}</maxHistory>
        </rollingPolicy>

        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <charset>UTF-8</charset>
            <Pattern>%msg%n</Pattern>
        </encoder>
</appender>
    
<!-- Set additivity false if you do not want DuoOIDC events in the standard audit log -->
<logger name="Shibboleth-Audit.DuoOIDC" level="ALL" additivity="false">
    <appender-ref ref="${idp.audit.appender:-IDP_DUO2FA_AUDIT}"/>
</logger>

The audit format and audit extractors can all be customised if required. See the bean reference section.

Audit Logging Fields

Field

Description

AAF

The ID of the currently running authentication flow i.e. authn/DuoOIDC in this case

DuoTXID

The transaction ID contained in the Duo 2FA response

DuoDID

The ID of the device used to authenticate the user

DuoDN

The friendly name of the device used to authenticate the user

DuoR

The authentication reason

DuoF

The factor used for 2FA e.g. a Security Key or SMS.

DuoU

The username of the authenticating user sent in the Duo 2FA request

DuoRespS

The state OAuth 2.0 parameter returned in the Duo response

DuoReqS

The state OAuth 2.0 parameter sent to Duo in the 2FA request (client authorization request)

Reference

Expand
titleBeans (General)

Bean ID / Type

Default

Description

shibboleth.authn.DuoOIDC.DuoIntegration

DuoOIDCIntegration

Derived from properties in conf/authn/duo-oidc.properties

Defines a single/static Duo OIDC Integration with Duo, you can override this bean to supply a non-property-configured alternative

shibboleth.authn.DuoOIDC.DuoIntegrationStrategy

Function<ProfileRequestContext,DuoOIDCIntegration>


Optional bean to supply the Duo OIDC integration settings dynamically

shibboleth.authn.DuoOIDC.UsernameLookupStrategy

Function<ProfileRequestContext,String>

CanonicalUsernameLookupStrategy

Optional bean to supply username

shibboleth.authn.DuoOIDC.resultCachingPredicate

Predicate<ProfileRequestContext>

shibboleth.Conditions.TRUE

Bean ID controlling whether to preserve the authentication result in an IdP session

shibboleth.authn.DuoOIDC.CleanUpHook

Consumer<ProfileRequestContext>

Bean that removes the DuoOIDAuthenticationContext from the tree

A cleanup hook that is executed on successful authentication.

shibboleth.authn.DuoOIDC.jwt.claims.CleanUpHook

Consumer<ProfileRequestContext>

Bean that removes the nonce value from the DuoOIDAuthenticationContext

A cleanup hook to execute after either successful or unsuccessful claims validation

shibboleth.authn.DuoOIDC.DuoTokenClaimsVerifier

JWTClaimsValidation

DefaultDuoTokenClaimsVerifier Claims verification in accordance with the Duo specification. Also OIDC compliant for the special Duo id_token case.

Duo result token (OIDC id_token) claims verifier using a 'chain' of ClaimsValidators e.g. audience, issuer, expiration checks etc. You can either replace the claims validator completely, change some of the behavior of existing validators individually, or add to a new validation check using a custom BiFunction, see shibboleth.authn.DuoOIDC.ExtendedClaimsValidator.

shibboleth.authn.DuoOIDC.jwt.IssuerLookupStrategy

BiFunction<ProfileRequestContext, JWTClaimsSet, String>

Combines the HTTPS scheme, with the Duo API Hostname, and the Duo token IssuerPath.

Lookup strategy that returns the OIDC issuer. An issuer contains the scheme, host, and optionally, port and path components that identify the id_token issuer.

shibboleth.authn.DuoOIDC.jwt.AudienceLookupStrategy

BiFunction<ProfileRequestContext,JWTClaimsSet, String>

The clientID of the Duo Integration pertaining to the request.

Lookup the client_id for the Relying Party.

shibboleth.authn.DuoOIDC.jwt.UsernameLookupStrategy

BiFunction<ProfileRequestContext,JWTClaimsSet, String>

The authenticating principal's username from the context pertaining to the request.

Lookup the authenticating principal's username to match Duo's preferred_username field in the id_token.

shibboleth.authn.DuoOIDC.jwt.AuthTimeActivationCondition

BiPredicate<ProfileRequestContext,JWTClaimsSet>

Returns true if forced authentication has been requested by the Relying Party.

Should the auth_time field be validated for the given request?

shibboleth.authn.DuoOIDC.jwt.NonceLookupStrategy

BiFunction<ProfileRequestContext,JWTClaimsSet, String>

The nonce that was used in the authorization request and stored in the Duo authentication context.

Lookup the nonce that was used in the authorization request and should be present in the id_token.

shibboleth.authn.DuoOIDC.jwt.NonceActivationCondition

BiPredicate<ProfileRequestContext,JWTClaimsSet>

Returns true iff the id_token contains a nonce.

Should we validate the nonce value in the id_token?

shibboleth.authn.DuoOIDC.RequiredOIDCClaims

Set<String>

Used by the DefaultDuoTokenClaimsVerifier above. Defaults to those claims required by the OIDC specification (https://openid.net/specs/openid-connect-core-1_0.html#IDToken)

The names of the claims required to be present in the Duo result token (OIDC id_token).

shibboleth.authn.DuoOIDC.ContextToPrincipalMappingStrategy

Function<ProfileRequestContext,Collection<Principal>>


Map information in the ProfileRequestContext, most likely in the Duo result id_token, to a collection of Principals the execution of the flow supports. See this advanced topic.

shibboleth.authn.DuoOIDC.ExtendedClaimsValidator

BiFunction<JWTClaimsSet,ProfileRequestContext,JWTValidationException>


Optional BiFunction extension point for custom claims validation of the Duo token

...