This is an automated email from the ASF dual-hosted git repository.
lprimak pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
The following commit(s) were added to refs/heads/main by this push:
new c922e73d3 docs: complete authenticator and authorizer documentation
(#290)
c922e73d3 is described below
commit c922e73d3afc02de07d9a6002f4e60511e1e835f
Author: Ganesh Patil <[email protected]>
AuthorDate: Sun Oct 11 10:45:40 2026 +0530
docs: complete authenticator and authorizer documentation (#290)
* docs: migrate issue tracking to GitHub Issues and Discussions
* review comments
* docs: address PR review feedback
* docs: complete authenticator and authorizer documentation
* merge: resolve conflicts by accepting latest changes from main
- community.adoc: Update to use GitHub Discussions instead of Nabble
- forums.adoc: Restructure and add GitHub Discussions section
- issues.adoc: Update from Jira to GitHub Issues for issue tracking
* fix: update issues.adoc to use GitHub Issues instead of Jira
* docs: clarify FirstSuccessfulStrategy description for better clarity
* reverted unnecssary files
* linked authn/authz pages in their appropriate docs
---------
Co-authored-by: lprimak <[email protected]>
---
src/site/content/architecture.adoc | 4 +-
src/site/content/authentication.adoc | 2 +
src/site/content/authenticator.adoc | 110 ++++++++++++++++++++++++++--
src/site/content/authorization.adoc | 2 +
src/site/content/authorizer.adoc | 134 +++++++++++++++++++++++++++++++++--
src/site/content/issues.adoc | 4 +-
6 files changed, 244 insertions(+), 12 deletions(-)
diff --git a/src/site/content/architecture.adoc
b/src/site/content/architecture.adoc
index 7e2d6c6ae..1a1e37605 100644
--- a/src/site/content/architecture.adoc
+++ b/src/site/content/architecture.adoc
@@ -45,13 +45,13 @@ A security-specific 'view' of the entity (user, 3rd-party
service, cron job, etc
As mentioned above, the `SecurityManager` is the heart of Shiro's
architecture. It is mostly an 'umbrella' object that coordinates its managed
components to ensure they work smoothly together. It also manages Shiro's view
of every application user, so it knows how to perform security operations per
user.
* *Authenticator*
(link:static/current/apidocs/org/apache/shiro/authc/Authenticator.html[org.apache.shiro.authc.Authenticator])
-The `Authenticator` is the component that is responsible for executing and
reacting to authentication (log-in) attempts by users. When a user tries to
log-in, that logic is executed by the `Authenticator`. The `Authenticator`
knows how to coordinate with one or more `Realms` that store relevant
user/account information. The data obtained from these `Realms` is used to
verify the user's identity to guarantee the user really is who they say they
are.
+The `Authenticator` is the component that is responsible for executing and
reacting to authentication (log-in) attempts by users. When a user tries to
log-in, that logic is executed by the `Authenticator`. The `Authenticator`
knows how to coordinate with one or more `Realms` that store relevant
user/account information. The data obtained from these `Realms` is used to
verify the user's identity to guarantee the user really is who they say they
are. See link:authenticator.html[Apache Shir [...]
** *Authentication Strategy*
(link:static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html[org.apache.shiro.authc.pam.AuthenticationStrategy])
If more than one `Realm` is configured, the `AuthenticationStrategy` will
coordinate the Realms to determine the conditions under which an authentication
attempt succeeds or fails (for example, if one realm succeeds but others fail,
is the attempt successful? Must all realms succeed? Only the first?).
* *Authorizer*
(link:static/current/apidocs/org/apache/shiro/authz/Authorizer.html[org.apache.shiro.authz.Authorizer])
-The `Authorizer` is the component responsible determining users' access
control in the application. It is the mechanism that ultimately says if a user
is allowed to do something or not. Like the `Authenticator`, the `Authorizer`
also knows how to coordinate with multiple back-end data sources to access role
and permission information. The `Authorizer` uses this information to determine
exactly if a user is allowed to perform a given action.
+The `Authorizer` is the component responsible determining users' access
control in the application. It is the mechanism that ultimately says if a user
is allowed to do something or not. Like the `Authenticator`, the `Authorizer`
also knows how to coordinate with multiple back-end data sources to access role
and permission information. The `Authorizer` uses this information to determine
exactly if a user is allowed to perform a given action. See
link:authorizer.html[Apache Shiro Authorize [...]
* *SessionManager*
(link:static/current/apidocs/org/apache/shiro/session/mgt/SessionManager.html[org.apache.shiro.session.mgt.SessionManager])
The `SessionManager` knows how to create and manage user `Session` lifecycles
to provide a robust Session experience for users in all environments. This is a
unique feature in the world of security frameworks - Shiro has the ability to
natively manage user Sessions in any environment, even if there is no
Web/Servlet or EJB container available. By default, Shiro will use an existing
session mechanism if available, (e.g. Servlet Container), but if there isn't
one, such as in a standalone a [...]
diff --git a/src/site/content/authentication.adoc
b/src/site/content/authentication.adoc
index 71570e394..4fcca7db1 100644
--- a/src/site/content/authentication.adoc
+++ b/src/site/content/authentication.adoc
@@ -242,6 +242,8 @@ We will cover the `Realm` authentication behavior shortly.
[#Authentication-AuthenticationSequence-Authenticator]
=== Authenticator
+For a standalone overview of the component, see link:authenticator.html[Apache
Shiro Authenticators].
+
As mentioned earlier, the Shiro `SecurityManager` implementations default to
using a
link:/static/current/apidocs/org/apache/shiro/authc/pam/ModularRealmAuthenticator.html[`ModularRealmAuthenticator`]
instance.
The `ModularRealmAuthenticator` equally supports applications with single
Realm as well as those with multiple realms.
diff --git a/src/site/content/authenticator.adoc
b/src/site/content/authenticator.adoc
index 5cb29fd43..327c40abe 100644
--- a/src/site/content/authenticator.adoc
+++ b/src/site/content/authenticator.adoc
@@ -1,8 +1,110 @@
-= Authenticator
-:jbake-type: lend_a_hand
+[#Authenticator-UnderstandingAuthenticators]
+= Apache Shiro Authenticators
+:jbake-date: 2010-03-18 00:00:00
+:jbake-type: page
:jbake-status: published
-:jbake-tags: documentation, todo, lend-a-hand
+:jbake-tags: authenticator, authentication, security, realms
+:jbake-description: Understanding Apache Shiro Authenticators - the component
responsible for verifying user identity. Learn how Authenticators work with
Realms and AuthenticationStrategies.
:idprefix:
:icons: font
+:toc:
-TODO
+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 link:/subject.html[Subject].
+
+While the link:/authentication.html[Authentication] documentation explains the
concepts and workflow of authentication in Shiro,
+the Authenticator represents the actual implementation component that performs
identity verification.
+
+[#Authenticator-Role]
+== Role in the SecurityManager
+
+The link:/securitymanager.html[SecurityManager] does not perform
authentication directly.
+Instead, it delegates authentication requests to its internal `Authenticator`
instance.
+When a link:/subject.html[Subject] calls
link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#login(org.apache.shiro.authc.AuthenticationToken)[`login(token)`],
+the SecurityManager receives the request and immediately delegates to the
Authenticator by calling
+link:/static/current/apidocs/org/apache/shiro/authc/Authenticator.html#authenticate(org.apache.shiro.authc.AuthenticationToken)[`authenticate(token)`].
+
+The Authenticator takes the submitted
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationToken.html[`AuthenticationToken`]
+and uses it to verify the Subject's identity.
+If verification succeeds, it returns an
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationInfo.html[`AuthenticationInfo`]
object.
+If verification fails, it throws an
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[`AuthenticationException`].
+
+[#Authenticator-ModularRealmAuthenticator]
+== ModularRealmAuthenticator
+
+Shiro uses the
link:/static/current/apidocs/org/apache/shiro/authc/pam/ModularRealmAuthenticator.html[`ModularRealmAuthenticator`]
+by default.
+This implementation supports coordinating one or more link:/realm.html[Realms]
during the authentication process.
+
+When an authentication token is submitted, the ModularRealmAuthenticator:
+
+* Iterates through configured Realms
+* Calls each Realm's
link:/static/current/apidocs/org/apache/shiro/realm/Realm.html#supports(org.apache.shiro.authc.AuthenticationToken)[`supports(token)`]
method to determine if the Realm can process the token
+* If a Realm supports the token, its
link:/static/current/apidocs/org/apache/shiro/realm/Realm.html#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)[`getAuthenticationInfo(token)`]
method is invoked
+* Returns authentication information if successful, or throws an exception if
failed
+
+[#Authenticator-SingleVsMultipleRealms]
+== 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
link:/static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html[`AuthenticationStrategy`]
+to determine how to coordinate authentication across the Realms.
+This is a
link:https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules[PAM]-style
approach where each Realm can be consulted in sequence.
+
+[#Authenticator-AuthenticationStrategy]
+== AuthenticationStrategy
+
+When multiple Realms are configured, the Authenticator must determine if the
overall authentication attempt succeeds or fails.
+The
link:/static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html[`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.
+
+[#Authenticator-Configuration]
+== Configuration
+
+You can configure a custom Authenticator in your Shiro configuration if needed:
+
+[source,ini]
+----
+authenticator = com.foo.bar.CustomAuthenticator
+securityManager.authenticator = $authenticator
+----
+
+You can also configure the AuthenticationStrategy:
+
+[source,ini]
+----
+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.
+
+[#Authenticator-RealmInteraction]
+== 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 link:/realm.html[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.
diff --git a/src/site/content/authorization.adoc
b/src/site/content/authorization.adoc
index 5e00e7f1a..a66e24047 100644
--- a/src/site/content/authorization.adoc
+++ b/src/site/content/authorization.adoc
@@ -526,6 +526,8 @@ We've taken our previous architecture diagram from the
link:architecture.html[Ar
[#Authentication-AuthorizingSubjects-ModularRealmAuthorizer]
=== Modular Realm Authorizer
+For a standalone overview of the component, see link:authorizer.html[Apache
Shiro Authorizers].
+
As mentioned earlier, the Shiro `SecurityManager` implementations default to
using a
link:static/current/apidocs/org/apache/shiro/authz/ModularRealmAuthorizer.html[`ModularRealmAuthorizer`]
instance. The `ModularRealmAuthorizer` equally supports applications with
single Realm as well as those with multiple realms.
For any authorization operation, the `ModularRealmAuthorizer` will iterate
over its internal collection of `Realms` and interact with each one in
iteration order. Each `Realm` interaction functions as follows:
diff --git a/src/site/content/authorizer.adoc b/src/site/content/authorizer.adoc
index 7b9ca4a8f..076aabd89 100644
--- a/src/site/content/authorizer.adoc
+++ b/src/site/content/authorizer.adoc
@@ -1,8 +1,134 @@
-= Authorizer
-:jbake-type: lend_a_hand
+[#Authorizer-UnderstandingAuthorizers]
+= Apache Shiro Authorizers
+:jbake-date: 2010-03-18 00:00:00
+:jbake-type: page
:jbake-status: published
-:jbake-tags: documentation, todo, lend-a-hand
+:jbake-tags: authorizer, authorization, access-control, permissions, roles
+:jbake-description: Understanding Apache Shiro Authorizers - the component
that determines what authenticated users are allowed to do. Learn how
Authorizers work with Realms to evaluate permissions and roles.
:idprefix:
:icons: font
+:toc:
-TODO
+An `Authorizer` is a component responsible for determining whether a user is
allowed to perform a certain action.
+It evaluates whether a `Subject` has the necessary permissions or roles to
access a resource or perform an operation.
+
+While the link:/authorization.html[Authorization] documentation explains the
concepts and workflow of access control in Shiro,
+the Authorizer represents the actual implementation component that performs
access control decisions.
+
+[#Authorizer-Role]
+== Role in the SecurityManager
+
+The link:/securitymanager.html[SecurityManager] does not perform authorization
checks directly.
+Instead, it delegates authorization decisions to its internal `Authorizer`
instance.
+When a link:/subject.html[Subject] calls authorization methods such as
+link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)[`hasRole(role)`],
+link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(org.apache.shiro.authz.Permission)[`isPermitted(permission)`],
+or their variants, the SecurityManager delegates to the Authorizer.
+
+The Authorizer determines whether the Subject is permitted to perform the
requested action by checking the Subject's roles and permissions.
+If the Subject has the necessary role or permission, the authorization check
passes.
+If not, an
link:/static/current/apidocs/org/apache/shiro/authz/AuthorizationException.html[`AuthorizationException`]
may be thrown.
+
+[#Authorizer-ModularRealmAuthorizer]
+== ModularRealmAuthorizer
+
+Shiro uses the
link:/static/current/apidocs/org/apache/shiro/authz/ModularRealmAuthorizer.html[`ModularRealmAuthorizer`]
+by default.
+This implementation supports coordinating one or more link:/realm.html[Realms]
during the authorization process.
+
+When an authorization check is performed, the ModularRealmAuthorizer:
+
+* Iterates through configured Realms
+* For each Realm that implements the `Authorizer` interface, calls the
corresponding authorization method
+ (`hasRole*`, `checkRole*`, `isPermitted*`, or `checkPermission*`)
+* Aggregates and evaluates the results according to Shiro's authorization
semantics
+* Returns the authorization decision to the caller
+
+It is important to note that the ModularRealmAuthorizer treats Realms
differently depending on whether they implement the `Authorizer` interface.
+If a Realm does not implement `Authorizer`, it is not consulted for
authorization checks.
+
+[#Authorizer-PermissionAndRoleChecks]
+== Permission and Role Checks
+
+The Authorizer performs two types of authorization checks:
+
+[#Authorizer-PermissionChecks]
+=== Permission Checks
+
+Permission checks verify whether a Subject is allowed to perform a specific
action on a specific resource.
+Methods for permission checks include:
+
+*
link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(org.apache.shiro.authz.Permission)[`isPermitted(permission)`]
- returns `true` or `false`
+*
link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#checkPermission(org.apache.shiro.authz.Permission)[`checkPermission(permission)`]
- throws an exception on failure
+
+For example:
+
+[source,java]
+----
+if (subject.isPermitted("account:read")) {
+ //User can read accounts
+}
+
+subject.checkPermission("document:delete:report123");
+----
+
+[#Authorizer-RoleChecks]
+=== Role Checks
+
+Role checks verify whether a Subject has a specific role. Methods for role
checks include:
+
+*
link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)[`hasRole(role)`]
- returns `true` or `false`
+*
link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRole(java.lang.String)[`checkRole(role)`]
- throws an exception on failure
+
+For example:
+
+[source,java]
+----
+if (subject.hasRole("admin")) {
+ //User is an administrator
+}
+
+subject.checkRole("user");
+----
+
+[#Authorizer-Configuration]
+== Configuration
+
+You can configure a custom Authorizer in your Shiro configuration if needed:
+
+[source,ini]
+----
+authorizer = com.foo.bar.CustomAuthorizer
+securityManager.authorizer = $authorizer
+----
+
+However, in most cases, the default ModularRealmAuthorizer is sufficient for
typical applications.
+
+[#Authorizer-RealmInteraction]
+== How Authorizers Work with Realms
+
+The Authorizer does not directly know where to retrieve authorization data.
+Instead, it coordinates with configured Realms to perform the actual
authorization checks.
+
+A link:/realm.html[Realm] is a security-specific data access object that knows
how to retrieve authorization data from a data source
+(database, LDAP, file system, etc.).
+The Realm is responsible for:
+
+* Determining if it implements the `Authorizer` interface (which indicates it
can perform authorization checks)
+* Retrieving the Subject's roles and permissions from the data source
+* Evaluating whether the Subject has the requested role or permission
+* Returning the results of the authorization check
+
+The Authorizer simply orchestrates this process by delegating to Realms and
aggregating their results.
+This allows you to use multiple Realms where authorization data may come from
different sources,
+and Shiro will coordinate the results appropriately.
+
+[#Authorizer-MultipleRealms]
+== Authorization with Multiple Realms
+
+When multiple Realms are configured, the ModularRealmAuthorizer consults all
Realms that implement the `Authorizer` interface.
+The results are aggregated to determine the final authorization decision.
+
+Typically, if any Realm grants permission or role membership, the
authorization check succeeds.
+However, the exact behavior depends on the authorization data model and how
the Realms are configured.
+Custom Authorizer implementations can be used to implement different
aggregation strategies if needed.
diff --git a/src/site/content/issues.adoc b/src/site/content/issues.adoc
index 79904b4a9..994160f5f 100644
--- a/src/site/content/issues.adoc
+++ b/src/site/content/issues.adoc
@@ -2,8 +2,8 @@
:jbake-date: 2010-03-18 00:00:00
:jbake-type: page
:jbake-status: published
-:jbake-tags: issues, bugs, jira, bug-tracking, support
-:jbake-description: Report bugs, request features, and track issues for Apache
Shiro using GitHub Issues tracking system.
+:jbake-tags: issues, bugs, bug-tracking, support
+:jbake-description: Report bugs, request features, and track issues for Apache
Shiro using GitHub Issues.
:idprefix:
:icons: font
