diff --git a/src/site/content/10-minute-tutorial.adoc b/src/site/content/10-minute-tutorial.adoc index e9976a2662..dcdabc99ae 100644 --- a/src/site/content/10-minute-tutorial.adoc +++ b/src/site/content/10-minute-tutorial.adoc @@ -9,7 +9,7 @@ Brian Demers == Introduction -Welcome to Apache Shiro's 10 Minute Tutorial! +Welcome to Apache Shiro's 10-Minute Tutorial! By going through this quick and simple tutorial you should fully understand how a developer uses Shiro in their application. And you should be able to do it in under 10 minutes. @@ -37,7 +37,7 @@ Now let's actually do something! [NOTE] ==== -Shiro can be run in any environment, from the simplest command line application to the biggest enterprise web and clustered applications, but we''ll use the simplest possible example in a simple `main` method for this QuickStart so you can get a feel for the API.') +Shiro can be run in any environment, from the simplest command line application to the biggest enterprise web and clustered applications, but we''ll use the simplest possible example in a simple `main` method for this QuickStart, so you can get a feel for the API.') ==== == Download @@ -71,7 +71,7 @@ Change that file and run the above `mvn compile exec:java` command as often as y == Quickstart.java The `Quickstart.java` file referenced above contains all the code that will get you familiar with the API. -Now lets break it down in chunks here so you can easily understand what is going on. +Now lets break it down in chunks here, so you can easily understand what is going on. In almost all environments, you can obtain the currently executing user via the following call: @@ -153,7 +153,7 @@ There are many different types of exceptions you can check, or throw your own fo Security best practice is to give generic login failure messages to users because you do not want to aid an attacker trying to break into your system. ==== -Ok, so by now, we have a logged in user. +Ok, so by now, we have a logged-in user. What else can we do? Let's say who they are: @@ -210,7 +210,7 @@ currentUser.logout(); //removes all identifying information and invalidates thei Well, that's the core to using Apache Shiro at the application-developer level. And although there is some pretty sophisticated stuff going on under the hood to make this work so elegantly, that's really all there is to it. -But you might ask yourself, "But who is responsible for getting the user data during a login (usernames and passwords, role and permissions, etc), and who actually performs those security checks during runtime?" Well, you do, by implementing what Shiro calls a [Realm](realm.html "Realm") and plugging that `Realm` into Shiro's configuration. +But you might ask yourself, "But who is responsible for getting the user data during a login (usernames and passwords, role and permissions, etc.), and who actually performs those security checks during runtime?" Well, you do, by implementing what Shiro calls a [Realm](realm.html "Realm") and plugging that `Realm` into Shiro's configuration. However, how you configure a [Realm](realm.html "Realm") is largely dependent upon your runtime environment. For example, if you run a standalone application, or if you have a web based application, or a Spring or JEE container-based application, or combination thereof. diff --git a/src/site/content/architecture.adoc b/src/site/content/architecture.adoc index 721e8cd352..9642177997 100644 --- a/src/site/content/architecture.adoc +++ b/src/site/content/architecture.adoc @@ -19,7 +19,7 @@ At the highest conceptual level, Shiro's architecture has 3 primary concepts: th image::/images/ShiroBasicArchitecture.png[Shiro Basic Architecture Diagram, align="center"] -* *Subject*: As we've mentioned in our link:tutorial.html[Tutorial], the `Subject` is essentially a security specific 'view' of the the currently executing user. Whereas the word 'User' often implies a human being, a `Subject` can be a person, but it could also represent a 3rd-party service, daemon account, cron job, or anything similar - basically anything that is currently interacting with the software. +* *Subject*: As we've mentioned in our link:tutorial.html[Tutorial], the `Subject` is essentially a security specific 'view' of the currently executing user. Whereas the word 'User' often implies a human being, a `Subject` can be a person, but it could also represent a 3rd-party service, daemon account, cron job, or anything similar - basically anything that is currently interacting with the software. + `Subject` instances are all bound to (and require) a `SecurityManager`. When you interact with a `Subject`, those interactions translate to subject-specific interactions with the `SecurityManager`. @@ -38,7 +38,7 @@ The following diagram shows Shiro's core architectural concepts followed by shor image::/images/ShiroArchitecture.png[Shiro Architecture Diagram, align="center"] * *Subject* (link:static/current/apidocs/org/apache/shiro/subject/Subject.html[`org.apache.shiro.subject.Subject`]) -A security-specific 'view' of the entity (user, 3rd-party service, cron job, etc) currently interacting with the software. +A security-specific 'view' of the entity (user, 3rd-party service, cron job, etc.) currently interacting with the software. * *SecurityManager* (link:static/current/apidocs/org/apache/shiro/mgt/SecurityManager.html[org.apache.shiro.mgt.SecurityManager]) 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. @@ -62,7 +62,7 @@ The `SessionDAO` performs `Session` persistence (CRUD) operations on behalf of t The `CacheManager` creates and manages `Cache` instance lifecycles used by other Shiro components. Because Shiro can access many back-end data sources for authentication, authorization and session management, caching has always been a first-class architectural feature in the framework to improve performance while using these data sources. Any of the modern open-source and/or enterprise caching products can be plugged in to Shiro to provide a fast and efficient user-experience. * *Cryptography* (link:static/current/apidocs/org/apache/shiro/crypto/package-summary.html[org.apache.shiro.crypto.*]) -Cryptography is a natural addition to an enterprise security framework. Shiro's `crypto` package contains easy-to-use and understand representations of crytographic Ciphers, Hashes (aka digests) and different codec implementations. All of the classes in this package are carefully designed to be very easy to use and easy to understand. Anyone who has used Java's native cryptography support knows it can be a challenging animal to tame. Shiro's crypto APIs simplify the complicated Java mechanisms and make cryptography easy to use for normal mortal human beings. +Cryptography is a natural addition to an enterprise security framework. Shiro's `crypto` package contains easy-to-use and understand representations of crytographic Ciphers, Hashes (aka digests) and different codec implementations. All the classes in this package are carefully designed to be very easy to use and easy to understand. Anyone who has used Java's native cryptography support knows it can be a challenging animal to tame. Shiro's crypto APIs simplify the complicated Java mechanisms and make cryptography easy to use for normal mortal human beings. * *Realms* (link:static/current/apidocs/org/apache/shiro/realm/Realm.html[org.apache.shiro.realm.Realm]) As mentioned above, Realms act as the ‘bridge’ or ‘connector’ between Shiro and your application’s security data. When it comes time to actually interact with security-related data like user accounts to perform authentication (login) and authorization (access control), Shiro looks up many of these things from one or more Realms configured for an application. You can configure as many `Realms` as you need (usually one per data source) and Shiro will coordinate with them as necessary for both authentication and authorization. diff --git a/src/site/content/articles.adoc b/src/site/content/articles.adoc index 88ebd93cef..217c04684a 100644 --- a/src/site/content/articles.adoc +++ b/src/site/content/articles.adoc @@ -60,4 +60,4 @@ Once you've gotten your feet wet, you might find these useful too: * *https://techbeats.deluan.com/apache-shiro-tags-for-jsffacelets[Apache Shiro tags for JSF - Securing Your JSF Pages]* by Deluan Quintão on 1 November 2010. -* *Shiro DevNexus 2009 Presentation* by Jeremy Haile: (link:files/articles/Ki-DevNexus-2009.pdf?version=1&modificationDate=1246602947000[PDF]) (link:files/articles/Ki-DevNexus-2009.key.zip?version=1&modificationDate=1246602947000[Keynote]) (link:files/articles/Ki-DevNexus-2009.ppt.zip?version=1&modificationDate=1246602947000[Powerpoint]) +* *Shiro DevNexus 2009 Presentation* by Jeremy Haile: (link:files/articles/Ki-DevNexus-2009.pdf?version=1&modificationDate=1246602947000[PDF]) (link:files/articles/Ki-DevNexus-2009.key.zip?version=1&modificationDate=1246602947000[Keynote]) (link:files/articles/Ki-DevNexus-2009.ppt.zip?version=1&modificationDate=1246602947000[PowerPoint]) diff --git a/src/site/content/authentication.adoc b/src/site/content/authentication.adoc index efa37ecacd..69fc1eb225 100644 --- a/src/site/content/authentication.adoc +++ b/src/site/content/authentication.adoc @@ -160,12 +160,12 @@ For example, a check to see if a `Subject` can access financial information shou [#Authentication-RememberedVsAuthenticated-AnIllustratingExample] === An illustrating example -The following is a fairly common scenario that helps illustrate why the the distinction between remembered and authenticated is important. +The following is a fairly common scenario that helps illustrate why the distinction between remembered and authenticated is important. Let's say you're using https://www.amazon.com[Amazon.com]. You've logged-in successfully and have added a few books to your shopping cart. But you have to run off to a meeting, but forget to log out. -By the time the meeting is over, it's time to go home and you leave the office. +By the time the meeting is over, it's time to go home, and you leave the office. The next day when you come in to work, you realize you didn't complete your purchase, so you go back to amazon.com. This time, Amazon 'remembers' who you are, greets you by name, and still gives you some personalized book recommendations. @@ -174,10 +174,10 @@ To Amazon, `subject.isRemembered()` would return `true`. But, what happens if you try to access your account to update your credit card information to make your book purchase? While Amazon 'remembers' you (`isRemembered()` == `true`), it cannot guarantee that you are in fact you (for example, maybe a co-worker is using your computer). -So before you can perform a sensitive action like updating credit card information, Amazon will force you to login so they can guarantee your identity. -After you login, your identity has been verified and to Amazon, `isAuthenticated()` would now be `true`. +So before you can perform a sensitive action like updating credit card information, Amazon will force you to login, so they can guarantee your identity. +After you log in, your identity has been verified and to Amazon, `isAuthenticated()` would now be `true`. -This scenario happens so frequently for many types of applications, so the functionality is built in to Shiro so you can leverage it for your own application. +This scenario happens so frequently for many types of applications, so the functionality is built in to Shiro, so you can leverage it for your own application. Now, whether you use `isRemembered()` or `isAuthenticated()` to customize your views and workflows is up to you, but Shiro will maintain this fundamental state in case you need it. [#Authentication-LoggingOut] @@ -276,9 +276,9 @@ An AuthenticationStrategy is a stateless component that is consulted 4 times dur . before any of the Realms are invoked . immediately before an individual Realm's `getAuthenticationInfo` method is called . immediately after an individual Realm's `getAuthenticationInfo` method is called -. after all of the Realms have been invoked +. after all the Realms have been invoked -Also an `AuthenticationStrategy` is responsible for aggregating the results from each successful Realm and 'bundling' them into a single link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationInfo.html[`AuthenticationInfo`] representation. +Also, an `AuthenticationStrategy` is responsible for aggregating the results from each successful Realm and 'bundling' them into a single link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationInfo.html[`AuthenticationInfo`] representation. 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). [NOTE] @@ -293,7 +293,7 @@ Shiro has 3 concrete `AuthenticationStrategy` implementations: |`AuthenticationStrategy` class |Description |link:/static/current/apidocs/org/apache/shiro/authc/pam/AtLeastOneSuccessfulStrategy.html[`AtLeastOneSuccessfulStrategy`] |If one (or more) Realms authenticate successfully, the overall attempt is considered successful. -If none authenticate succesfully, the attempt fails. +If none authenticate successfully, the attempt fails. |link:/static/current/apidocs/org/apache/shiro/authc/pam/FirstSuccessfulStrategy.html[`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. @@ -379,7 +379,7 @@ securityManager.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. +This is different from implicit realm ordering where all available realms will be used. ==== [#Authentication-RealmAuthentication] diff --git a/src/site/content/authorization-features.adoc b/src/site/content/authorization-features.adoc index 2a5591bdce..b0f2f3fd0a 100644 --- a/src/site/content/authorization-features.adoc +++ b/src/site/content/authorization-features.adoc @@ -11,7 +11,7 @@ In other words, determining *"who has access to what"*. Authorization is used to answer security questions like, "is the user allowed to edit accounts", "is this user allowed to view this web page", "does this user have access to this button"? These are all decisions determining what a user has access to and therefore all represent authorization checks. -Authorization is a critical element of any application but it can quickly become very complex. +Authorization is a critical element of any application, but it can quickly become very complex. Shiro's goal is to eliminate much of the complexity around authorization so that you can more easily build secure software. Below is a highlight of the Shiro authorization features. @@ -29,9 +29,9 @@ Since the complexity of authorization differs greatly between applications, Shir * *Powerful and intuitive permission syntax* + -As an option, Shiro provides an out-of-the-box permission syntax, called Wildcard Permissions, that help you model the fine grained access policies your application may have. -By using Shiro's Wildcard Permissions you get an easy-to-process and human readable syntax. -Moreoever, you don't have to go through the time-consuming effort and complexity of creating your own method for representing your access policies. +As an option, Shiro provides an out-of-the-box permission syntax, called Wildcard Permissions, that help you model the fine-grained access policies your application may have. +By using Shiro's Wildcard Permissions you get an easy-to-process and human-readable syntax. +Moreover, you don't have to go through the time-consuming effort and complexity of creating your own method for representing your access policies. * *Multiple enforcement options* + diff --git a/src/site/content/authorization.adoc b/src/site/content/authorization.adoc index 3842c8ee94..9a6df0c750 100644 --- a/src/site/content/authorization.adoc +++ b/src/site/content/authorization.adoc @@ -52,7 +52,7 @@ We'll cover how Shiro determines if a `Subject` is permitted to do something or [#Authentication-ElementsOfAuthorization-Permissions-PermissionGranularity] ==== Permission Granularity -The permission examples above all specify actions (open, read, delete, etc) on a resource type (door, file, customer, etc). In some cases, they even specify very fine-grained _instance-level_ behavior - for example, 'delete' (action) the 'user' (resource type) with username 'jsmith' (instance identifier). In Shiro, you have the ability to define exactly how granular those statements can be. +The permission examples above all specify actions (open, read, delete, etc.) on a resource type (door, file, customer, etc). In some cases, they even specify very fine-grained _instance-level_ behavior - for example, 'delete' (action) the 'user' (resource type) with username 'jsmith' (instance identifier). In Shiro, you have the ability to define exactly how granular those statements can be. We cover permission granularity and 'levels' of permission statements in much more detail in Shiro's link:permissions.html[Permissions Documentation]. @@ -91,7 +91,7 @@ A user essentially is the 'who' of an application. As we've covered previously h Users (Subjects) are allowed to perform certain actions in your application through their association with roles or direct permissions. Your application's data model defines exactly how a `Subject` is allowed to do something or not. -For example, in your data model, perhaps you have an actual `User` class and you assign permissions directly to `User` instances. Or maybe you assign permissions only to `Roles` directly, and then assign Roles to `Users`, so by association, `Users` transitively 'have' the permissions assigned to their roles. Or you could represent these things with a 'Group' concept. It is up to you - use what makes sense for your application. +For example, in your data model, perhaps you have an actual `User` class, and you assign permissions directly to `User` instances. Or maybe you assign permissions only to `Roles` directly, and then assign Roles to `Users`, so by association, `Users` transitively 'have' the permissions assigned to their roles. Or you could represent these things with a 'Group' concept. It is up to you - use what makes sense for your application. Your data model defines exactly how authorization will function. Shiro relies on a link:realm.html[Realm] implementation to translate your data model association details into a format Shiro understands. We'll cover how Realms do this a little later. @@ -99,7 +99,7 @@ Your data model defines exactly how authorization will function. Shiro relies on ==== .Note Ultimately, your link:realm.html[Realm] implementation is what communicates with your data source (RDBMS, LDAP, etc). -So your realm is what will tell Shiro whether or not roles or permissions exist. You have full control over how your authorization model is structured and defined. +So your realm is what will tell Shiro whether roles or permissions exist. You have full control over how your authorization model is structured and defined. ==== [#Authentication-AuthorizingSubjects] @@ -146,8 +146,8 @@ There are few role-oriented `Subject` methods you can call, depending on your ne |Subject Method |Description |link:static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)[`hasRole(String roleName)`] |Returns `true` if the `Subject` is assigned the specified role, `false` otherwise. -|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRoles(java.util.List)[`hasRoles(List<String> roleNames)`] |Returns a array of `hasRole` results corresponding to the indices in the method argument. Useful as a performance enhancement if many role checks need to be performed (e.g. when customizing a complex view) -|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#hasAllRoles(java.util.Collection)[`hasAllRoles(Collection<String> roleNames)`] |Returns `true` if the `Subject` is assigned _all_ of the specified roles, `false` otherwise. +|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRoles(java.util.List)[`hasRoles(List<String> roleNames)`] |Returns an array of `hasRole` results corresponding to the indices in the method argument. Useful as a performance enhancement if many role checks need to be performed (e.g. when customizing a complex view) +|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#hasAllRoles(java.util.Collection)[`hasAllRoles(Collection<String> roleNames)`] |Returns `true` if the `Subject` is assigned _all_ the specified roles, `false` otherwise. |=== [#Authentication-AuthorizingSubjects-ProgrammaticAuthorization-RoleBasedAuthorization-Assertions] @@ -175,7 +175,7 @@ There are few role-oriented `Subject` assertion methods you can call, depending |Subject Method |Description |link:static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRole(java.lang.String)[`checkRole(String roleName)`] |Returns quietly if the `Subject` is assigned the specified role or throws an `AuthorizationException` if not. -|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRoles(java.util.Collection)[`checkRoles(Collection<String> roleNames)`] |Returns quietly if the `Subject` is assigned _all_ of the specified role or throws an `AuthorizationException` if not. +|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRoles(java.util.Collection)[`checkRoles(Collection<String> roleNames)`] |Returns quietly if the `Subject` is assigned _all_ the specified role or throws an `AuthorizationException` if not. |link:++static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRoles(java.lang.String...)++[`checkRoles(String... roleIdentifiers)`] |Same effect as the `checkRoles` method above, but allows Java 5 var-args style arguments. |=== @@ -225,13 +225,13 @@ There are few Object permission-oriented `Subject` methods you can call, dependi |link:static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(org.apache.shiro.authz.Permission)[`isPermitted(Permission p)`] |Returns `true` if the `Subject` is permitted to perform an action or access a resource summarized by the specified `Permission` instance, `false` otherwise. |link:static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(java.util.List)[`isPermitted(List<Permission> perms)`] |Returns an array of `isPermitted` results corresponding to the indices in the method argument. Useful as a performance enhancement if many permission checks need to be performed (e.g. when customizing a complex view) -|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermittedAll(java.util.Collection)[`isPermittedAll(Collection<Permission> perms)`] |Returns `true` if the `Subject` is permitted _all_ of the specified permissions, `false` otherwise. +|link:static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermittedAll(java.util.Collection)[`isPermittedAll(Collection<Permission> perms)`] |Returns `true` if the `Subject` is permitted _all_ the specified permissions, `false` otherwise. |=== [#Authentication-AuthorizingSubjects-ProgrammaticAuthorization-PermissionBasedAuthorization-StringBasedPermissionChecks] ===== String-based permission checks -While Object-based permissions can be useful (compile-time type-safety, guaranteed behavior, customized implication logic, etc), they can sometimes feel a bit 'heavy handed' for many applications. An alternative is to use normal `Strings` to represent a permission instance. +While Object-based permissions can be useful (compile-time type-safety, guaranteed behavior, customized implication logic, etc.), they can sometimes feel a bit 'heavy-handed' for many applications. An alternative is to use normal `Strings` to represent a permission instance. For example, based on the print permission example above, we can re-formulate that same check as a `String`-based permission check: @@ -278,7 +278,7 @@ Like the Object-based permission check methods, there are String variants to sup |link:static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(java.lang.String)[`isPermitted(String perm)`] |Returns `true` if the `Subject` is permitted to perform an action or access a resource summarized by the specified `String` permission, `false` otherwise. |link:static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(java.util.List)[`isPermitted(List perms)`] |Returns an array of `isPermitted` results corresponding to the indices in the method argument. Useful as a performance enhancement if many `String` permission checks need to be performed (e.g. when customizing a complex view) -|link:++static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermittedAll(java.lang.String...)++[`isPermittedAll(String... perms)`] |Returns `true` if the `Subject` is permitted _all_ of the specified `String` permissions, `false` otherwise. +|link:++static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermittedAll(java.lang.String...)++[`isPermittedAll(String... perms)`] |Returns `true` if the `Subject` is permitted _all_ the specified `String` permissions, `false` otherwise. |=== [#Authentication-AuthorizingSubjects-ProgrammaticAuthorization-PermissionBasedAuthorization-PermissionAssertions] @@ -533,7 +533,7 @@ For any authorization operation, the `ModularRealmAuthorizer` will iterate over .. If the Realm's method results in an exception, the exception is propagated as an link:static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[`AuthorizationException`] to the `Subject` caller. This short-circuits the authorization process and any remaining Realms will not be consulted for that authorization operation. -.. If the Realm's method is a `hasRole*` or `isPermitted*` variant that returns a boolean and that return value is `true`, the `true` value is returned immediately and any remaining Realms are short circuited. This behavior exists as a performance enhancement, as typically if permitted by one Realm, it is implied that the Subject is permitted. This favors security policies where everything is prohibited by default and things are explicitly allowed, the most secure type of security policy. +.. If the Realm's method is a `hasRole*` or `isPermitted*` variant that returns a boolean and that return value is `true`, the `true` value is returned immediately and any remaining Realms are short-circuited. This behavior exists as a performance enhancement, as typically if permitted by one Realm, it is implied that the Subject is permitted. This favors security policies where everything is prohibited by default and things are explicitly allowed, the most secure type of security policy. . If the Realm does not implement the `Authorizer` interface, it is ignored. @@ -572,7 +572,7 @@ securityManager.authorizer.permissionResolver = $globalPermissionResolver [WARNING] ==== .PermissionResolverAware -If you want to configure a global `PermissionResolver`, each `Realm` that is to receive the configured `PermissionResolver` *must* implement the link:static/current/apidocs/src-html/org/apache/shiro/authz/permission/PermissionResolverAware.html[`PermisionResolverAware`] interface. +If you want to configure a global `PermissionResolver`, each `Realm` that is to receive the configured `PermissionResolver` *must* implement the link:static/current/apidocs/src-html/org/apache/shiro/authz/permission/PermissionResolverAware.html[`PermissionResolverAware`] interface. This guarantees that the configured instance can be relayed to each `Realm` that supports such configuration. If you don't want to use a global `PermissionResolver` or you don't want to be bothered with the `PermissionResolverAware` interface, you can always configure a realm with a `PermissionResolver` instance explicitly (assuming there is a JavaBeans-compatible setPermissionResolver method). ==== @@ -617,7 +617,7 @@ securityManager.authorizer.rolePermissionResolver = $globalRolePermissionResolve ==== .RolePermissionResolverAware If you want to configure a global `RolePermissionResolver`, each `Realm` that is to receive the configured `RolePermissionResolver` *must* implement the -link:static/current/apidocs/org/apache/shiro/authz/permission/RolePermissionResolverAware.html[`RolePermisionResolverAware`] interface. +link:static/current/apidocs/org/apache/shiro/authz/permission/RolePermissionResolverAware.html[`RolePermissionResolverAware`] interface. This guarantees that the configured global `RolePermissionResolver` instance can be relayed to each `Realm` that supports such configuration. If you don't want to use a global `RolePermissionResolver` or you don't want to be bothered with the `RolePermissionResolverAware` interface, you can always configure a realm with a `RolePermissionResolver` instance explicitly (assuming there is a JavaBeans-compatible setRolePermissionResolver method). diff --git a/src/site/content/blog/2010/09/14/ibm-developerworks-introduction-to-apache-shiro.adoc b/src/site/content/blog/2010/09/14/ibm-developerworks-introduction-to-apache-shiro.adoc index 70d1b67e8d..42761f2683 100644 --- a/src/site/content/blog/2010/09/14/ibm-developerworks-introduction-to-apache-shiro.adoc +++ b/src/site/content/blog/2010/09/14/ibm-developerworks-introduction-to-apache-shiro.adoc @@ -7,4 +7,4 @@ Les Hazlewood :idprefix: Nathan Good wrote link:https://www.ibm.com/developerworks/web/library/wa-apacheshiro/[an article] introducing some of Apache Shiro's capabilities. -Thanks Nathan! +Thanks, Nathan! diff --git a/src/site/content/blog/2010/09/24/apache-shiro-becomes-an-apache-top-level-project.adoc b/src/site/content/blog/2010/09/24/apache-shiro-becomes-an-apache-top-level-project.adoc index d0fad2b0b4..8d29575cdd 100644 --- a/src/site/content/blog/2010/09/24/apache-shiro-becomes-an-apache-top-level-project.adoc +++ b/src/site/content/blog/2010/09/24/apache-shiro-becomes-an-apache-top-level-project.adoc @@ -6,7 +6,7 @@ Les Hazlewood :jbake-tags: blog, apache :idprefix: -On Wednesday, September 22nd jbake.content.blog.2010, the Apache Software Foundation Board voted unanimously to accept Apache Shiro's graduation out of the Incubator and to become a Apache Top Level Project. +On Wednesday, September 22nd, the Apache Software Foundation Board voted unanimously to accept Apache Shiro's graduation out of the Incubator and to become a Apache Top Level Project. Many thanks to the entire community for the continued growth and support, and especially to our Mentors, for helping us navigate the project through the incubation process. Everything is much appreciated and it has been well worth it. diff --git a/src/site/content/blog/2020/03/25/apache-shiro-152-released.adoc b/src/site/content/blog/2020/03/25/apache-shiro-152-released.adoc index 7d51b79070..5841b27af7 100644 --- a/src/site/content/blog/2020/03/25/apache-shiro-152-released.adoc +++ b/src/site/content/blog/2020/03/25/apache-shiro-152-released.adoc @@ -9,7 +9,7 @@ The Shiro team is pleased to announce the release of Apache Shiro version 1.5.2. This is a feature release for 1.x. -This release includes 3 issues resolved since the 1.5.1 release and isavailable for Download now. +This release includes 3 issues resolved since the 1.5.1 release and is available for download now. Of Note: diff --git a/src/site/content/cachemanager.adoc b/src/site/content/cachemanager.adoc index fbe6874d6f..0aac1efc83 100644 --- a/src/site/content/cachemanager.adoc +++ b/src/site/content/cachemanager.adoc @@ -34,9 +34,9 @@ securityManager.cacheManager = $cacheManager ---- We have an out-of-the-box link:static/current/apidocs/org/apache/shiro/cache/ehcache/EhCacheManager.html[`+EhCacheManager+`] implementation, so you can use that today if you wanted. -Otherwise, you can implement your own `+CacheManager+` (e.g. with Coherence, etc) and configure it as above, and you’ll be good to go. +Otherwise, you can implement your own `+CacheManager+` (e.g. with Coherence, etc.) and configure it as above, and you’ll be good to go. == Authorization Cache Invalidation [[CacheManager-AuthorizationCacheInvalidation]] -Finally note that link:static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html[`+AuthorizingRealm+`] has a link:static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html#clearCachedAuthorizationInfo%28org.apache.shiro.subject.PrincipalCollection%29[`+clearCachedAuthorizationInfo+`] method that can be called by subclasses to evict the cached authzInfo for a particular account. +Finally, note that link:static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html[`+AuthorizingRealm+`] has a link:static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html#clearCachedAuthorizationInfo%28org.apache.shiro.subject.PrincipalCollection%29[`+clearCachedAuthorizationInfo+`] method that can be called by subclasses to evict the cached authzInfo for a particular account. It is usually called by custom logic if the corresponding account’s authz data has changed (to ensure the next authz check will pick up the new data). diff --git a/src/site/content/caching.adoc b/src/site/content/caching.adoc index ca96ee2020..63094a8766 100644 --- a/src/site/content/caching.adoc +++ b/src/site/content/caching.adoc @@ -101,7 +101,7 @@ TBD == Authorization Cache Invalidation -Finally note that +Finally, note that link:static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html[`+AuthorizingRealm+`] has a link:static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html#clearCachedAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)[clearCachedAuthorizationInfo diff --git a/src/site/content/cas.adoc b/src/site/content/cas.adoc index 2233bd0529..570eb8e76b 100644 --- a/src/site/content/cas.adoc +++ b/src/site/content/cas.adoc @@ -22,7 +22,7 @@ The _shiro-cas_ module is made to protect a web application with a https://wiki. == Basic understanding of the CAS protocol . If you want to access an application protected by a CAS client and if you are not authenticated in this application, you are redirected by the CAS client to the CAS server login page. -A service parameter in the CAS login url defines the application the user wants to login. +A service parameter in the CAS login url defines the application the user wants to log in. + [source,nohighlight] ---- diff --git a/src/site/content/configuration.adoc b/src/site/content/configuration.adoc index cf0289f2d0..064547f88d 100644 --- a/src/site/content/configuration.adoc +++ b/src/site/content/configuration.adoc @@ -72,7 +72,7 @@ However, even with these caveats, the direct programmatic manipulation approach Most applications instead benefit from text-based configuration that could be modified independently of source code and even make things easier to understand for those not intimately familiar with Shiro's APIs. -To ensure a common-denominator text-based configuration mechanism that can work in all environments with minimal 3rd party dependencies, Shiro supports the link:https://en.wikipedia.org/wiki/INI_file[INI format] to build the `SecurityManager` object graph and its supporting components. INI is easy to read, easy to configure, and is simple to set-up and suits most applications well. +To ensure a common-denominator text-based configuration mechanism that can work in all environments with minimal 3rd party dependencies, Shiro supports the link:https://en.wikipedia.org/wiki/INI_file[INI format] to build the `SecurityManager` object graph and its supporting components. INI is easy to read, easy to configure, and is simple to set up and suits most applications well. [#Configuration-INIConfiguration-CreatingSecurityManagerFromINI] === Creating a SecurityManager from INI @@ -128,7 +128,7 @@ Now that we know how to construct a `SecurityManager` from INI configuration, le [#Configuration-INIConfiguration-Sections] === INI Sections -INI is basically a text configuration consisting of key/value pairs organized by uniquely-named sections. Keys are unique per section only, not over the entire configuration (unlike the JDK https://java.sun.com/javase/6/docs/api/java/util/Properties.html[Properties]). Each section may be viewed like a single `Properties` definition however. +INI is basically a text configuration consisting of key/value pairs organized by uniquely-named sections. Keys are unique per section only, not over the entire configuration (unlike the JDK https://java.sun.com/javase/6/docs/api/java/util/Properties.html[Properties]). Each section may be viewed like a single `Properties` definition, however. Commented lines can start with either with an Octothorpe (# - aka the 'hash', 'pound' or 'number' sign) or a Semi-colon (';') @@ -391,7 +391,7 @@ securityManager.sessionManager.globalSessionTimeout = 1800000 ... ---- -This is because the `securityManager` instance is a special one - it is already instantiated for you and ready to go so you don't need to know the specific `SecurityManager` implementation class to instantiate. +This is because the `securityManager` instance is a special one - it is already instantiated for you and ready to go, so you don't need to know the specific `SecurityManager` implementation class to instantiate. Of course, if you actually _want_ to specify your own implementation, you can, just define your implementation as specified in the "Overriding Instances" section above: @@ -439,7 +439,7 @@ Each line in the [users] section must conform to the following format: [#Configuration-INIConfiguration-Sections-users-EncryptingPasswords] ===== Encrypting Passwords -If you don't want the [users] section passwords to be in plain-text, you can encrypt them using your favorite hash algorithm (MD5, Sha1, Sha256, etc) however you like and use the resulting string as the password value. By default, the password string is expected to be Hex encoded, but can be configured to be Base64 encoded instead (see below). +If you don't want the [users] section passwords to be in plain-text, you can encrypt them using your favorite hash algorithm (MD5, Sha1, Sha256, etc.) however you like and use the resulting string as the password value. By default, the password string is expected to be Hex encoded, but can be configured to be Base64 encoded instead (see below). [NOTE] ==== @@ -495,7 +495,7 @@ goodguy = winnebago:drive:eagle5 [#Configuration-INIConfiguration-Sections-roles-LineFormat] ===== Line Format -Each line in the [roles] section must must define a role-to-permission(s) key/value mapping with in the following format: +Each line in the [roles] section must define a role-to-permission(s) key/value mapping with in the following format: `rolename` = _permissionDefinition1_, _permissionDefinition2_, …, _permissionDefinitionN_ @@ -517,4 +517,4 @@ If you have roles that don't require permission associations, you don't need to [#Configuration-INIConfiguration-Sections-urls] ==== `[urls]` -This section and its options is described in the link:web.html[Web] chapter. +This section and its options are described in the link:web.html[Web] chapter. diff --git a/src/site/content/cryptography-features.adoc b/src/site/content/cryptography-features.adoc index 6e89441e11..d28a7ea0f7 100644 --- a/src/site/content/cryptography-features.adoc +++ b/src/site/content/cryptography-features.adoc @@ -10,7 +10,7 @@ Cryptography is the practice of protecting information from undesired access by hiding it or converting it into nonsense so no one else can read it. Shiro focuses on two core elements of Cryptography: ciphers that encrypt data like email using a public or private key, and hashes (aka message digests) that irreversibly encrypt data like passwords. -Shiro Cryptography's primary goal is take what has traditionally been an extremely complex field and make it easy for the rest of us while providing a robust set of cryptography features. +Shiro Cryptography's primary goal is taking what has traditionally been an extremely complex field and make it easy for the rest of us while providing a robust set of cryptography features. [#CryptographyFeatures-SimplicityFeatures] == Simplicity Features @@ -66,5 +66,5 @@ Shiro's Hash implementations support salts and multiple hash iterations out of t [#CryptographyFeatures-GetStartedin10MinuteswithShiro] == Get Started in 10 Minutes with Shiro -Try out Shiro for yourself with our link:/10-minute-tutorial.html[10 Minute Tutorial]. +Try out Shiro for yourself with our link:/10-minute-tutorial.html[10-Minute Tutorial]. If you have any questions about Shiro, please check out our link:/forums.html[community forum] or link:/mailing-lists.html[user mailing list] for answers from the community. diff --git a/src/site/content/features.adoc b/src/site/content/features.adoc index 848d28671a..6b0de61d56 100644 --- a/src/site/content/features.adoc +++ b/src/site/content/features.adoc @@ -34,4 +34,4 @@ Check out the specific features for each of Shiro's major components: link:authe == Get Started in 10 Minutes with Shiro -Try out Shiro for yourself with our link:10-minute-tutorial.html[10 Minute Tutorial]. And if you have any questions about Shiro, please check out our link:forums.html[community forum] or link:mailing-lists.html[user mailing list] for answers from the community. +Try out Shiro for yourself with our link:10-minute-tutorial.html[10-Minute Tutorial]. And if you have any questions about Shiro, please check out our link:forums.html[community forum] or link:mailing-lists.html[user mailing list] for answers from the community. diff --git a/src/site/content/forums.adoc b/src/site/content/forums.adoc index 6581a5eb10..a207a02e2f 100644 --- a/src/site/content/forums.adoc +++ b/src/site/content/forums.adoc @@ -13,7 +13,7 @@ For users that prefer to use browse the mailing lists with a browser can use htt ____ -*NOTE:* Previously, `nabble.com` was used as an alternative to the mailing list, this service is not longer hosting the mailing list archive. +*NOTE:* Previously, `nabble.com` was used as an alternative to the mailing list, this service is no longer hosting the mailing list archive. ____ diff --git a/src/site/content/guice.adoc b/src/site/content/guice.adoc index 3d207e29cd..2d2bc93bd5 100644 --- a/src/site/content/guice.adoc +++ b/src/site/content/guice.adoc @@ -7,7 +7,7 @@ :icons: font :toc: -Shiro https://github.com/google/guice[Guice] integration was added in Shiro 1.2. This page covers the ways to integrate Shiro into Guice-based applications using standard Guice conventions and mechanisms. Prior to reading this integration document, you should be a least somewhat familiar with Guice. +Shiro https://github.com/google/guice[Guice] integration was added in Shiro 1.2. This page covers the ways to integrate Shiro into Guice-based applications using standard Guice conventions and mechanisms. Prior to reading this integration document, you should be at least somewhat familiar with Guice. == Overview @@ -137,7 +137,7 @@ In the previous code, we have bound an `IniRealm` and setup four filter chains. /** = authcBasic ---- -In shiro-guice, the filter names are Guice keys. All of the default Shiro filters are available as constants, but you are not limited to those. In order to use a custom filter in a filter chain, you would do +In shiro-guice, the filter names are Guice keys. All the default Shiro filters are available as constants, but you are not limited to those. In order to use a custom filter in a filter chain, you would do [source,java] ---- diff --git a/src/site/content/how-to-contribute.adoc b/src/site/content/how-to-contribute.adoc index dac8b102a4..f520e82863 100644 --- a/src/site/content/how-to-contribute.adoc +++ b/src/site/content/how-to-contribute.adoc @@ -9,7 +9,7 @@ == Introduction -Apache Shiro is an https://opensource.org/[Open Source] software security framework that performs authentication, authorization, cryptography and session management. The Shiro Project is an volunteer project released under a link:license.html[liberal license]. Anyone can participate and volunteer. No need to be an experienced developer or have great visions. Roll up your sleeves and come try, help is always welcome, and your input will be appreciated! +Apache Shiro is an https://opensource.org/[Open Source] software security framework that performs authentication, authorization, cryptography and session management. The Shiro Project is a volunteer project released under a link:license.html[liberal license]. Anyone can participate and volunteer. No need to be an experienced developer or have great visions. Roll up your sleeves and come try, help is always welcome, and your input will be appreciated! There are many ways how to contribute to this project, you can participate directly by: * coding @@ -93,7 +93,7 @@ An overview of how to use Git to participate in Shiro development. Beginners, do === Getting Started with Development -Go to https://github.com/apache/shiro[GitHub] and fork the project by pressing the Fork button. Fork makes a copy of an existing repository and you can start doing new development on your copy. +Go to https://github.com/apache/shiro[GitHub] and fork the project by pressing the Fork button. Fork makes a copy of an existing repository, and you can start doing new development on your copy. === Getting Started with Git @@ -141,7 +141,7 @@ Use `git add` to stage the changes. Commit the changes to your working branch: git commit -m "Insert a meaningful summary of changes here." ---- -Finally, you can create a patch and attach it to the Github issue: +Finally, you can create a patch and attach it to the GitHub issue: [source,bash] ---- diff --git a/src/site/content/integration.adoc b/src/site/content/integration.adoc index 14ba8c050b..ef0a226931 100644 --- a/src/site/content/integration.adoc +++ b/src/site/content/integration.adoc @@ -71,7 +71,7 @@ A nifty set of tools and libraries for enhancing productivity with the Apache Wi from https://twitter.com/@timperrett[@timperrett]. + Integration between Shiro and the Lift Web framework. -Uses Lift’s sitemap Locs instead of Shiro’s built in web.xml resource filters to control access to URLs. +Uses Lift’s sitemap Locs instead of Shiro’s built-in web.xml resource filters to control access to URLs. * *https://github.com/alexxiyang/shiro-redis[Redis Cache Manager]* + diff --git a/src/site/content/introduction.adoc b/src/site/content/introduction.adoc index 86b1635229..fee6a65a7f 100644 --- a/src/site/content/introduction.adoc +++ b/src/site/content/introduction.adoc @@ -51,7 +51,7 @@ There are also additional features to support and reinforce these concerns in di * Web Support: Shiro's web support APIs help easily secure web applications. * Caching: Caching is a first-tier citizen in Apache Shiro's API to ensure that security operations remain fast and efficient. -* Concurrency: Apache Shiro supports multi-threaded applications with its concurrency features. +* Concurrency: Apache Shiro supports multithreaded applications with its concurrency features. * Testing: Test support exists to help you write unit and integration tests and ensure your code will be secured as expected. * "Run As": A feature that allows users to assume the identity of another user (if they are allowed), sometimes useful in administrative scenarios. -* "Remember Me": Remember users' identities across sessions so they only need to log in when mandatory. +* "Remember Me": Remember users' identities across sessions, so they only need to log in when mandatory. diff --git a/src/site/content/issues.adoc b/src/site/content/issues.adoc index 860fc2ad5a..a7f0918cd3 100644 --- a/src/site/content/issues.adoc +++ b/src/site/content/issues.adoc @@ -18,8 +18,8 @@ For community advice and help in using Apache Shiro, please visit the link:/supp * You do your due diligence to ensure a suspected error is actually a bug. * You search the issue tracker to ensure what you want to report has not already been reported by someone else. -* If your problem is actually a bug, we would appreciate it if you could attach a simple JUnit test case that allows us to repeat the problem so we can fix it as fast as possible. +* If your problem is actually a bug, we would appreciate it if you could attach a simple JUnit test case that allows us to repeat the problem, so we can fix it as fast as possible. * If a unit test is not available (please really try to make one!), attach a stack trace and Shiro's TRACE or DEBUG log output. -* If you've already fixed the problem, please submit a patch and we'll likely include it in the next release. +* If you've already fixed the problem, please submit a patch, and we'll likely include it in the next release. https://issues.apache.org/jira/browse/SHIRO[Click here to visit the Apache Shiro Jira issue tracker]. diff --git a/src/site/content/jakarta-ee.adoc b/src/site/content/jakarta-ee.adoc index 9bd4c2245f..86072d4508 100644 --- a/src/site/content/jakarta-ee.adoc +++ b/src/site/content/jakarta-ee.adoc @@ -227,7 +227,7 @@ ssl.alwaysEnabled = true ==== Using Enhanced SSL filter with HAProxy or other load balancers When behind SSL-terminating proxy, Shiro may not be able to determine if SSL was used. `X-Forwarded-Proto` header can mitigate this. You can configure your proxy set this header to `https` to tell Shiro -when SSL is used. Below is an haproxy configuration excerpt: +when SSL is used. Below is a haproxy configuration excerpt: [source] ---- .... @@ -237,7 +237,7 @@ frontend tcp-in ---- ==== Using CDI Beans in shiro.ini -Below is an example of using a CDI bean and assign it's property to a variable in shiro.ini +Below is an example of using a CDI bean and assign its property to a variable in shiro.ini [source,java] ---- @Named diff --git a/src/site/content/java-annotations-list.adoc b/src/site/content/java-annotations-list.adoc index 59152e7584..798cb46a81 100644 --- a/src/site/content/java-annotations-list.adoc +++ b/src/site/content/java-annotations-list.adoc @@ -13,6 +13,6 @@ Below are a list of the different Shiro annotations you can use in your applicat * *link:static/current/apidocs/org/apache/shiro/authz/annotation/RequiresPermissions.html[RequiresPermissions]* - Requires the current executor's Subject to imply a particular permission in order to execute the annotated method. If the executor's associated Subject determines that the executor does not imply the specified permission, the method will not be executed. -* *link:static/current/apidocs/org/apache/shiro/authz/annotation/RequiresRoles.html[RequiresRoles]* - Requires the currently executing Subject to have all of the specified roles. If they do not have the role(s), the method will not be executed and an AuthorizationException is thrown. +* *link:static/current/apidocs/org/apache/shiro/authz/annotation/RequiresRoles.html[RequiresRoles]* - Requires the currently executing Subject to have all the specified roles. If they do not have the role(s), the method will not be executed and an AuthorizationException is thrown. * *link:static/current/apidocs/org/apache/shiro/authz/annotation/RequiresUser.html[RequiresUser]* - Requires the current Subject to be an application user for the annotated class/instance/method to be accessed or invoked. \ No newline at end of file diff --git a/src/site/content/java-authentication-guide.adoc b/src/site/content/java-authentication-guide.adoc index a63d792008..52479ce833 100644 --- a/src/site/content/java-authentication-guide.adoc +++ b/src/site/content/java-authentication-guide.adoc @@ -13,7 +13,7 @@ Authentication is the process of identity verification– you are trying to prov To do so, a user needs to provide some sort of proof of identity that your system understands and trust. The goal of this guide is to walk you through how Authentication in Java is performed in Shiro. -If you haven't already please take moment and go through Shiro's link:/10-minute-tutorial.html[10 Minute Tutorial] so that you get a basic understanding of how to work with Shiro. +If you haven't already please take moment and go through Shiro's link:/10-minute-tutorial.html[10-Minute Tutorial] so that you get a basic understanding of how to work with Shiro. [#JavaAuthenticationGuide-Terminologyyoullneed] == Terminology you'll need @@ -29,7 +29,7 @@ Realms:: Security specific DAO, data access object, software component that talk [#JavaAuthenticationGuide-HowtoAuthenticateinJavawithShiro] == How to Authenticate in Java with Shiro -In Shiro's framework, and most every other framework for that matter, the Java authentication process can be broken up into three distinct steps. +In Shiro's framework, and almost every other framework for that matter, the Java authentication process can be broken up into three distinct steps. [#JavaAuthenticationGuide-Steps] @@ -72,7 +72,7 @@ So we’ve collected the information in a token and set it to remember returning Your authentication system is represented in Shiro by security-specific DAOs, that are referred to as link:/static/current/apidocs/[Realms]. For more information on realms please check out the link:/realm.html[Shiro Realm Guide]. -In Shiro we try to make this part as quick and easy as humanly possible. We have it down to one line of Java code! +In Shiro, we try to make this part as quick and easy as humanly possible. We have it down to one line of Java code! [source,java] ---- @@ -104,7 +104,7 @@ If the `login()` method call is successful, then the user is logged in and assoc From here, the user can go about using your application and retain their identity through their session or longer since we have set the "Remember Me" in our example. But what happens if something fails in the authentication attempt? -What if they give you the wrong password or they accessed the system too many times, maybe their account is locked? +What if they give you the wrong password, or they accessed the system too many times, maybe their account is locked? In this case, Shiro will throw an exception. This is where Shiro's rich exception hierarchy comes into play. @@ -123,7 +123,7 @@ try { //No problems, show authenticated view… ---- -You can take that method call and wrap it in a try/catch block and you can catch all sort of exceptions if you want to handle them and react accordingly. In addition to a rich set of exceptions that Shiro offers, you can create your own if you need custom functionality. For more information, follow this link documentation on link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[AuthenticationException]. +You can take that method call and wrap it in a try/catch block, and you can catch all sort of exceptions if you want to handle them and react accordingly. In addition to a rich set of exceptions that Shiro offers, you can create your own if you need custom functionality. For more information, follow this link documentation on link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[AuthenticationException]. [TIP] .Security Tip @@ -162,9 +162,9 @@ For example, a check to see if a subject can access financial information should Here is a scenario to help illustrate why the distinction between isAuthenticated and isRemembered is important. Let's say you're using Amazon.com. -You log in and you add some books to your shopping cart. +You log in, and you add some books to your shopping cart. A day goes by. -Of course your user session has expired and you've been logged out. +Of course your user session has expired, and you've been logged out. But Amazon "remembers" you, greets you by name, and is still giving you personalized book recommendations. To Amazon, `isRemembered()` would return `TRUE`. What happens if you try to use one of the credit cards on file or change your account information? While Amazon "remembers" you, `isRemembered() = TRUE`, it is not certain that you are in fact you, `isAuthenticated()=FALSE`. diff --git a/src/site/content/java-authorization-guide.adoc b/src/site/content/java-authorization-guide.adoc index 8877ad449d..a663eaa1c6 100644 --- a/src/site/content/java-authorization-guide.adoc +++ b/src/site/content/java-authorization-guide.adoc @@ -15,7 +15,7 @@ Authorization has three core elements that we reference quite a bit in Shiro– === Permissions Defined -Permissions are the most atomic level of a security policy and they are statements of functionality. Permissions represent what can be done in your application. A well formed permission describes a resource types and what actions are possible when you interact with those resources. Can you _open_ a _door_? Can you _read_ a _file_? Can you _delete_ a _customer record_? Can you _push_ a _button_? +Permissions are the most atomic level of a security policy, and they are statements of functionality. Permissions represent what can be done in your application. A well-formed permission describes a resource types and what actions are possible when you interact with those resources. Can you _open_ a _door_? Can you _read_ a _file_? Can you _delete_ a _customer record_? Can you _push_ a _button_? Common actions for data-related resources are create, read, update, and delete, commonly referred to as CRUD. @@ -23,7 +23,7 @@ It is important to understand that permissions do not have knowledge of _who_ ca ==== Levels of permission granularity -The permissions above all specify an actions (open, read, delete, etc) on a resource (door, file, customer record, etc). In Shiro, you can define a permission to any depth you like. Here are a few common permission levels in order of granularity. +The permissions above all specify an actions (open, read, delete, etc.) on a resource (door, file, customer record, etc). In Shiro, you can define a permission to any depth you like. Here are a few common permission levels in order of granularity. * Resource Level - This is the broadest and easiest to build. A user can edit customer records or open doors. The resource is specified but not a specific instance of that resource. * Instance Level - The permission specifies the instance of a resource. A user can edit the customer record for IBM or open the kitchen door. @@ -39,13 +39,13 @@ There are two types of roles that you need to be aware of and Shiro will support ==== Implicit Roles -Most people view roles as what we define as an implicit role where your application _implies_ a set of permissions because a user has a particular role as opposed to the role explicitly being assigned permissions or your application checking for those permissions. Role checks in code are generally a reflection of an implicit role. You can view patient data because you have the _administrator_ role. You can create an account because you have the _bank teller_ role. The fact that these names exist does not have a correlation to what the software can actually do. Most people use roles in this manner. It is easiest but it can create a lot of maintenance and management problems for all but the simplest application. +Most people view roles as what we define as an implicit role where your application _implies_ a set of permissions because a user has a particular role as opposed to the role explicitly being assigned permissions or your application checking for those permissions. Role checks in code are generally a reflection of an implicit role. You can view patient data because you have the _administrator_ role. You can create an account because you have the _bank teller_ role. The fact that these names exist does not have a correlation to what the software can actually do. Most people use roles in this manner. It is easiest, but it can create a lot of maintenance and management problems for all but the simplest application. ==== Explicit Roles -An explicit role has permissions _explicitly_ assigned to it and therefore is an _explicit_ collection of permissions. Permission checks in code are a reflection of an explicit role. You can view patient data because because you have the _view patient data_ permission as part of your _administrator_ role. You can create an account because you have the _create account_ permission as part of your _bank teller_ role. You can perform these actions, not because of some implicit role name based on a string but because the corresponding permission was explicitly assigned to your role. +An explicit role has permissions _explicitly_ assigned to it and therefore is an _explicit_ collection of permissions. Permission checks in code are a reflection of an explicit role. You can view patient data because you have the _view patient data_ permission as part of your _administrator_ role. You can create an account because you have the _create account_ permission as part of your _bank teller_ role. You can perform these actions, not because of some implicit role name based on a string but because the corresponding permission was explicitly assigned to your role. -The big benefits of explicit roles are easier manageability and lower maintenance of your application. If you ever need to add, remove, or change a role, you can do so without touching your source code. And in Shiro, you'll also be able to dynamically add, remove, or change roles at runtime and your authorization checks will always have up to date values. This means you won't have to force users to log out and log back in order to get their new permissions. +The big benefits of explicit roles are easier manageability and lower maintenance of your application. If you ever need to add, remove, or change a role, you can do so without touching your source code. And in Shiro, you'll also be able to dynamically add, remove, or change roles at runtime and your authorization checks will always have up-to-date values. This means you won't have to force users to log out and log back in order to get their new permissions. === Users Defined @@ -58,7 +58,7 @@ For more information on Users, aka Subjects, please check out the link:subject.h [NOTE] ==== .Note -Ultimately, your link:realm.html[Realm] implementation is what communicates with your data source (RDBMS, LDAP, etc). So your realm is what will tell Shiro whether or not roles or permissions exist. You have full control over how your authorization model works. +Ultimately, your link:realm.html[Realm] implementation is what communicates with your data source (RDBMS, LDAP, etc). So your realm is what will tell Shiro whether roles or permissions exist. You have full control over how your authorization model works. ==== == How to perform Authorization in Java with Shiro @@ -77,7 +77,7 @@ Checking for permissions and roles, programmatically in your Java code is the tr This is an example of how you do a role check programmatically in your application. We want to check if a user has the _administrator_ role and if they do, then we'll show a special button, otherwise we won't show it.SubjectAwareExecutor.html#execute(java.lang.Runnable) -First we get access to the current user, the link:subject.html[Subject]. Then we pass the _adminstrator_ to the Subject's link:static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)[`.hasRole()`] method. It will return `TRUE` or `FALSE`. +First we get access to the current user, the link:subject.html[Subject]. Then we pass the _administrator_ to the Subject's link:static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)[`.hasRole()`] method. It will return `TRUE` or `FALSE`. [source,java] ---- @@ -92,7 +92,7 @@ if (currentUser.hasRole("administrator")) { ---- -Now a role based check is quick and easy to implement but it has a major drawback. It is implicit. +Now a role based check is quick and easy to implement, but it has a major drawback. It is implicit. What if you just want to add, remove, or redefine a role later? You'll have to crack open your source code and change all your role checks to reflect the change in your security model. You'll have to shut down the application, crack open the code, test it, and then restart it everytime. @@ -136,7 +136,7 @@ if(currentUser.isPermitted(perm)){ You can construct the permission string the way you want so long as your link:realm.html[Realm] knows how to work with it. In this example we use Shiro's optional permission syntax, link:permissions.html[WildCardPermissions]. WildCardPermissions are powerful and intuitive. If you'd like to learn more about them then check out the link:static/current/apidocs/org/apache/shiro/authz/Permission.html[Permissions Documentation]. -With string-based permission checks, you get the same functionality as the example before. The benefit is that you are not forced to implement a permission interface and you can construct the permission via a simple string. The downside is that you don't have type safety and if you needed more complicated permission capabilities that are outside the scope of what this represents, you're going to want to implement your own permission objects based on the permission interface. +With string-based permission checks, you get the same functionality as the example before. The benefit is that you are not forced to implement a permission interface, and you can construct the permission via a simple string. The downside is that you don't have type safety and if you needed more complicated permission capabilities that are outside the scope of what this represents, you're going to want to implement your own permission objects based on the permission interface. === Annotation Authorization @@ -190,7 +190,7 @@ For JSP/GSP based web applications, Shiro also offers a link:jsp-tag-library.htm In this example, we're going to show users with the _users:manage_ permission a link to the Manage Users page. If they do not have the permission, then we'll show them a nice message. -First, we'll need to add the Shiro taglib to our web application. Next, we add the `<shiro:hasPermission>` tag with a check for _users:manage_. Within the `<shiro:hasPermission>` tags we will place the code we want to execute if the user has the permission we're checking for. If we want to take an action if the user lacks the permission, then we need to also add the `<shiro:lacksPermission>` tag, again checking for _users:manage_. And any code we want to excute if the user lacks the permission will need to be placed within the `<shiro:lacksPermission>` tags. +First, we'll need to add the Shiro taglib to our web application. Next, we add the `<shiro:hasPermission>` tag with a check for _users:manage_. Within the `<shiro:hasPermission>` tags we will place the code we want to execute if the user has the permission we're checking for. If we want to take an action if the user lacks the permission, then we need to also add the `<shiro:lacksPermission>` tag, again checking for _users:manage_. And any code we want to execute if the user lacks the permission will need to be placed within the `<shiro:lacksPermission>` tags. [source,html] ---- diff --git a/src/site/content/java-cryptography-guide.adoc b/src/site/content/java-cryptography-guide.adoc index 236be380cb..bfb8976d90 100644 --- a/src/site/content/java-cryptography-guide.adoc +++ b/src/site/content/java-cryptography-guide.adoc @@ -12,8 +12,8 @@ Cryptography is the protecting of information from undesired access by hiding it Shiro is a major part of Shiro because we wanted to provide you with simplicity on what is typically a very complex topic. For example, the Java Cryptography Extension (JCE) already handles cryptography in a Java environment but is very difficult to learn and use. So we grabbed the concepts made available by the JCE API and make them available to us mortals. -In addition, all of the calls in the JCE are procedural which doesn't fit in Java's Object Oriented paradigm. -So in Shiro, our cryptography features are all object oriented. +In addition, all the calls in the JCE are procedural which doesn't fit in Java's Object-Oriented paradigm. +So in Shiro, our cryptography features are all object-oriented. == Elements of Cryptography @@ -21,7 +21,7 @@ cryptography has two core elements in Shiro– ciphers and hashes. === Ciphers Defined -Ciphers are algorightms that can either encrypt or decrypt based on public or private key pair. And there are two different types of ciphers: +Ciphers are algorithms that can either encrypt or decrypt based on public or private key pair. And there are two different types of ciphers: * Symmetric Cipher - encrypts and decrypts using the same key. @@ -35,7 +35,7 @@ A hash is a one-way irreversible conversion of an input source. In the JDK, a ha ==== Common uses for Hashes -Hashes are often used to transforms credentials like passwords or biometric data. It's a one way transformation so you can never see what the original value was. This is a very safe way of storing passwords so that no one other than the user will ever know a password, even if your system is compromised. +Hashes are often used to transforms credentials like passwords or biometric data. It's a one way transformation, so you can never see what the original value was. This is a very safe way of storing passwords so that no one other than the user will ever know a password, even if your system is compromised. In addition, Shiro's hashes can be used with any type of data with an underlying byte array. Examples of this data include files, streams, byte arrays, strings, and character arrays. diff --git a/src/site/content/jaxrs.adoc b/src/site/content/jaxrs.adoc index 5a0736bb9e..e6390e3ae1 100644 --- a/src/site/content/jaxrs.adoc +++ b/src/site/content/jaxrs.adoc @@ -41,9 +41,9 @@ Just like any other web application, your resources paths can be defined in a `s See the link:web.html[web documentation] for more details. -The other, probably more popular, option is to use Shiro's link:java-annotations-list.html[annotations] along side other JAX-RS annotations on your resources. However you *MUST* still define at least one path in your `shiro.ini` file. +The other, probably more popular, option is to use Shiro's link:java-annotations-list.html[annotations] alongside other JAX-RS annotations on your resources. However, you *MUST* still define at least one path in your `shiro.ini` file. -The below code block will allow for basic authentication but NOT require it (via the `permissive` flag). This way all of the resources under `/api` can optional require authentication and authorization based on annotations. +The below code block will allow for basic authentication but NOT require it (via the `permissive` flag). This way all the resources under `/api` can optional require authentication and authorization based on annotations. [source,ini] ---- @@ -95,7 +95,7 @@ public class HelloShiro { } ---- -This resource has two end points, the first allows access by any logged in user, the second any user with the link:permissions.html[permission] `hello:define`. +This resource has two end points, the first allows access by any logged-in user, the second any user with the link:permissions.html[permission] `hello:define`. The corresponding JAX-RS Application class: @@ -129,4 +129,4 @@ In the above example, requests to either `/api/shiro` or `/api/shiro/define` wil == Want to see more? -You can find portable JAX-RS application that runs with https://jersey.java.net/[Jersey], https://resteasy.dev/[RestEasy] or https://cxf.apache.org[Apache CXF] in the https://github.com/apache/shiro/tree/main/samples[samples] directory on Github. +You can find portable JAX-RS application that runs with https://jersey.java.net/[Jersey], https://resteasy.dev/[RestEasy] or https://cxf.apache.org[Apache CXF] in the https://github.com/apache/shiro/tree/main/samples[samples] directory on GitHub. diff --git a/src/site/content/jsp-tag-library.adoc b/src/site/content/jsp-tag-library.adoc index 2fe0b93046..af04d65ff0 100644 --- a/src/site/content/jsp-tag-library.adoc +++ b/src/site/content/jsp-tag-library.adoc @@ -20,7 +20,7 @@ It is logically opposite to the 'guest' tag. Displays the user's principal or a property of the user's principal. * ** + -Displays body content only if the current Subject (user) 'has' (implies) the specified permission (i.e the user has the specified ability). +Displays body content only if the current Subject (user) 'has' (implies) the specified permission (i.e. the user has the specified ability). * ** + Displays body content only if the current Subject (user) does NOT have (not imply) the specified permission (i.e. the user lacks the specified ability). @@ -40,5 +40,5 @@ It is more restrictive than the 'user' tag. It is logically opposite to the 'notAuthenticated' tag. * ** + -Displays body content only if the current user has NOT succesfully authenticated _during their current session_. +Displays body content only if the current user has NOT successfully authenticated _during their current session_. It is logically opposite to the 'authenticated' tag. diff --git a/src/site/content/overview.adoc b/src/site/content/overview.adoc index 3ba83bbbaf..2b23cd8d6d 100644 --- a/src/site/content/overview.adoc +++ b/src/site/content/overview.adoc @@ -47,10 +47,10 @@ There are also additional features to support and reinforce these concerns in di * Web Support: Shiro's web support APIs help easily secure web applications. * Caching: Caching is a first-tier citizen in Apache Shiro's API to ensure that security operations remain fast and efficient. -* Concurrency: Apache Shiro supports multi-threaded applications with its concurrency features. +* Concurrency: Apache Shiro supports multithreaded applications with its concurrency features. * Testing: Test support exists to help you write unit and integration tests and ensure your code will be secured as expected. * "Run As": A feature that allows users to assume the identity of another user (if they are allowed), sometimes useful in administrative scenarios. -* "Remember Me": Remember users' identities across sessions so they only need to log in when mandatory. +* "Remember Me": Remember users' identities across sessions, so they only need to log in when mandatory. == A First Look at Apache Shiro @@ -62,7 +62,7 @@ This example statement indicates that applications are largely written to satisf Shiro largely reflects these concepts in its own design. By matching what is already intuitive for software developers, Apache Shiro remains intuitive and easy to use in practically any application. -=== Bsic Design +=== Basic Design Shiro's architecture has 3 primary concepts: the `Subject`, `SecurityManager` and `Realm` s. The following diagram is a high-level overview of how these concepts interact, and we'll cover each concept below: @@ -70,7 +70,7 @@ image::images/ShiroArchitecture.png["Apache Shiro Architecture",align="center"] ==== Subject -The `Subject` is essentially a security specific 'view' of the the currently executing user. Notice that it is not actually named _User_ however. The name _Subject_ was chosen for two reasons: +The `Subject` is essentially a security specific 'view' of the currently executing user. Notice that it is not actually named _User_, however. The name _Subject_ was chosen for two reasons: . The word 'User' often implies a human being in many software systems. But sometimes the 'currently executing user' isn't a human being at all - maybe it is a 3rd-party process or remote server or daemon account. The word 'Subject' is more general and can mean 'the entity interacting with the software'. . The word 'Subject', because it is a general-purpose concept, is the actual term most often used in the security world. We retain that definition to be consistent. @@ -103,6 +103,6 @@ The third and final core concept in Shiro is that of a Realm. A Realm acts as th In this sense a Realm is essentially a security-specific https://en.wikipedia.org/wiki/Data_access_object[DAO]: it encapsulates connection details for data sources and makes the associated data available to Shiro as needed. When configuring Shiro, you must specify at least one Realm to use for authentication and/or authorization. More than one Realm may be configured, but at least one is required. -Shiro provides out-of-the-box Realms to connect to a number of security data sources (aka directories) such as LDAP, relational databases (JDBC), text configuration sources like INI and properties files, and more. You can plug-in your own Realm implementations to represent custom data sources if the default Realms do not meet your needs. +Shiro provides out-of-the-box Realms to connect to a number of security data sources (aka directories) such as LDAP, relational databases (JDBC), text configuration sources like INI and properties files, and more. You can plug in your own Realm implementations to represent custom data sources if the default Realms do not meet your needs. Like other internal components, the Shiro `SecurityManager` manages how Realms are used to acquire security data and then represented as `Subject` instances. diff --git a/src/site/content/permissions.adoc b/src/site/content/permissions.adoc index 80e208a7ef..1e6aec38a6 100644 --- a/src/site/content/permissions.adoc +++ b/src/site/content/permissions.adoc @@ -26,7 +26,7 @@ There are many variations for how permissions could be granted to users - the ap [#wildcard_permissions] == Wildcard Permissions -The above examples of permissions, "Open a file", "View the 'user/list' web page", etc are all valid permission statements.However, it would be very difficult computationally to interpret those natural language strings and determine if a user is allowed to perform that behavior or not. +The above examples of permissions, "Open a file", "View the 'user/list' web page", etc. are all valid permission statements.However, it would be very difficult computationally to interpret those natural language strings and determine if a user is allowed to perform that behavior or not. So to enable easy-to-process yet still readable permission statements, Shiro provides powerful and intuitive permission syntax we refer to as the WildcardPermission. @@ -221,7 +221,7 @@ printer:*:lp7200 While permission assignments use the wildcard construct quite a bit ("printer:print:*" = print to any printer) for convenience and scalability, permission *checks* at runtime should _always_ be based on the most specific permission string possible. -For example, if the user had a UI and they wanted to print a document to the `lp7200` printer, you *should* check if the user is permitted to do so by executing this code: +For example, if the user had a UI, and they wanted to print a document to the `lp7200` printer, you *should* check if the user is permitted to do so by executing this code: [source,java] ---- @@ -253,7 +253,7 @@ Why is it that runtime permission checks should be as specific as possible, but That is, if a user is assigned the `user:*` permission, this _implies_ that the user can perform the `user:view` action. The string "user:*" is clearly not equal to "user:view", but the former implies the latter. "user:*" describes a superset of functionality of that defined by "user:view". -To support implication rules, all permissions are translated in to object instances that implement the `org.apache.shiro.authz.Permission` interface. This is so that implication logic can be executed at runtime and that implication logic is often more complex than a simple string equality check. All of the wildcard behavior described in this document is actually made possible by the `org.apache.shiro.authz.permission.WildcardPermission` class implementation. Here are some more wildcard permission strings that show access by implication: +To support implication rules, all permissions are translated in to object instances that implement the `org.apache.shiro.authz.Permission` interface. This is so that implication logic can be executed at runtime and that implication logic is often more complex than a simple string equality check. All the wildcard behavior described in this document is actually made possible by the `org.apache.shiro.authz.permission.WildcardPermission` class implementation. Here are some more wildcard permission strings that show access by implication: [source,ini] ---- @@ -303,4 +303,4 @@ Shiro's default behavior for Realm implementations is that, for every permission This is usually extremely fast when users, roles and permissions are cached in memory when using a proper link:cachemanager.html[CacheManager], which Shiro does support for Realm implementations. Just know that with this default behavior, as the number of permissions assigned to a user or their roles or groups increase, the time to perform the check will necessarily increase. -If a Realm implementor has a more efficient way of checking permissions and performing this implication logic, especially if based on the applicaton's data model, they should implement that as part of their Realm isPermitted* method implementations. The default Realm/WildcardPermission support exists to cover 80-90% of most use cases, but it might not be the best solution for applications that have massive amounts of permissions to store and/or check at runtime. +If a Realm implementor has a more efficient way of checking permissions and performing this implication logic, especially if based on the application's data model, they should implement that as part of their Realm isPermitted* method implementations. The default Realm/WildcardPermission support exists to cover 80-90% of most use cases, but it might not be the best solution for applications that have massive amounts of permissions to store and/or check at runtime. diff --git a/src/site/content/privacy-policy.adoc b/src/site/content/privacy-policy.adoc index 2ef220119a..72d0f9785f 100644 --- a/src/site/content/privacy-policy.adoc +++ b/src/site/content/privacy-policy.adoc @@ -60,7 +60,7 @@ It can only be accessed by members of the Apache Privacy committee. The data can be viewed by anyone by visiting https://matomo.privacy.apache.org/. Matomo respects any Do Not Track setting in your browser. -You can also opt-out from all Matomo tracking below. +You can also opt out from all Matomo tracking below. ++++