The Shibboleth IdP V3 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP4 wiki space for current documentation on the supported version.
JAASAuthnConfiguration
Current File(s): conf/authn/jaas-authn-config.xml, conf/authn/jaas.config
Format: Native Spring, JAAS
Legacy V2 File(s): conf/handler.xml, conf/login.config
Overview
The JAAS (Java Authentication and Authorization Service) is a desktop authentication mechanism in Java that has been commonly misappropriated as a server-side technology. A variety of "login module" plugins exist for different password-based technologies. Support is provided for using JAAS as a back-end for the password authentication login flow.
General Configuration
Configuring JAAS as a back-end requires that the right import is active in authn/password-authn-config.xml:
<import resource="jaas-authn-config.xml" />
The other imports must be commented or removed.
A few beans are defined in authn/jaas-authn-config.xml to configure this back-end by identifying the JAAS configuration file and JAAS application name(s) to use.
A bean alias is also defined that instantiates the JAAS back-end action as the "ValidateUsernamePassword" step of the web flow. This must not be changed.
JAAS Configuration
Simple JAAS Usage
JAAS has its own configuration format (see here). By default, the named application configuration used is called "ShibUserPassAuth". This can be changed using the shibboleth.authn.JAAS.LoginConfigNames, or turned into a list of more than one configuration, with each one tried in series until a success. This is equivalent to the JAAS keyword "sufficient". Using separate configurations allows errors to be isolated per-module instead of masked by generic JAAS exceptions.
Advanced JAAS Usage 3.3
As of V3.3, more advanced options exist to:
- supply the JAAS configuration name(s) dynamically using a function
- associate particular JAAS configuration(s) with a set of custom Principals to attach to the authentication result
For the former, a Function bean called shibboleth.authn.JAAS.LoginConfigStrategy is defined. This allows the set of JAAS configurations to be supplied at runtime. The signature of this function is fairly complex:
Function<ProfileRequestContext, Collection<Pair<String,Subject>>>
The result of the function is a collection of JAAS configuration names together with an optional collection of custom Principals (wrapped in a Java Subject) to inject into the Subject produced by the login flow. This allows the result to be tailored based on which JAAS configuration actually succeeds, a common need when combining methods.
If the information the function would return is static, a bean called shibboleth.authn.JAAS.LoginConfigurations can be defined.
When using either a static or dynamic approach involving custom Principals, the surrounding flow generally should carry all of the possible Principal types in its supportedPrincipals property and the automatic injection of all those Principals is turned off by defining a bean like so:
<util:constant id="shibboleth.authn.Password.addDefaultPrincipals" static-field="java.lang.Boolean.FALSE" />
Reference
Beans
The beans defined in authn/jaas-authn-config.xml follow:
Bean ID | Type | Default | Function |
|---|---|---|---|
| JAASConfig | String | %{idp.home}/conf/authn/jaas.config | Defines a Spring Resource containing the JAAS config. Normally this just points to a file in the filesystem |
| shibboleth.authn.JAAS.JAASConfigURI | java.net.URI | JAASConfig.URI | Defines the URI object containing the JAAS configuration |
| shibboleth.authn.JAAS.LoginConfigNames | Collection<String> | [ "ShibUserPassAuth" ] | Simple list of JAAS application configuration names to use |
| shibboleth.authn.JAAS.LoginConfigurations 3.3 | Collection<Pair<String,Subject>> | Static list of JAAS application configuration names along with mappings to custom Principals | |
| shibboleth.authn.JAAS.LoginConfigStrategy 3.3 | Function (see above) | For advanced use, you can inject a function to supply at runtime the information that the previous bean would supply statically |
V2 Compatibility
JAAS configuration is independent of the IdP and is therefore identical with the use of JAAS in the V2 UsernamePassword handler. By default this configuration is placed in authn/jaas.config and the legacy-matching "ShibUserPassAuth" login configuration name is used (though this can be changed).
Unlike V2, the JAAS configuration is not placed into a global system property that would apply to the container as a whole; it is private to the IdP application.
However, while JAAS configuration in general is the same, the vt-ldap JAAS module supplied with V2 is not supported and has been superseded by the newer ldaptive library, which provides its own JAAS module. In addition to the module class being different, there are other differences in settings.
LDAP Module Configuration Comparison
This is not a comprehensive list, but it does include the most commonly used configuration arguments.
| vt-ldap | ldaptive | comments |
|---|---|---|
| ldapUrl | ldapUrl | |
| host | N/A | use ldapUrl |
| port | N/A | use ldapUrl |
timeout | connectTimeout | |
| N/A | responseTimeout | |
| baseDn | baseDn | |
base | N/A | use baseDn |
| tls | useStartTLS | |
ssl | useSSL | |
| sslSocketFactory | credentialConfig | |
userField | N/A | use userFilter |
| userFilter | userFilter | |
subtreeSearch | subtreeSearch | |
authorizationFilter | N/A | |
constructDn | N/A | use dnResolver |
allowMultipleDns | allowMultipleDns | |
| bindDn | bindDn | |
serviceUser | N/A | use bindDn |
| bindCredential | bindCredential | |
serviceCredential | N/A | use bindCredential |
dnResolver | dnResolver | |
userRoleAttribute | userRoleAttribute |
Notes
TBD