...
The "authn/X509Internal" login flow leverages any surrounding mechanism you have available for TLS client certificate authentication, provided the standard servlet request attribute (now "javaxjakarta.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.
...
There is no configuration required, but you may use conf/global.xml to define a Spring bean named shibboleth.authn.X509X509Internal.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.
...
Reference
| Expand |
|---|
|
The beans supported by this flow follow: The beans supported by this flow follow: Default | Description |
|---|
shibboleth.authn. |
X509X509X509Internal.resultCachingPredicate | Predicate<ProfileRequestContext> | An optional bean that can be defined to control whether to preserve the authentication result in an IdP session | shibboleth.authn. |
X509addDefaultPrincipals Bean ID | Type | Description |
|---|
shibboleth.authn.X509.TrustEngine | TrustEngine<X509Credential> | An optional bean for validating the client certificate | 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 | ClassifiedMessageMap |
Boolean | true | Whether to add the content of the supportedPrincipals property of the underlying flow descriptor to the resulting Subject | |
| Expand |
|---|
|
Map<String,Collection<String>> | Optional remapping of exception messages or events into specific Spring Web Flow events. |
|
| Expand |
|---|
|
The properties specific to this flow defined in authn/authn.properties are: Name | Default | Description |
|---|
idp.authn.X509Internal.saveCertificateToCredentialSet | true | Whether to save the certificate into the Subject's public credential set. Disable to reduce the size if not relying on the certificate for subject c14n. |
The general properties configuring this flow via authn/authn.properties are: Name | Default | Description |
|---|
idp.authn.X509Internal.order | 1000 | Flow priority relative to other enabled login flows (lower is "higher" in priority) | idp.authn.X509Internal.nonBrowserSupported | true | Whether the flow should handle non-browser request profiles (e.g., ECP) | idp.authn.X509Internal.passiveAuthenticationSupported | false | Whether the flow allows for passive authentication | idp.authn.X509Internal.forcedAuthenticationSupported | false | Whether the flow supports forced authentication | idp.authn.X509Internal.proxyRestrictionsEnforced | %{idp.authn.enforceProxyRestrictions:true} | Whether the flow enforces upstream IdP-imposed restrictions on proxying | idp.authn.X509Internal.proxyScopingEnforced | false | Whether the flow considers itself to be proxying, and therefore enforces SP-signaled restrictions on proxying | idp.authn.X509Internal.discoveryRequired | false | Whether to invoke IdP-discovery prior to running flow | idp.authn.X509Internal.lifetime | %{idp.authn.defaultLifetime:PT1H} | Lifetime of results produced by this flow | idp.authn.X509Internal.inactivityTimeout | %{idp.authn.defaultTimeout:PT30M} | Inactivity timeout of results produced by this flow | idp.authn.X509Internal.reuseCondition | shibboleth.Conditions.TRUE | Bean ID of Predicate<ProfileRequestContext> controlling result reuse for SSO | idp.authn.X509Internal.activationCondition | shibboleth.Conditions.TRUE | Bean ID of Predicate<ProfileRequestContext> determining whether flow is usable for request | idp.authn.X509Internal.subjectDecorator | | Bean ID of BiConsumer<ProfileRequestContext,Subject> for subject customization | idp.authn.X509Internal.supportedPrincipals | (see below) | Comma-delimited list of protocol-specific Principal strings associated with flow | idp.authn.X509Internal.addDefaultPrincipals | true | Whether to auto-attach the preceding set of Principal objects to each Subject produced by this flow |
As a non-password based flow, the supportedPrincipals property defaults to the following XML: | Code Block |
|---|
| <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> |
In property form, this is expressed as (note the trailing commas): | Code Block |
|---|
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 |
|
| Expand |
|---|
| title | Flow Descriptor XML (V4.1+) |
|---|
|
To replace the internally defined flow descriptor bean, the following XML is required: | Code Block |
|---|
| <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-ref="#{getObject('%{idp.authn.X509Internal.subjectDecorator:}'.trim())}">
<property name="supportedPrincipalsByString">
<bean parent="shibboleth.CommaDelimStringArray"
c:_0="#{'%{idp.authn.X509Internal.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+V45, no default version of the list is provided and it may simply be placed in conf/global.xml if needed. |
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.