Current File(s): conf/authn/x509-authn-config.xml, webapp/WEB-INF/web.xml, webapp/x509-prompt.jsp

Format: Native Spring

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 added as a public credential of the Subject. Note that no actual "username" is produced; rather, a suitable 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, it's better to leave it as is and use the External flow itself 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. This flow pulls in the certificate as the primary result of the authentication and relies on downstream logic (often the x500 subject canonicalization flow) to get a username out of it.

General Configuration

Use conf/authn/x509-authn-config.xml to configure this flow.

The shibboleth.authn.X509.externalAuthnPath bean is the flow redirection path to either a JSP page allowing an explicit prompt for certificate authentication (and other messaging to the user), or directly to the authentication servlet, skipping the UI (which is at /Authn/X509). These are context-relative locations, and you can use any JSP page you choose. It can be modified if needed, but in most cases modifying this to anything but one of those two choices means the External flow is likely a better choice to use.

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

The shibboleth.authn.X509.populateUIInfo bean is a flag controlling whether to populate information about the relying party for user interface customization. You can certainly disable this if you modify the first bean to directly invoke the servlet with no UI.

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. 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

Beans

The beans defined in authn/x509-authn-config.xml follow:

Bean ID	Type	Default	Function
shibboleth.authn.X509.externalAuthnPath	String	contextRelative:x509-prompt.jsp	Spring Web Flow redirection expression for the protected resource
shibboleth.authn.X509.externalAuthnPathStrategy^3.3	Function<ProfileRequestContext,String>	A constant function returning the bean value above.	A function that returns the redirection expression to use for the protected resource
shibboleth.authn.X509.ClassifiedMessageMap	Map<String,List<String>>	various	A map between defined error/warning conditions and events and implementation-specific message fragments to map to them.
shibboleth.authn.X509.resultCachingPredicate	Predicate<ProfileRequestContext>		An optional bean that can be defined to control whether to preserve the authentication result in an IdP session
shibboleth.authn.X509.addDefaultPrincipals^3.2	Boolean	true	Whether to add the content of the `supportedPrincipals` property of the underlying flow descriptor to the resulting Subject

V2 Compatibility

There is no equivalent V2 feature, but this implementation is based on a V2-compatible contribution from SWITCH.

The default servlet path that should be protected is slightly changed from the contributed code for consistency with other V3 methods.

Direct support for extracting subjectAltName extensions as custom Principals is not provided by this implementation, but the same functionality can be configured using the x500 subject canonicalization flow.

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.