Introduction
Shiro can use multi-realm authentication and authorization - for example, authentication and authorization against a shiro.ini account and an LDAP account or against one or more LDAP accounts.
Scope
This article describes multi-realm authentication in detail - example configurations showing multi-realm authentication and authorization have already been presented in the Authentication and Authorization - Configuration and LDAP Configuration articles.
Behavior for Accounts with a Common User Name and Password
Consider the case of a user account that is registered for both the Shiro ini realm and an LDAP realm. An example configuration is shown in the listing below. A publicly accessible LDAP server (hosted by forumsys.com) is used in this configuration to allow the configuration to be implemented by 'cut and paste' and a minimum of modification. The LDAP server has an account with name 'newton', password 'password' and this account belongs to the group 'scientists'. In the configuration below members of the 'scientists' LDAP group are assigned the (Shiro) 'it_operator' role. The ini realm 'newton' account has been given the same password as the LDAP realm account.
In this example:
- the
securityManager.realms
parameter is specified:- The authorization information provided by the user logging in will be checked against each realm account in the order in which realms are specified in a
securityManager.realms
parameter.(explicit ordering). In the example, this would be first thepublicLdapRealm
and then theiniRealm
.
- The authorization information provided by the user logging in will be checked against each realm account in the order in which realms are specified in a
- If the
securityManager.realms
parameter had not been specified:- The authorization information provided by the user logging in would have been checked against each realm account in the order in which realms were listed in the [main] section of the shiro.ini file.(implicit ordering). In the example, this would be first the
iniRealm
and then thepublicLdapRealm
.
- The authorization information provided by the user logging in would have been checked against each realm account in the order in which realms were listed in the [main] section of the shiro.ini file.(implicit ordering). In the example, this would be first the
Note that Explicit and implicit realm ordering is described in more detail in the 'Realm Authentication' section of on the Shiro Authentication web site.
Alternative Authentication Behavior Strategies
Shiro allows a number of Authentication Behavior Strategies to be followed. These are configured with the authcStrategy
parameter and are:
org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy
- If one (or more) Realms authenticate successfully, the overall attempt is considered successful. If none authenticate successfully, the attempt fails.
- Roles from all authenticated realms are merged.
org.apache.shiro.authc.pam.FirstSuccessfulStrategy
- Only the information returned from the first successfully authenticated Realm will be used. All further Realms will be ignored. If none authenticate successfully, the attempt fails.
- Roles from the first authenticated realm are used.
org.apache.shiro.authc.pam.AllSuccessfulStrategy
- All Realms listed in the
securityManager.realms
parameter must authenticate successfully for the overall attempt to be considered successful. If any one does not authenticate successfully, the attempt fails. - Roles from all realms are merged.
- All Realms listed in the
By default, Shiro authentication uses the authcStrategy = org.apache.shiro.authc.pam.AtLeastOneSuccessful
strategy. This strategy causes a login to be attempted for all the realms listed in the securityManager.realms
parameter or, if this is not set, in all the realms listen in the shiro.ini configuration file.
Note that roles from the iniRealm
for authenticated LDAP realm user accounts of the same name are always merged to the list of roles, regardless of whether or not the same password is used for both realm accounts.
The roleAssignmentFromIni = false
LDAP realm parameter (default setting is true) can be used to stop this happening, In the example listed above this parameter would then be configured for the publicLdapRealm
as:
publicLdapRealm.
roleAssignmentFromIni = false
Multi-Realm Authentication and Authorization up to Release 1.12.3
Note that the FirstSuccessfulStrategy
strategy is incorrectly implemented and that a login will be attempted for all the realms, even after a successful login has been noted. Login attempts carried out after a successful login has been noted will be logged at the [error]
level. See issue JOC-437 for more information.
Multi-Realm Authentication and Authorization from Release 1.12.4 onwards
The default Shiro authenticator can be replaced by one written by the SOS.The SOS authenticator is called using the following lines of code:
authenticator = com.sos.auth.shiro.SOSAuthenticator securityManager.authenticator=$authenticator
The SOS authenticator stops attempting to authenticate when the FirstSuccessfulStrategy
strategy is specified and a successful login has taken place.
Note: roles from the iniRealm
for authenticated users are always merged to the list of roles regardless of the strategy specified (This seems to be an error in Shiro.)
Behavior for Accounts with Differing Passwords
The following points apply for a multi-realm environment, where one of the realms is the iniRealm and when the user accounts have a common name but different passwords:
When the SOS Authenticator is used with the First Successful strategy:
- If the authorization occurs through the ini realm then the user account will only be assigned the roles specified for the ini realm. The LDAP realm(s) will be ignored.
- If the authorization occurs through an LDAP realm then, regardless of whether or not the same password is used in each realm:
- The user account will be assigned the role(s) specified for the account in the (first) authorizing realm.
- The user account will also be assigned the role(s) specified for the account in the ini realm.
- This behavior ensures that a login is possible in the event of problems with the LDAP realm(s).
- The order in which the realms are specified in the
securityManager.realms
parameter is not significant here. - The ldap.roleAssignmentFromIni=false setting (default true) can be used to modify the behavior of the First Successful strategy so that roles from the ini realm are not assigned.