PasswordAuthnConfiguration

Use authn/password-authn-config.xml to configure the main features of this flow.

Unlike V3, it is no longer necessary to pick a single back-end configuration and to comment or uncomment specific supporting files for LDAP, Kerberos, or JAAS. All of the files can be imported if desired/needed and any of the back-ends can be used at the same time in sequence, if desired.

Most features of this flow can be configured with authn/authn.properties, with some advanced features relying on authn/password-authn-config.xml.

Unlike V3, it is no longer necessary to pick a single back-end configuration and to comment or uncomment specific supporting files for LDAP, Kerberos, or JAAS. All of the original back-end files have been removed from the default distribution and any outlying needs for XML configuration can be placed in authn/password-authn-config.xml.

An Boolean bean called shibboleth.authn.Password.RequireAll controls whether the credentials must be validated successfully by all applicable plugins in the list, or just one.

Combining plugins tends to be more complex but the default, requiring only a single valid result, is fairly simple to deal with. One obvious issue is that you should make sure to set the shibboleth.authn.Password.RemoveAfterValidation bean to FALSE if you apply the "require all" mode to prevent the username/password information from being pulled mid-request.

A property named idp.authn.Password.requireAll controls whether the credentials must be validated successfully by all applicable plugins in the list, or just one.

Combining plugins tends to be more complex but the default, requiring only a single valid result, is fairly simple to deal with. One obvious issue is that you should make sure to set the property named idp.authn.Password.removeAfterValidation to false if you apply the "require all" mode to prevent the username/password information from being pulled mid-request.

The first user interface layer of the flow is actually HTTP Basic authentication; if a header with credentials is supplied, the credentials are tested immediately with no prompting. If that step fails, or no credentials are supplied, then a view is rendered unless the request is for passive authentication or part of a non-browser profile.

Views are handled by Spring Web Flow, so support various technologies, but Velocity and JSP are supported by default and the examples are all based on Velocity.

Example Velocity User Interface

The example Velocity templates views/login.vm and views/login-error.vm illustrate generally how to populate the form, and how to detect and respond to error conditions. Internationalization is performed through the use of Spring message properties (which can be overridden via the top-level messages folder). Information on Spring internationalization is near the end of this section of the Spring documentation.

When rendering Velocity views, several variables are available to aid per-relying party customization.

Spring form generation macros such as #springMessage and #springMessageText are available to Velocity templates.

You can freely comment out or remove the "Do Not Cache" support of course, or use Javascript to automate it for certain address ranges.

Advanced Error Handling Example

The error message classification feature allows error messages to be mapped into grouped "classes" of errors that can be used in the view to report the results of a failed login. The main value of this feature is in supporting chains of multiple validators because the system will accumulate all of the classified errors that occur so that a precedence of error types can be applied to decide what to report to the user. A working example of this:

views/login-error.vm

## Velocity Template for login error message production, included by login.vm
##
## authenticationErrorContext - context containing error data, if available
##
#if ($authenticationErrorContext && $authenticationErrorContext.getClassifiedErrors().size() > 0 && $authenticationErrorContext.getClassifiedErrors().iterator().next() != "ReselectFlow")
    ## This handles errors that are classified by the message maps in the config.
    #if ($authenticationErrorContext.getClassifiedErrors().contains("InvalidPassword"))
        #set ($eventId = "InvalidPassword")
    #elseif ($authenticationErrorContext.getClassifiedErrors().contains("AccountLocked"))
        #set ($eventId = "AccountLocked")
    #elseif ($authenticationErrorContext.getClassifiedErrors().contains("AccountDisabled"))
        #set ($eventId = "AccountDisabled")
    #elseif ($authenticationErrorContext.getClassifiedErrors().contains("ExpiredPassword"))
        #set ($eventId = "ExpiredPassword")
    #elseif ($authenticationErrorContext.getClassifiedErrors().contains("UnknownUsername"))
        #set ($eventId = "UnknownUsername")
    #end
#elseif ($authenticationErrorContext && $authenticationErrorContext.getExceptions().size() > 0)
    ## This handles login exceptions that are left unclassified.
    #set ($loginException = $authenticationErrorContext.getExceptions().get(0))
    #if ($loginException.getMessage())
        #set ($message = "Login Failure: $loginException.getMessage()")
    #else
    	#set ($message = "Unidentified error")
    #end
#end

#if ($eventId || $message)
	<div class="error notification">
	#if ($eventId == "AccountLocked")
		## your code here
	#elseif ($eventId == "AccountDisabled")
		## your code here
	#elseif ($eventId == "ExpiredPassword")
		## your code here
	#elseif ($eventId == "InvalidPassword")
		## your code here
	#elseif ($eventId == "UnknownUsername")
		## your code here
	#elseif ($message)
		## your code here
	#end
	</div>
#end

JSP User Interface

