Current File(s): authn/authn.properties (V4.1+)
Format: Native Spring, Properties (V4.1+)
Overview
The "authn/X509Internal" 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 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.
...
| Code Block |
|---|
<bean id="shibboleth.authn.X509.TrustEngine" parent="shibboleth.StaticPKIXTrustEngine"
p:certificates="%{idp.home}/credentials/rootca.pem"
p:checkNames="false"
p:verifyDepth="1" /> |
Reference
| Localtabgroup |
|---|
The beans supported by this flow follow: Bean ID | Type | Default | 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 | shibboleth.authn.X509.addDefaultPrincipals
| Boolean | true | Whether to add the content of the supportedPrincipals property of the underlying flow descriptor to the resulting Subject |
The beans supported by this flow follow: Bean ID | Type | Default | 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 |
| Localtab live |
|---|
| active | true |
|---|
| title | Properties (V4.1+) |
|---|
|
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 |
| Localtab live |
|---|
| 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+, no default version of the list is provided and it may simply be placed in conf/global.xml if needed. |