FunctionAuthnConfiguration

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

1 Overview
2 General Configuration
- 2.1 Use of Cookies
3 Reference
4 Notes

Overview

The authn/Function login flow is an extension point that allows authentication to be handled by a deployer-supplied Function object, which can be written in Java, a scripting language, etc. It simplifies authoring certain kinds of custom login flows (essentially it provides the "flow" part) and potentially simplifies some MultiFactorAuthnConfiguration scenarios by moving some of the logic into a separate component.

General Configuration

Dome generic settings applicable to all login flows are in authn/authn.properties.

Note for Upgraded Systems

The old file conf/authn/function-authn-config.xml is now supported only for compatibility and generally not installed or needed going forward.

The core of the flow’s configuration is a required bean named shibboleth.authn.Function.ResultLookupStrategy, of type Function<ProfileRequestContext,Object>, which you may define in global.xml.

If the Function returns a null, then authentication fails (this is how to signal a controlled failure). Otherwise, the Function can return a String (the username), a Principal, or a Subject, and the system will construct an appropriate AuthenticationResult around whatever is returned. You may also raise an exception if desired.

A simple scripted example that is more or less an emulation of the RemoteUser flow:

    <bean id="shibboleth.authn.Function.ResultLookupStrategy"
            parent="shibboleth.ContextFunctions.Scripted" factory-method="inlineScript"
            customObject-ref="shibboleth.HttpServletRequestSupplier">
        <constructor-arg>
            <value>
            <![CDATA[
                custom.get().getRemoteUser();
            ]]>
            </value>
        </constructor-arg>
    </bean>

Use of Cookies

Since a common use case is to be able to read and write cookies, note that there's already a component that handles this called a CookieManager. There are built-in objects of this type that will reuse standard properties controlling cookie domain, path, flags, etc. and that's usually the best way to do things. Simply inject an instance of shibboleth.CookieManager or shibboleth.PersistentCookieManager into a Java-based Function implementation, or as a customObject-ref property of a bean inheriting from shibboleth.ContextFunctions.Scripted or shibboleth.ContextFunctions.Expression, to use it to read and write cookies for you.

Reference

Beans that may be defined in global.xml: Bean ID / Type Default Function shibboleth.authn.Function.resultLookupStrategy Function<ProfileRequestContext,Object> A function to produce the authentication result (see above) shibboleth.authn.Function.resultCachingPredicate Predicate<ProfileRequestContext> An optional bean that can be defined to control whether to preserve the authentication result in an IdP session shibboleth.authn.Function.ClassifiedMessageMap Map<String,Collection<String>> Remaps NoCredentials and InvalidCredentials into ReselectFlow for fall-through behavior Optional remapping of exception messages or events into specific Spring Web Flow events.