The use of JSP is not advised, but is supported. To do so, views/login.vm must be removed or renamed and the IdP restarted, or it will take precedence. Views in JSP should be created in edit-webapp/WEB-INF/jsp (and the warfile should be recreated with bin/build.sh or bin/build.bat and the container restarted). The old V2 Taglibs are supported for JSP for now, but we have plans to deprecate them in the future.

There are parent beans defined for each back-end plugin supported to allow easy incorporation of the default configured behavior into the chain of validators. The settings inherited from V3 and (prior to V4.1) defined in the individual Spring bean files are now "global" options for each back-end that will apply to any validator of the given type unless overridden.

For example, this syntax defines a single LDAP validator that uses settings defined in a manner consistent with older versions of the software. The parent bean is used "as is" with no changes.

<util:list id="shibboleth.authn.Password.Validators">
    <ref bean="shibboleth.LDAPValidator" />
</util:list>

This syntax in contrast uses the parent bean as a template:

<util:list id="shibboleth.authn.Password.Validators">
    <bean parent="shibboleth.LDAPValidator"
		p:authenticator-ref="bindSearchAuthenticator" />
</util:list>

In this case, the LDAP authenticator object used is explicitly set to the bindSearchAuthenticator bean from the old V3 version of ldap-authn-config.xml instead of the value set by the "idp.authn.LDAP.authenticator" property.

This is a simple example but the point is that once you switch from a <ref> to a new, but inherited, <bean>, you can default or override each property of the validator as you choose. The global/default settings in the individual Spring bean files only matter to the extent that you want to use them.

With the expansion from one to potentially multiple back-end validators, a backward-compatible enhancement has been made to the support for case folding, trimming, and regular expression transformation of the username entered by a subject. Instead of normalizing the value "in place", the same features can be applied either globally or individually to each validator so that the normalized value may be different in each case.

The globally defined beans (and properties in V4.1) are used if not overridden, but options exist on each supported CredentialValidator class to override a global setting with a more specific setting.

Note that the result of a successful authentication via a particular validator will typically produce a Java Subject containing a UsernamePrincipal containing the normalized value specific to that validator, so it's possible when chaining and using the "RequireAll" feature to produce compound results containing multiple, distinct UsernamePrincipal objects that will not work with the default/simple SimplePostLoginC14NConfiguration used in many cases. Something more may be needed to tell the system which of the potentially multiple "usernames" should be the official one used in the session.

Similarly, the bean shibboleth.authn.Password.matchExpression (V4.0) or property idp.authn.Password.matchExpression (V4.1+) are applied globally, if set, but each CredentialValidator can be individually configured with their own matchExpression setting. If a validator detects that a candidate transformed/normalized username doesn't match the expression, the validator will silently be ignored. This is not considered a success or failure. Note that Spring will automatically convert a string into a regular expression pattern, so adding a localized match rule is as simple as:

<util:list id="shibboleth.authn.Password.Validators">
    <bean parent="shibboleth.KerberosValidator" p:matchExpression="^\S+\.\d+$" />
    <ref bean="shibboleth.LDAPValidator" />
</util:list>

A special feature of this flow is the ability to inject your own behavior in response to particular error or warning conditions that occur. These conditions are set via the shibboleth.authn.Password.ClassifiedMessageMap bean in authn/password-authn-config.xml. If you map a particular string label to one or more exception/error messages in the map, that string label becomes a flow "event" that you can program the flow to respond to.

If your goal is to terminate processing at this point, then you should take a look at the discussion in AuthenticationConfiguration under "Custom Events", which describes how to configure the system to treat your custom events as allowable "end" states for the request and handle them as errors.

If your goal is rather to interrupt but then resume the login flow, then this is somewhat accomodated with a predefined set of flow defintions designed to be user-editable in flows/authn/conditions/

The conditions-flows.xml file controls what events are detected and handled, and what to do. The example included responds to a number of events by calling predefined subflows that are themselves just empty examples that return immediately, and then control passes back to the view state that renders the login form.

An obvious use for this feature is responding to an imminently expiring password with some kind of warning view; another is detection of a locked account, and the use of a dedicated view to help the user with that condition.

In the simplest case, maybe you just want to display a page, in which case you can insert your own <view-state> that displays a template of your own creation. Views generally have to contain a form whose action is set to "$flowExecutionUrl" and that contain a button to submit the form with the value "_eventId_proceed". Your view then transitions on "proceed" to the corresponding <end-state> and ends up back on the login form.

In more complex cases, you may need to actually redirect the user out to other functionality implemented outside the IdP, which is something the Spring Web Flow documentation refers to as an external redirect, and it's possible to resume the flow in that scenario as well. If you don't, the user's session is suspeneded and will consume resources until it times out, and that doesn't work well at scale, so you have to be careful with that approach.

A pluggable implementation of account lockout can be enabled by defining a bean called shibboleth.authn.Password.AccountLockoutManager that implements the AccountLockoutManager interface. A default implementation of this interface is available using a parent bean named shibboleth.StorageBackedAccountLockoutManager (commented out by default in conf/authn/password-authn-config.xml).

