Page Comparison

Current File(s): conf/authn/x509-authn-config.xml, (edit-)webapp/WEB-INF/web.xml, (edit-)webapp/x509-prompt.jsp, authn/authn.properties (V4.1+)
Format: Native Spring, Properties (V4.1+)

Overview

The authn/X509 login flow leverages any surrounding mechanism you have available for TLS client certificate authentication, provided the standard servlet request attribute ("javax.servlet.request.X509Certificate") is populated. By default, this flow is configured without support for advanced authentication controls like passive or forced authentication since this is not generally possible with client certificate authentication.

The result of this flow is a Java Subject containing an X500Principal derived from the subject of the certificate, and the certificate is optionally added as a public credential of the Subject. Note that no actual "username" is produced; rather, a suitable post-login Subject Canonicalization flow must be enabled/configured to pull a suitable principal name out of the Subject.

This flow is implemented as a special case of the External flow that happens to use a supplied servlet to implement the External contract that supports extraction of the certificate from the request. Rather than customizing this flow, use the External flow directly to do more advanced things.

Note that if you have a web server that is configured to perform the certificate evaluation for you and populate a header or variable with the "username" to use based on the certificate, you almost certainly will want to use the RemoteUser flow instead. This flow pulls in the certificate as the primary result of the authentication and relies on downstream logic (often the x500 subject c14n flow) to get a username out of it.

Enabling Module (V4.1+)

For V4.1+, configuring and using this feature requires that you first enable the "idp.authn.X509" 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.

(Windows)
C:\opt\shibboleth-idp> bin\module.bat -t idp.authn.X509 || bin\module.bat -e idp.authn.X509
 
(Other)
$ bin/module.sh -t idp.authn.X509 || bin/module.sh -e idp.authn.X509

General Configuration

You can make the location dynamic via a bean of type Function<ProfileRequestContext,String> named shibboleth.authn.X509.externalAuthnPathStrategy

The shibboleth.authn.X509.ClassifiedMessageMap bean is a map of error messages to classified error conditions that isn't generally used with this handler because it usually won't return with any contextual details, but there is a default mapping supplied that signals fall-through to other login flows if no certificate is found or the certificate fails optional validation. This is done by remapping those specific error events into a "ReselectFlow" event.

The servlet that implements the authentication for this flow is configured by webapp/WEB-INF/web.xml and can be given a "trustEngine" context parameter that identifies a Spring bean ID of an OpenSAML TrustEngine that should be used to validate the client certificate chain. The best spot to define such a bean is usually conf/global.xml, as it needs to be in the root Spring context for the servlet to access it. Of course, it's often simpler and more common to do this validation using the web server itself, although that's less flexible.

An example of a PKIX-based TrustEngine declaration follows. The bean ID would need to be supplied in web.xml as the "trustEngine" context paramater to the servlet.

<bean id="my.X509AuthnTrustEngine" parent="shibboleth.StaticPKIXTrustEngine"
	p:certificates="%{idp.home}/credentials/rootca.pem"
	p:checkNames="false"
	p:verifyDepth="1" />

The servlet also supports a boolean parameter, "saveCertificateToCredentialSet", which can be set to false to prevent the preservation of the certificate in the resulting credentials to save space if it won't be used.

As always, if editing web.xml, make sure to copy it to edit-webapp/WEB-INF first and make any changes to that copy.

Reference

<list>
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:X509" />
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient" />
    <bean parent="shibboleth.SAML1AuthenticationMethod"
        c:method="urn:ietf:rfc:2246" />
</list>

idp.authn.X509.supportedPrincipals = \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:X509, \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient, \
    saml1/urn:ietf:rfc:2246

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

<util:list id="shibboleth.AvailableAuthenticationFlows">
 
    <bean p:id="authn/X509" parent="shibboleth.AuthenticationFlow"
            p:order="%{idp.authn.X509.order:1000}"
            p:nonBrowserSupported="%{idp.authn.X509.nonBrowserSupported:false}"
            p:passiveAuthenticationSupported="%{idp.authn.X509.passiveAuthenticationSupported:false}"
            p:forcedAuthenticationSupported="%{idp.authn.X509.forcedAuthenticationSupported:false}"
            p:proxyRestrictionsEnforced="%{idp.authn.X509.proxyRestrictionsEnforced:%{idp.authn.enforceProxyRestrictions:true}}"
            p:proxyScopingEnforced="%{idp.authn.X509.proxyScopingEnforced:false}"
            p:discoveryRequired="%{idp.authn.X509.discoveryRequired:false}"
            p:lifetime="%{idp.authn.X509.lifetime:%{idp.authn.defaultLifetime:PT1H}}"
            p:inactivityTimeout="%{idp.authn.X509.inactivityTimeout:%{idp.authn.defaultTimeout:PT30M}}"
            p:reuseCondition-ref="#{'%{idp.authn.X509.reuseCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:activationCondition-ref="#{'%{idp.authn.X509.activationCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:subjectDecorator-ref="#{getObject('%{idp.authn.X509.subjectDecorator:}'.trim())}">
        <property name="supportedPrincipalsByString">
            <bean parent="shibboleth.CommaDelimStringArray"
                c:_0="#{'%{idp.authn.X509.supportedPrincipals:}'.trim()}" />
        </property>
    </bean>
 
</util:list>

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.

Notes

Note that this flow is configured by default without support for non-browser profiles (namely ECP) because the X509Internal flow is a better choice when a browser isn't required. It eliminates the extra redirects (and the optional HTML UI) used by this flow.