Current File(s): authn/authn.properties
Format: Properties, Native Spring

Overview

The "authn/X509Internal" login flow leverages any surrounding mechanism you have available for TLS client certificate authentication, provided the standard servlet request attribute (now "jakarta.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 difference between this flow and the X509 flow is that this flow doesn't redirect to a protected path; rather, the path of the requested profile flow has to be protected, which typically will trigger as soon as the client makes its first request. This is primarily suited to non-browser clients or other scenarios in which authentication is uniformly certificate-based.

The main disadvantage of using this flow for browser use cases is that it will perform the request for authentication without having a chance to determine if the request will succeed, which may be undesirable from a usability perspective.

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 post-login Subject Canonicalization flow must be enabled/configured to pull a suitable principal name out of the Subject.

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 or RemoteUserInternal 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

There is no configuration required, but you may use conf/global.xml to define a Spring bean named shibboleth.authn.X509Internal.TrustEngine as an OpenSAML TrustEngine that should be used to validate the client certificate chain. Of course, it's often simpler and more common to do this validation at the web server itself, although that's less flexible.

An example of a PKIX-based TrustEngine declaration follows. The bean ID is defined to allow the built-in flow to locate it.

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

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

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

Notes

The beans and properties governing this feature have evolved over the years and the documentation above is canonical for this release. Many older variants, which may include X509 instead of X509Internal in the name, remain supported for compatibility but are no longer documented here.