Page tree
Skip to end of metadata
Go to start of metadata

Current File(s): conf/authn/password-authn-config.xml, views/login.vm, conf/authn/authn.properties (V4.1+)

Format: Native Spring

Overview

The authn/Password login flow supports an extensible set of back-ends for password-based authentication, normally collected using a web form, and is the flow used at least in part by most deployments.

It is compatible with non-browser clients by virtue of supporting HTTP Basic authentication if credentials are provided without prompting, and knows not to present a form when a non-browser profile like ECP is used.

New to V4 is a refactored design that includes a dedicated plugin API for developing custom "back-ends", the CredentialValidator interface and some associated base classes for assisting in developing new ones. The flow now also supports chaining of CredentialValidator plugins in arbitrary sequences instead of requiring the use of JAAS login modules for that feature.

Enabling Module (V4.1+)

For V4.1+, configuring and using this feature requires that you first enable the "idp.authn.Password" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.

(Windows)
C:\opt\shibboleth-idp> bin\module.bat -t idp.authn.Password || bin\module.bat -e idp.authn.Password

(Other)
$ bin/module.sh -t idp.authn.Password || bin/module.sh -e idp.authn.Password

General Configuration

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.

For detailed information on configuring the supplied back-ends, see:

Aside from the more specific back-end configurations, there are beans and properties defined for some general configuration independent of the back-end chosen. They are all listed in the reference section below.

The most important bean is shibboleth.authn.Password.Validators, a List of CredentialValidator plugins that should be used to validate the subject's username and password.

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.

Upgraded V3 Configurations

For backward compatibility, the original "one back-end at a time" configuration is detected and turned into a list of a single CredentialValidator plugin that matches as much as possible the behavior of the original software. This is triggered by the absence of the new shibboleth.authn.Password.Validators bean and the presence of the old "ValidateUsernamePassword" bean alias that was used in V3 to identify which back-end to use.

Basic Features

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.

Be aware that the default view templates and configuration of classified messages (see next section) results in a system that will report context-sensitive errors to the user, such as whether the password was invalid or the username was mis-entered. This is appropriate for most organizations to reduce help desk calls caused by simple user error, but some organizations keep usernames a secret and may wish to adjust the configuration to collapse all error reporting and avoid leaking information about whether usernames are valid or not.

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.

Advanced Features

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.

This feature has been superseded by the MFA login flow, which is much more flexible and almost always much simpler to use, though it's more complex to understand at first. There are no final plans to deprecate or remove this feature yet, but that's very likely, so migrating away from it would be a good decision.

Mixing this feature with the MFA flow or other means of combining methods is also strongly discouraged, as it gets very confusing and difficult to debug very quickly.

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.

If you are using 4.0.0 or 4.0.1 or later versions with previous configuration files, login.vm may fail to display additional buttons. The following patch will fix that issue:

views/login.vm
--- a/idp-conf/src/main/resources/views/login.vm
+++ b/idp-conf/src/main/resources/views/login.vm
@@ -90,7 +90,7 @@
             #end
 
             #foreach ($extFlow in $extendedAuthenticationFlows)
-              #if ($authenticationContext.isAcceptable($extFlow) and $extFlow.apply(profileRequestContext))
+              #if ($authenticationContext.isAcceptable($extFlow) and $extFlow.test(profileRequestContext))
                 <div class="form-element-wrapper">
                   <button class="form-element form-button" type="submit" name="_eventId_$extFlow.getId()">
                     #springMessageText("idp.login.$extFlow.getId().replace('authn/','')", $extFlow.getId().replace('authn/',''))

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.

Reference

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

Bean ID / Type

Default

Description

shibboleth.authn.Password.Validators

List<CredentialValidator>


Defines the set of validator plugins to use

shibboleth.authn.Password.RequireAll

Boolean

FalseWhether all validators must succeed or just one

shibboleth.LDAPValidator

LDAPCredentialValidator


Parent bean for referencing or defining LDAP validation

shibboleth.KerberosValidator

KerberosCredentialValidator


Parent bean for referencing or defining Kerberos validation

shibboleth.JAASValidator

JAASCredentialValidator


Parent bean for referencing or defining JAAS validation

shibboleth.HTPasswdCredentialValidator

HTPasswdValidator


Parent bean for referencing or defining htpasswd file validation (note the name for this is inconsistent with the others for the time being)

shibboleth.authn.Password.UsernameFieldName

String

j_username

Name of the username field in the form

shibboleth.authn.Password.PasswordFieldName

String

j_passwordName of the password field in the form

shibboleth.authn.Password.SSOBypassFieldName

String

donotcacheName of the form field signaling to avoid caching the authentication result for SSO

shibboleth.authn.Password.Lowercase

Boolean

falseWhether to lowercase the username before validating it

shibboleth.authn.Password.Uppercase

Boolean

falseWhether to uppercase the username before validating it

shibboleth.authn.Password.Trim

Boolean

trueWhether to trim leading and trailing whitespace from the username before validating it

shibboleth.authn.Password.Transforms

Pair<String,String>


Pairs of regular expressions and replacement expressions to apply to the username before validating it

shibboleth.authn.Password.matchExpression

Pattern


Regular expression to check username against

shibboleth.authn.Password.RetainAsPrivateCredential

Boolean

falseWhether to keep the password around as a private "credential" in the Java Subject for use in later stages such as attribute resolution

shibboleth.authn.Password.RemoveAfterValidation

Boolean

trueWhether to remove the object holding the password from the request's active state after validating it (to avoid it being preserved in the session any longer than needed)

shibboleth.StorageBackedAccountLockoutManager

StorageBackedAccountLockoutManager


Parent bean for declaring storage-backed account lockout with appropriate defaults