The default implementation has the following behavior:

• Tracks lockout state via an injected StorageService, by default the in-memory variant preconfigured with the IdP. This results in per-node lockout tracking, usually sufficient considering the overhead of other options.

• Provides a simple algorithm that tracks invalid attempts that occur within a specified interval, and once a limit is reached, blocks subsequent attempts for a specified duration.

• Scopes lockouts to a given username and client IP address (but this is configurable via an injectable function).

Note that each attempt can be separated in time by the specified interval, so a 5 minute interval does not mean all the attempts must occur within 5 minutes, but could occur over a period as long as 5 times the number of attempts.

Once an account locks, an "AccountLocked" event is signaled, and the new default configuration maps this event to the "AccountLocked" classified error. If your installation pre-dates this feature, you will likely want to map that event to whichever classified error reporting condition you want to expose to the user.

See AccountLockoutManagement for information on the administrative flow that allows management of lockout state.

With V4, creating a new back-end generally is less work than before and relies on supplying new implementations of the CredentialValidator interface, usually by inheriting from the net.shibboleth.idp.authn.AbstractUsernamePasswordCredentialValidator class.

If you built a custom back-end using the older V3 "action bean" contract, that is no longer supported in this version. It's generally straightforward to simplify such a class and turn it into a CredentialValidator.

A feature included with the Password flow is the ability to present additional login options to the user and call them directly as subflows in response to some form of user input or client-side script. This is useful if you want most users to have the option to use a password, but make more advanced options available at the same time without requiring extra pages or clicks to reach the password option.

Basic Setup

Some preconditions for using this feature:

• The "extended" flows you want to make available must be active. That is, they must be enabled via the idp.authn.flows property and/or any profile-specific configuration you create.

• The Password flow must be configured to run before other flows that you want it to run itself. This depends on the bean order in authn/general-authn.xml (or on the various "order" properties in authn/authn.properties in V4.1+).

• The supportedPrincipals of the Password flow must typically be a union of its own list of custom Principals and any supported by the extended flows. Otherwise the IdP may not invoke the Password flow if a request is made that requires one of the extended flows to be used.

Assuming the above changes are made, to configure this feature you must supply definitions for the following beans in authn/password-authn-config.xml (there are example definitions at the bottom of the file in a comment):

• shibboleth.authn.Password.ExtendedFlows

  • Similar to the idp.authn.flows property, this is a String containing a regular expression matching the names of the candidate extended login flows to offer.

• shibboleth.authn.Password.PrincipalOverride

  • This list bean overrides the values supplied in the Password flow's supportedPrincipals property and reduces the list back down to a smaller set, just the custom Principals to include in any results produced by the Password mechanism itself. In other words, if the Password flow has to be enabled for stronger authentication types, this is where you reduce the list back down to just the values associated with password authentication. Typically you would set this to the same values the Password flow's supportedPrincipals property would have originally been configured with.

User Interface

The above changes trigger the example logic in the login view template (views/login.vm) that iterates over the extended flows, determines which ones are "allowable" for the request, and displays a button to run them. This is obviously a crude UI that you are expected to tailor for your use case, usually by taking advantage of knowledge of the specific methods you're trying to make available and how you want to describe them to users. The UI also includes support for not rendering the Password login form if that method itself isn't allowed.

The example buttons will run the corresponding extended flow. If the flow succeeds, the authentication process will complete in the usual manner. If not, the login view will be re-displayed, and the "event" triggered will reflect whatever was returned by the failed flow. In addition, the AuthenticationFlowDescriptor returned by $authenticationContext.getAttemptedFlow() will return the flow that failed, rather than the Password flow. With this information, you can customize the login-error.vm template to respond to the error appropriately.

For obvious reasons, it's hard to document exactly how to do all this "correctly" because the UI will be very site-dependent (and quite often will be complex to display). The goal is to supply the template with sufficient information to allow you to script the UI without having to make coding changes.

Additional Notes

Some login flows may be implemented to take advantage of the use of this feature in a couple of different ways. A custom login flow can distinguish between being called directly by the IdP and as an extended flow called by another login flow by the presence of a flow variable called "calledAsExtendedFlow". This is automated for the External login flow by making a request attribute available called "extended" when this flow variable is set.

It's also possible to pass information across the flow boundary. Any form parameters you include in the form that submits the event to call the extended flow can be captured by adding their names to a bean called shibboleth.authn.Password.ExtendedFlowParameters. Any values for parameters that match a name in that bean will be saved to a map returned by the AuthenticationContext's getAuthenticationStateMap() method. They are not typically preserved on the actual query string that a called flow will see.

The beans defined in or for use in authn/password-authn-config.xml follow:

The beans defined in or for use in authn/password-authn-config.xml follow:

The flow-specific properties usable via authn/authn.properties are:

The general properties configuring this flow via /authn.properties are:

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