AuthenticationStrategy

When two or more realms are configured for an application, the ModularRealmAuthenticator relies on an internal AuthenticationStrategy component to determine the conditions for which an authentication attempt succeeds or fails.

For example, if only one Realm authenticates an AuthenticationToken successfully, but all others fail, is the authentication attempt considered successful? Or must all Realms authenticate successfully for the overall attempt to be considered successful? Or, if a Realm authenticates successfully, is it necessary to consult other Realms further? An AuthenticationStrategy makes the appropriate decision based on an application’s needs.

An AuthenticationStrategy is a stateless component that is consulted 4 times during an authentication attempt (any necessary state required for these 4 interactions will be given as method arguments):

1. before any of the Realms are invoked
2. immediately before an individual Realm’s getAuthenticationInfo method is called
3. immediately after an an individual Realm’s getAuthenticationInfo method is called
4. after all of the Realms have been invoked

Also an AuthenticationStrategy is responsible for aggregating the results from each successful Realm and ‘bundling’ them into a single AuthenticationInforepresentation. This final aggregate AuthenticationInfo instance is what is returned by the Authenticator instance and is what Shiro uses to represent the Subject’s final identity (aka Principals).

Subject Identity 'View'

If you use more than one Realm in your application to acquire account data from multiple data sources, the AuthenticationStrategy is ultimately responsible for the final 'merged' view of the Subject's identity that is seen by the application.

Shiro has 3 concrete AuthenticationStrategy implementations:

The ModularRealmAuthenticator defaults to the AtLeastOneSuccessfulStrategy implementation, as this is the most commonly desired strategy. However, you could configure a different strategy if you wanted:

[main]
...
authcStrategy = org.apache.shiro.authc.pam.FirstSuccessfulStrategysecurityManager.authenticator.authenticationStrategy = $authcStrategy...

Custom AuthenticationStrategy

If you wanted to create your own AuthenticationStrategy implementation yourself, you could use the org.apache.shiro.authc.pam.AbstractAuthenticationStrategy as a starting point. The AbstractAuthenticationStrategy class automatically implements the 'bundling'/aggregation behavior of merging the results from each Realm into a single AuthenticationInfo instance.

Realm Authentication Order

It is very important to point out that the ModularRealmAuthenticator will interact with Realm instances in iteration order.

The ModularRealmAuthenticator has access to the Realm instances configured on the SecurityManager. When performing an authentication attempt, it will iterate over that collection, and for each Realm that supports the submitted AuthenticationToken, invoke the Realm’s getAuthenticationInfo method.

Implicit Ordering

When using Shiro’s INI configuration format, you should configure Realms in the order you want them to process an AuthenticationToken. For example, in shiro.ini, Realms will be consulted in the order in which they are defined in the INI file. That is, for the following shiro.ini example:

blahRealm = com.company.blah.Realm
...
fooRealm = com.company.foo.Realm
...
barRealm = com.company.another.Realm

The SecurityManager will be configured with those three realms, and during an authentication attempt, blahRealm, fooRealm, and barRealm will be invoked in that order.

This has basically the same effect as if the following line were defined:

securityManager.realms = $blahRealm, $fooRealm, $barRealm

Using this approach, you don’t need to set the securityManager's realms property - every realm defined will automatically be added to the realms property.

Explicit Ordering

If you want to explicitly define the order in which the realms will be interacted with, regardless of how they are defined, you can set the securityManager’s realms property as an explicit collection property. For example, if using the definition above, but you wanted the blahRealm to be consulted last instead of first:

blahRealm = com.company.blah.Realm
...
fooRealm = com.company.foo.Realm
...
barRealm = com.company.another.RealmsecurityManager.realms = $fooRealm, $barRealm, $blahRealm
...

Explicit Realm Inclusion

When you explicitly configure the securityManager.realms property, only the referenced realms will be configured on the SecurityManager. This means you could define 5 realms in INI, but only actually use 3 if 3 are referenced for the realms property. This is different than implicit realm ordering where all available realms will be used.