Fork me on GitHub

Apache Shiro Logo Simple. Java. Security. Apache Software Foundation Event Banner

Apache Shiro Authenticators

Handy Hint
Shiro v1 and v2 version end-of-life notice

As of February 28, 2024, Shiro v1 was superseded by v2.

As of June 29, 2026, Shiro v2 was superseded by v3.
Table of Contents

An Authenticator is a component responsible for verifying that a user actually is who they claim to be. It is the core component that executes the authentication process on behalf of the Subject.

While the Authentication documentation explains the concepts and workflow of authentication in Shiro, the Authenticator represents the actual implementation component that performs identity verification.

Role in the SecurityManager

The SecurityManager does not perform authentication directly. Instead, it delegates authentication requests to its internal Authenticator instance. When a Subject calls login(token), the SecurityManager receives the request and immediately delegates to the Authenticator by calling authenticate(token).

The Authenticator takes the submitted AuthenticationToken and uses it to verify the Subject’s identity. If verification succeeds, it returns an AuthenticationInfo object. If verification fails, it throws an AuthenticationException.

ModularRealmAuthenticator

Shiro uses the ModularRealmAuthenticator by default. This implementation supports coordinating one or more Realms during the authentication process.

When an authentication token is submitted, the ModularRealmAuthenticator:

  • Iterates through configured Realms

  • Calls each Realm’s supports(token) method to determine if the Realm can process the token

  • If a Realm supports the token, its getAuthenticationInfo(token) method is invoked

  • Returns authentication information if successful, or throws an exception if failed

Single vs. Multiple Realms

The ModularRealmAuthenticator supports both configurations:

Single Realm: When only one Realm is configured, the Authenticator directly invokes that Realm to verify the Subject’s credentials.

Multiple Realms: When multiple Realms are configured, the Authenticator uses an AuthenticationStrategy to determine how to coordinate authentication across the Realms. This is a PAM-style approach where each Realm can be consulted in sequence.

AuthenticationStrategy

When multiple Realms are configured, the Authenticator must determine if the overall authentication attempt succeeds or fails. The AuthenticationStrategy makes this determination.

Shiro provides three built-in strategies:

  • FirstSuccessfulStrategy: Consults Realms in order until one succeeds. Remaining Realms are not consulted.

  • AtLeastOneSuccessfulStrategy: Returns success if at least one Realm succeeds. Other Realms continue to be consulted.

  • AllSuccessfulStrategy: All Realms must succeed for authentication to succeed. This is the most restrictive.

You can configure which strategy the Authenticator uses, or implement your own strategy for custom behavior.

Configuration

You can configure a custom Authenticator in your Shiro configuration if needed:

authenticator = com.foo.bar.CustomAuthenticator
securityManager.authenticator = $authenticator

You can also configure the AuthenticationStrategy:

authenticationStrategy = org.apache.shiro.authc.pam.FirstSuccessfulStrategy
authenticator.authenticationStrategy = $authenticationStrategy

However, in most cases, the default ModularRealmAuthenticator with the default strategy is sufficient for typical applications.

How Authenticators Work with Realms

The Authenticator does not directly know how to verify credentials. Instead, it coordinates with configured Realms to perform the actual verification.

A Realm is a security-specific data access object that can locate and validate user credentials from a data source (database, LDAP, file system, etc.). The Realm is responsible for:

  • Determining if it understands the submitted AuthenticationToken via its supports(token) method

  • Looking up the user in the data source

  • Comparing submitted credentials with those stored in the data source

  • Returning the user’s authentication information if credentials match

  • Throwing an exception if credentials do not match

The Authenticator simply orchestrates this process by delegating to Realms in order and handling the results according to its configured strategy.

See Also

To learn more about related topics, see:

  • Authentication - Conceptual overview of authentication in Shiro.

  • Java Authentication Guide - Practical guide to implementing authentication in your application.

  • Realms - How Realms connect Shiro to your data sources.

  • Authorizers - The counterpart component for authorization.

  • SecurityManager - The component that orchestrates Authenticators and other Shiro components.