shibboleth.authn.Password.AccountLockoutManager

AccountLockoutManager


A lockout manager that, if defined, will enable account lockout feature

shibboleth.authn.Password.ClassifiedMessageMap

Map<String,List<String>>

(see file)A map between defined error/warning conditions and events and implementation-specific message fragments to map to them.

shibboleth.authn.Password.resultCachingPredicate

Predicate<ProfileRequestContext>


An optional bean that can be defined to control whether to preserve the authentication result in an IdP session
The beans below are primarily used in conjunction with the Extended Flow Calling feature:

shibboleth.authn.Password.ExtendedFlows

String


Regular expression identifying the login flows to present as additional options to a user in the view

shibboleth.authn.Password.ExtendedFlowParameters

List<String>


A list of form parameters to preserve for access by extended flows

shibboleth.authn.Password.PrincipalOverride

List<Principal>


Custom principals to include in the results produced by the Password flow, if different from the set attached to the flow's supportedPrincipals property

shibboleth.authn.Password.addDefaultPrincipals

Boolean

trueWhether to add the content of the supportedPrincipals property of the underlying flow descriptor to the resulting Subject

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

Bean ID

DefaultDescription

shibboleth.authn.Password.Validators

List<CredentialValidator>


Defines the set of validator plugins to use

shibboleth.LDAPValidator

LDAPCredentialValidator


Parent bean for referencing or defining LDAP validation

shibboleth.KerberosValidator

KerberosCredentialValidator


Parent bean for referencing or defining Kerberos validation

shibboleth.JAASValidator

JAASCredentialValidator


Parent bean for referencing or defining JAAS validation

shibboleth.HTPasswdValidator

HTPasswdCredentialValidator


Parent bean for referencing or defining htpasswd file validation

shibboleth.authn.Password.Transforms

Pair<String,String>


Pairs of regular expressions and replacement expressions to apply to the username before validating it

shibboleth.StorageBackedAccountLockoutManager

StorageBackedAccountLockoutManager


Parent bean for declaring storage-backed account lockout with appropriate defaults

shibboleth.authn.Password.AccountLockoutManager

AccountLockoutManager


A lockout manager that, if defined, will enable account lockout feature

shibboleth.authn.Password.ClassifiedMessageMap

Map<String,List<String>>

(see file)A map between defined error/warning conditions and events and implementation-specific message fragments to map to them.

shibboleth.authn.Password.resultCachingPredicate

Predicate<ProfileRequestContext>


An optional bean that can be defined to control whether to preserve the authentication result in an IdP session

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

PropertyDefaultDescription
idp.authn.Password.requireAllfalseWhether all validators must succeed or just one
idp.authn.Password.removeAfterValidationtrueWhether to remove the object holding the password from the request's active state after validating it (to avoid it being preserved in the session any longer than needed)
idp.authn.Password.retainAsPrivateCredentialfalseWhether to keep the password around as a private "credential" in the Java Subject for use in later stages such as attribute resolution
idp.authn.Password.trimtrueWhether to trim leading and trailing whitespace from the username before validating it
idp.authn.Password.lowercasefalseWhether to lowercase the username before validating it
idp.authn.Password.uppercasefalseWhether to uppercase the username before validating it
idp.authn.Password.matchExpression
Regular expression to apply before accepting username

idp.authn.Password.usernameFieldName

j_usernameName of the username field in the form
idp.authn.Password.passwordFieldNamej_passwordName of the password field in the form
idp.authn.Password.ssoBypassFieldNamedonotcacheName of the form field signaling to avoid caching the authentication result for SSO

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

Property Default Description
idp.authn.Password.order 1000 Flow priority relative to other enabled login flows (lower is "higher" in priority)
idp.authn.Password.nonBrowserSupported true Whether the flow should handle non-browser request profiles (e.g., ECP)
idp.authn.Password.passiveAuthenticationSupported true Whether the flow allows for passive authentication
idp.authn.Password.forcedAuthenticationSupported true Whether the flow supports forced authentication
idp.authn.Password.proxyRestrictionsEnforced %{idp.authn.enforceProxyRestrictions:true} Whether the flow enforces upstream IdP-imposed restrictions on proxying
idp.authn.Password.proxyScopingEnforced false Whether the flow considers itself to be proxying, and therefore enforces SP-signaled restrictions on proxying
idp.authn.Password.discoveryRequired false Whether to invoke IdP-discovery prior to running flow
idp.authn.Password.lifetime %{idp.authn.defaultLifetime:PT1H} Lifetime of results produced by this flow
idp.authn.Password.inactivityTimeout %{idp.authn.defaultTimeout:PT30M} Inactivity timeout of results produced by this flow
idp.authn.Password.reuseCondition shibboleth.Conditions.TRUE Bean ID of Predicate<ProfileRequestContext> controlling result reuse for SSO
idp.authn.Password.activationCondition shibboleth.Conditions.TRUE Bean ID of Predicate<ProfileRequestContext> determining whether flow is usable for request
idp.authn.Password.subjectDecorator Bean ID of BiConsumer<ProfileRequestContext,Subject> for subject customization
idp.authn.Password.supportedPrincipals (see below) Comma-delimited list of protocol-specific Principal strings associated with flow
idp.authn.Password.addDefaultPrincipals true Whether to auto-attach the preceding set of Principal objects to each Subject produced by this 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.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.

Notes

The shibboleth.authn.Password.RetainAsPrivateCredential bean (and idp.authn.Password.retainAsPrivateCredential property in V4.1+) should be used with caution, as it retains the password and makes it available in plaintext form within server memory at various stages. When the session is written to storage, the password is encrypted with the secret key used by the IdP for other encryption of data to itself, but it will be decrypted and back in memory at various times when the session is accessed or updated.

  • No labels