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/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