The general properties configuring this flow via authn/authn.properties are: Name Default Description idp.authn.Function.order 1000 Flow priority relative to other enabled login flows (lower is "higher" in priority) idp.authn.Function.nonBrowserSupported true Whether the flow should handle non-browser request profiles (e.g., ECP) idp.authn.Function.passiveAuthenticationSupported true Whether the flow allows for passive authentication idp.authn.Function.forcedAuthenticationSupported false Whether the flow supports forced authentication idp.authn.Function.proxyRestrictionsEnforced %{idp.authn.enforceProxyRestrictions:true} Whether the flow enforces upstream IdP-imposed restrictions on proxying idp.authn.Function.proxyScopingEnforced false Whether the flow considers itself to be proxying, and therefore enforces SP-signaled restrictions on proxying idp.authn.Function.discoveryRequired false Whether to invoke IdP-discovery prior to running flow idp.authn.Function.lifetime %{idp.authn.defaultLifetime:PT1H} Lifetime of results produced by this flow idp.authn.Function.inactivityTimeout %{idp.authn.defaultTimeout:PT30M} Inactivity timeout of results produced by this flow idp.authn.Function.lifetimeStrategy 5.2 Function returning null Bean ID of Function<ProfileRequestContext,Duration> overriding a specific result’s lifetime idp.authn.Function.inactivityTimeoutStrategy 5.2 Function returning null Bean ID of Function<ProfileRequestContext,Duration> overriding a specific result’s inactivity timeout idp.authn.Function.reuseCondition shibboleth.Conditions.TRUE Bean ID of Predicate<ProfileRequestContext> controlling result reuse for SSO idp.authn.Function.activationCondition shibboleth.Conditions.TRUE Bean ID of Predicate<ProfileRequestContext> determining whether flow is usable for request idp.authn.Function.subjectDecorator Bean ID of BiConsumer<ProfileRequestContext,Subject> for subject customization idp.authn.Function.supportedPrincipals (see below) Comma-delimited list of protocol-specific Principal strings associated with flow idp.authn.Function.addDefaultPrincipals true Whether to auto-attach the preceding set of Principal objects to each Subject produced by this flow idp.authn.Function.c14n.flows 5.2 Comma-delimited list of c14n methods (beans) to run after use of this login flow Most of the flows, including this one, default to describing themselves in terms of "password"-based authentication, so the supportedPrincipals property defaults to the following XML: <list> <bean parent="shibboleth.SAML2AuthnContextClassRef" c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" /> <bean parent="shibboleth.SAML2AuthnContextClassRef" c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" /> <bean parent="shibboleth.SAML1AuthenticationMethod" c:method="urn:oasis:names:tc:SAML:1.0:am:password" /> </list> In property form, this is expressed as (note especially the trailing commas, which MUST be there): idp.authn.Function.supportedPrincipals = \ saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, \ saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:Password, \ saml1/urn:oasis:names:tc:SAML:1.0:am:password

To replace the internally defined flow descriptor bean, the following XML is required: <util:list id="shibboleth.AvailableAuthenticationFlows"> <bean p:id="authn/Function" parent="shibboleth.AuthenticationFlow" p:order="%{idp.authn.Function.order:1000}" p:nonBrowserSupported="%{idp.authn.Function.nonBrowserSupported:true}" p:passiveAuthenticationSupported="%{idp.authn.Function.passiveAuthenticationSupported:true}" p:forcedAuthenticationSupported="%{idp.authn.Function.forcedAuthenticationSupported:false}" p:proxyRestrictionsEnforced="%{idp.authn.Function.proxyRestrictionsEnforced:%{idp.authn.enforceProxyRestrictions:true}}" p:proxyScopingEnforced="%{idp.authn.Function.proxyScopingEnforced:false}" p:discoveryRequired="%{idp.authn.Function.discoveryRequired:false}" p:lifetime="%{idp.authn.Function.lifetime:%{idp.authn.defaultLifetime:PT1H}}" p:inactivityTimeout="%{idp.authn.Function.inactivityTimeout:%{idp.authn.defaultTimeout:PT30M}}" p:reuseCondition-ref="#{'%{idp.authn.Function.reuseCondition:shibboleth.Conditions.TRUE}'.trim()}" p:activationCondition-ref="#{'%{idp.authn.Function.activationCondition:shibboleth.Conditions.TRUE}'.trim()}" p:resultLifetimeLookupStrategy-ref="#{'%{idp.authn.Function.lifetimeStrategy:NullDurationLookupStrategy}'.trim()}" p:resultTimeoutLookupStrategy-ref="#{'%{idp.authn.Function.inactivityTimeoutStrategy:NullDurationLookupStrategy}'.trim()}" p:subjectDecorator="#{getObject('%{idp.authn.Function.subjectDecorator:}'.trim())}"> <property name="supportedPrincipalsByString"> <bean parent="shibboleth.CommaDelimStringArray" c:_0="#{'%{idp.authn.Function.supportedPrincipals:}'.trim()}" /> </property> </bean> </util:list> In older versions and upgraded systems, this list is defined in conf/authn/general-authn.xml. In V5, no default version of the list is provided and it may simply be placed in conf/global.xml if needed.

Notes

Note that upgraded systems will have alternate, legacy approaches to configuring this feature, as noted above.