Fix some typos and grammer
diff --git a/src/site/content/10-minute-tutorial.adoc b/src/site/content/10-minute-tutorial.adoc
index e9976a2..dcdabc9 100644
--- a/src/site/content/10-minute-tutorial.adoc
+++ b/src/site/content/10-minute-tutorial.adoc
@@ -9,7 +9,7 @@
== 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 @@
[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 @@
== 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 @@
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 @@
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 721e8cd..9642177 100644
--- a/src/site/content/architecture.adoc
+++ b/src/site/content/architecture.adoc
@@ -19,7 +19,7 @@
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 @@
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 `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 88ebd93..217c046 100644
--- a/src/site/content/articles.adoc
+++ b/src/site/content/articles.adoc
@@ -60,4 +60,4 @@
* *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 efa37ec..69fc1eb 100644
--- a/src/site/content/authentication.adoc
+++ b/src/site/content/authentication.adoc
@@ -160,12 +160,12 @@
[#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 @@
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 @@
. 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 @@
|`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 @@
.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 2a5591b..b0f2f3f 100644
--- a/src/site/content/authorization-features.adoc
+++ b/src/site/content/authorization-features.adoc
@@ -11,7 +11,7 @@
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 @@
* *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 3842c8e..9a6df0c 100644
--- a/src/site/content/authorization.adoc
+++ b/src/site/content/authorization.adoc
@@ -52,7 +52,7 @@
[#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 @@
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 @@
====
.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 @@
|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 @@
|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 @@
|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 @@
|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 @@
.. 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 @@
[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 @@
====
.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 70d1b67..42761f2 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 @@
: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 d0fad2b..8d29575 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 @@
: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 7d51b79..5841b27 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 fbe6874..0aac1ef 100644
--- a/src/site/content/cachemanager.adoc
+++ b/src/site/content/cachemanager.adoc
@@ -34,9 +34,9 @@
----
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 ca96ee2..63094a8 100644
--- a/src/site/content/caching.adoc
+++ b/src/site/content/caching.adoc
@@ -101,7 +101,7 @@
== 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 2233bd0..570eb8e 100644
--- a/src/site/content/cas.adoc
+++ b/src/site/content/cas.adoc
@@ -22,7 +22,7 @@
== 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 cf0289f..064547f 100644
--- a/src/site/content/configuration.adoc
+++ b/src/site/content/configuration.adoc
@@ -72,7 +72,7 @@
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 @@
[#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 @@
...
----
-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 @@
[#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 @@
[#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 @@
[#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 6e89441..d28a7ea 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 @@
[#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 848d286..6b0de61 100644
--- a/src/site/content/features.adoc
+++ b/src/site/content/features.adoc
@@ -34,4 +34,4 @@
== 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 6581a5e..a207a02 100644
--- a/src/site/content/forums.adoc
+++ b/src/site/content/forums.adoc
@@ -13,7 +13,7 @@
____
-*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 3d207e2..2d2bc93 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 @@
/** = 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 dac8b10..f520e82 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 @@
=== 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 @@
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 14ba8c0..ef0a226 100644
--- a/src/site/content/integration.adoc
+++ b/src/site/content/integration.adoc
@@ -71,7 +71,7 @@
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 86b1635..fee6a65 100644
--- a/src/site/content/introduction.adoc
+++ b/src/site/content/introduction.adoc
@@ -51,7 +51,7 @@
* 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 860fc2a..a7f0918 100644
--- a/src/site/content/issues.adoc
+++ b/src/site/content/issues.adoc
@@ -18,8 +18,8 @@
* 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 9bd4c22..86072d4 100644
--- a/src/site/content/jakarta-ee.adoc
+++ b/src/site/content/jakarta-ee.adoc
@@ -227,7 +227,7 @@
==== 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 @@
----
==== 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 59152e7..798cb46 100644
--- a/src/site/content/java-annotations-list.adoc
+++ b/src/site/content/java-annotations-list.adoc
@@ -13,6 +13,6 @@
* *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 a63d792..52479ce 100644
--- a/src/site/content/java-authentication-guide.adoc
+++ b/src/site/content/java-authentication-guide.adoc
@@ -13,7 +13,7 @@
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 @@
[#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 @@
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 @@
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 @@
//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 @@
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 8877ad4..a663eaa 100644
--- a/src/site/content/java-authorization-guide.adoc
+++ b/src/site/content/java-authorization-guide.adoc
@@ -15,7 +15,7 @@
=== 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 @@
==== 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 @@
==== 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 @@
[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 @@
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 @@
----
-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 @@
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 @@
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 236be38..bfb8976 100644
--- a/src/site/content/java-cryptography-guide.adoc
+++ b/src/site/content/java-cryptography-guide.adoc
@@ -12,8 +12,8 @@
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 @@
=== 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 @@
==== 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 5a0736b..e6390e3 100644
--- a/src/site/content/jaxrs.adoc
+++ b/src/site/content/jaxrs.adoc
@@ -41,9 +41,9 @@
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 @@
}
----
-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 @@
== 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 2fe0b93..af04d65 100644
--- a/src/site/content/jsp-tag-library.adoc
+++ b/src/site/content/jsp-tag-library.adoc
@@ -20,7 +20,7 @@
Displays the user's principal or a property of the user's principal.
* *<shiro:hasPermission/>* +
-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).
* *<shiro:lacksPermission/>* +
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 logically opposite to the 'notAuthenticated' tag.
* *<shiro:notAuthenticated/>* +
-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 3ba83bb..2b23cd8 100644
--- a/src/site/content/overview.adoc
+++ b/src/site/content/overview.adoc
@@ -47,10 +47,10 @@
* 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 @@
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 @@
==== 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 @@
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 80e208a..1e6aec3 100644
--- a/src/site/content/permissions.adoc
+++ b/src/site/content/permissions.adoc
@@ -26,7 +26,7 @@
[#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 @@
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 @@
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 @@
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 2ef2201..72d0f97 100644
--- a/src/site/content/privacy-policy.adoc
+++ b/src/site/content/privacy-policy.adoc
@@ -60,7 +60,7 @@
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.
++++
<iframe
diff --git a/src/site/content/realm.adoc b/src/site/content/realm.adoc
index 0a8d261..627bd4c 100644
--- a/src/site/content/realm.adoc
+++ b/src/site/content/realm.adoc
@@ -95,7 +95,7 @@
As mentioned in the link:/authentication.html#Authentication-AuthenticationSequence[authentication sequence], just before a `Realm` is consulted to perform an authentication attempt, its link:static/current/apidocs/org/apache/shiro/realm/Realm.html#supports(org.apache.shiro.authc.AuthenticationToken)[`supports`] method is called.
If the return value is `true`, only then will its `getAuthenticationInfo(token)` method be invoked.
-Typically a realm will check the type (interface or class) of the submitted token to see if it can process it.
+Typically, a realm will check the type (interface or class) of the submitted token to see if it can process it.
For example, a Realm that processes biometric data may not understand `UsernamePasswordTokens` at all, in which case it would return `false` from the `supports` method.
[#Realm-Handling-supported-AuthenticationTokens]
@@ -121,7 +121,7 @@
====
Implementing
link:/static/current/apidocs/org/apache/shiro/realm/Realm.html[Realm]
-interface directly might be time consuming and error prone.
+interface directly might be time-consuming and error-prone.
Most people choose to subclass the
link:/static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html[AuthorizingRealm]
abstract class instead of starting from scratch.
@@ -292,12 +292,12 @@
. `Subject` delegates the task to grant or deny Permission to SecurityManager
. `SecurityManager` then delegates to Authorizer
-. Authorizer then referrers to all of the Authorizer Realms one by one until it Permission is granted If Permission is not granted by any of the Authorizing Realm, Subject is denied Permission
+. Authorizer then referrers to all the Authorizer Realms one by one until it Permission is granted If Permission is not granted by any of the Authorizing Realm, Subject is denied Permission
. Authorizing Realm does the following in order to check if a Subject is permitted:
a. First it gets identify all Permissions assigned to Subject directly by calling getObjectPermissions() and getStringPermissions methods on link:/static/current/apidocs/org/apache/shiro/authz/AuthorizationInfo.html[AuthorizationInfo] and aggregating the results.
-b. If a link:/static/current/apidocs/org/apache/shiro/authz/permission/RolePermissionResolver.html[RolePermissionResolver] is registered, it is used to retrieve Permissions based on all of the roles assigned to Subject by calling the `RolePermissionResolver.resolvePermissionsInRole()`
+b. If a link:/static/current/apidocs/org/apache/shiro/authz/permission/RolePermissionResolver.html[RolePermissionResolver] is registered, it is used to retrieve Permissions based on all the roles assigned to Subject by calling the `RolePermissionResolver.resolvePermissionsInRole()`
c. For aggregated Permissions from a. and b. the implies() method is called to check if any of these permission are implied the checked permission.
See link:/permissions.html#wildcard_permissions[WildcardPermission]
diff --git a/src/site/content/roadmap.adoc b/src/site/content/roadmap.adoc
index 9dec0ac..6db1a63 100644
--- a/src/site/content/roadmap.adoc
+++ b/src/site/content/roadmap.adoc
@@ -14,7 +14,7 @@
[IMPORTANT]
====
-This list is not exhausive.
+This list is not exhaustive.
The wiki page should be regarded as the primary source.
Feel free to tell us about your ideas on the link:mailing-lists.html[mailing lists]!
====
diff --git a/src/site/content/security-reports.adoc b/src/site/content/security-reports.adoc
index 7cb946c..640e6e5 100644
--- a/src/site/content/security-reports.adoc
+++ b/src/site/content/security-reports.adoc
@@ -63,7 +63,7 @@
Apache Shiro before 1.7.0, when using Apache Shiro with Spring, a specially crafted HTTP request may cause an authentication bypass.
-If you are NOT using Shiro's Spring Boot Starter (`shiro-spring-boot-web-starter`), you must configure add the link:/spring-framework.html#web_applications[`ShiroRequestMappingConfig` auto configuration to your application] or configure the https://github.com/apache/shiro/blob/shiro-root-1.7.0/support/spring/src/main/java/org/apache/shiro/spring/web/config/ShiroRequestMappingConfig.java#L28-L30[equivalent manually].
+If you are NOT using Shiro's Spring Boot Starter (`shiro-spring-boot-web-starter`), you must configure add the link:/spring-framework.html#web_applications[`ShiroRequestMappingConfig` autoconfiguration to your application] or configure the https://github.com/apache/shiro/blob/shiro-root-1.7.0/support/spring/src/main/java/org/apache/shiro/spring/web/config/ShiroRequestMappingConfig.java#L28-L30[equivalent manually].
=== https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-13933[CVE-2020-13933]
diff --git a/src/site/content/securitymanager.adoc b/src/site/content/securitymanager.adoc
index eded85c..c8133b6 100644
--- a/src/site/content/securitymanager.adoc
+++ b/src/site/content/securitymanager.adoc
@@ -80,4 +80,4 @@
[#SecurityManager-TextConfiguration]
=== Text Configuration
-Shiro provides a simple INI-based link:configuration.html[configuration] that can be used out of the box, but any other JavaBeans-compatible mechanism can be used as well. For example, Shiro has excellent link:spring.html[Spring support] too. Other similar frameworks (Guice, JBoss, etc) could also be used.
+Shiro provides a simple INI-based link:configuration.html[configuration] that can be used out of the box, but any other JavaBeans-compatible mechanism can be used as well. For example, Shiro has excellent link:spring.html[Spring support] too. Other similar frameworks (Guice, JBoss, etc.) could also be used.
diff --git a/src/site/content/session-management-features.adoc b/src/site/content/session-management-features.adoc
index a543bcf..72a70d1 100644
--- a/src/site/content/session-management-features.adoc
+++ b/src/site/content/session-management-features.adoc
@@ -16,7 +16,7 @@
Because Shiro's Session objects are POJO-based, session data can be easily stored in any number of data sources. This allows you to customize exactly where your application's session data resides - for example, the file system, an enterprise cache, a relational database, or proprietary data store.
* *Easy and Powerful Clustering* +
-Shiro's sessions can be easily clustered using any of the readily-available networked caching products, like Ehcache, Coherence, GigaSpaces, et. al.
+Shiro's sessions can be easily clustered using any of the readily-available networked caching products, like Ehcache, Coherence, GigaSpaces, et al.
This means you can configure session clustering for Shiro once and only once, and no matter what web container you deploy to, your sessions will be clustered the same way. No need for container-specific configuration!
* *Heterogeneous Client Access* +
@@ -32,7 +32,7 @@
Sessions expire due to inactivity as expected, but they can be prolonged via a `touch()` method to keep them 'alive' if desired. This is useful in Rich Internet Application (RIA) environments where the user might be using a desktop application, but may not be regularly communicating with the server, but the server session should not expire.
* *Transparent web use* +
-Shiro's web support implements the `HttpSession` interface and all of it's associated APIs. This means you can use Shiro sessions in existing web applications and you don't need to change any of your existing web code.
+Shiro's web support implements the `HttpSession` interface and all of it's associated APIs. This means you can use Shiro sessions in existing web applications, and you don't need to change any of your existing web code.
* *Can be used for SSO* +
Because Shiro’s sessions are POJO based, they are easily stored in any data source, and they can be 'shared' across applications if needed. This can be used to provide a simple sign-on experience since the shared session can retain authentication state.
diff --git a/src/site/content/session-management.adoc b/src/site/content/session-management.adoc
index 155dfbe..6fa72c1 100644
--- a/src/site/content/session-management.adoc
+++ b/src/site/content/session-management.adoc
@@ -8,7 +8,7 @@
:icons: font
:toc:
-Apache Shiro offers something unique in the world of security frameworks: a complete enterprise-grade Session solution for any application, from the simplest command-line and smart phone applications to the largest clustered enterprise web applications.
+Apache Shiro offers something unique in the world of security frameworks: a complete enterprise-grade Session solution for any application, from the simplest command-line and smartphone applications to the largest clustered enterprise web applications.
This has large implications for many applications - until Shiro, if you required session support, you were required to deploy your application in a web container or use EJB Stateful Session Beans. Shiro's Session support is much simpler to use and manage than either of these two mechanisms, and it is available in any application, regardless of container.
@@ -20,7 +20,7 @@
* *Easy Custom Session Storage* - Because Shiro's Session objects are POJO-based, session data can be easily stored in any number of data sources. This allows you to customize exactly where your application's session data resides - for example, the file system, in memory, in a networked distributed cache, a relational database, or proprietary data store.
-* *Container-Independent Clustering!* - Shiro's sessions can be easily clustered using any of the readily-available networked caching products, like Ehcache + Terracotta, Coherence, GigaSpaces, et. al. This means you can configure session clustering for Shiro once and only once, and no matter what container you deploy to, your sessions will be clustered the same way. No need for container-specific configuration!
+* *Container-Independent Clustering!* - Shiro's sessions can be easily clustered using any of the readily-available networked caching products, like Ehcache + Terracotta, Coherence, GigaSpaces, et al. This means you can configure session clustering for Shiro once and only once, and no matter what container you deploy to, your sessions will be clustered the same way. No need for container-specific configuration!
* *Heterogeneous Client Access* - Unlike EJB or Web sessions, Shiro sessions can be 'shared' across various client technologies. For example, a desktop application could 'see' and 'share' the same physical session used by the same user in a web application. We are unaware of any framework other than Shiro that can support this.
@@ -30,9 +30,9 @@
* *Inactivity/Expiration Support* – Sessions expire due to inactivity as expected, but they can be prolonged via a `touch()` method to keep them 'alive' if desired. This is useful in Rich Internet Application (RIA) environments where the user might be using a desktop application, but may not be regularly communicating with the server, but the server session should not expire.
-* *Transparent Web Use* - Shiro's web support fully implements and supports the Servlet 2.5 specification for Sessions (`HttpSession` interface and all of it's associated APIs). This means you can use Shiro sessions in existing web applications and you don't need to change any of your existing web code.
+* *Transparent Web Use* - Shiro's web support fully implements and supports the Servlet 2.5 specification for Sessions (`HttpSession` interface and all of it's associated APIs). This means you can use Shiro sessions in existing web applications, and you don't need to change any of your existing web code.
-* *Can be used for SSO* - Because Shiro session's are POJO based, they are easily stored in any data source, and they can be 'shared' across applications if needed. We call this 'poor man's SSO', and it can be used to provide a simple sign-on experience since the shared session can retain authentication state.
+* *Can be used for SSO* - Because Shiro sessions are POJO based, they are easily stored in any data source, and they can be 'shared' across applications if needed. We call this 'poor man's SSO', and it can be used to provide a simple sign-on experience since the shared session can retain authentication state.
[#SessionManagement-UsingSessions]
== Using Sessions
@@ -71,7 +71,7 @@
The SessionManager, as its name might imply, manages Sessions for _all_ subjects in an application - creation, deletion, inactivity and validation, etc. Like other core architectural components in Shiro, the `SessionManager` is a top-level component maintained by the `SecurityManager`.
-The default `SecurityManager` implementation defaults to using a link:static/current/apidocs/org/apache/shiro/mgt/DefaultSecurityManager.html[`DefaultSessionManager`] out of the box. The `DefaultSessionManager` implementation provides all of the enterprise-grade session management features needed for an application, like Session validation, orphan cleanup, etc. This can be used in any application.
+The default `SecurityManager` implementation defaults to using a link:static/current/apidocs/org/apache/shiro/mgt/DefaultSecurityManager.html[`DefaultSessionManager`] out of the box. The `DefaultSessionManager` implementation provides all the enterprise-grade session management features needed for an application, like Session validation, orphan cleanup, etc. This can be used in any application.
[NOTE]
====
@@ -96,7 +96,7 @@
[#SessionManagement-SessionManager-SessionTimeout]
=== Session Timeout
-By default, Shiro's `SessionManager` implementations default to a 30 minute session timeout. That is, if any `Session` created remains idle (unused, where its link:static/current/apidocs/org/apache/shiro/session/Session.html#getLastAccessTime()[`lastAccessedTime`] isn't updated) for 30 minutes or more, the `Session` is considered expired and will not be allowed to be used anymore.
+By default, Shiro's `SessionManager` implementations default to a 30-minute session timeout. That is, if any `Session` created remains idle (unused, where its link:static/current/apidocs/org/apache/shiro/session/Session.html#getLastAccessTime()[`lastAccessedTime`] isn't updated) for 30 minutes or more, the `Session` is considered expired and will not be allowed to be used anymore.
You can set the default `SessionManager` implementation's `globalSessionTimeout` property to define the default timeout value for all sessions. For example, if you wanted the timeout to be an hour instead of 30 minutes:
@@ -143,7 +143,7 @@
[#SessionManagement-SessionManager-Storage]
=== Session Storage
-Whenever a session is created or updated, its data needs to persisted to a storage location so it is accessible by the application at a later time. Similarly, when a session is invalid and longer being used, it needs to be deleted from storage so the session data store space is not exhausted. The `SessionManager` implementations delegate these Create/Read/Update/Delete (CRUD) operations to an internal component, the link:static/current/apidocs/org/apache/shiro/session/mgt/eis/SessionDAO.html[`SessionDAO`], which reflects the https://en.wikipedia.org/wiki/Data_access_object[Data Access Object (DAO)] design pattern.
+Whenever a session is created or updated, its data needs to persisted to a storage location, so it is accessible by the application at a later time. Similarly, when a session is invalid and longer being used, it needs to be deleted from storage so the session data store space is not exhausted. The `SessionManager` implementations delegate these Create/Read/Update/Delete (CRUD) operations to an internal component, the link:static/current/apidocs/org/apache/shiro/session/mgt/eis/SessionDAO.html[`SessionDAO`], which reflects the https://en.wikipedia.org/wiki/Data_access_object[Data Access Object (DAO)] design pattern.
The power of the SessionDAO is that you can implement this interface to communicate with _any_ data store you wish. This means your session data can reside in memory, on the file system, in a relational database or NoSQL data store, or any other location you need. You have control over persistence behavior.
@@ -254,7 +254,7 @@
If you wish to use your own `ehcache.xml` file, ensure that you have defined a similar cache entry for Shiro's needs. Most likely you might change the `maxElementsInMemory` attribute value to meet your needs. However, it is very important that at least the following two attributes exist (and are not changed) in your own configuration:
-* `overflowToDisk="true"` - this ensures that if you run out of process memory, sessions won't be lost and can serialized to disk
+* `overflowToDisk="true"` - this ensures that if you run out of process memory, sessions won't be lost and can be serialized to disk
* `eternal="true"` - ensures that cache entries (Session instances) are never expired or expunged automatically by the cache. This is necessary because Shiro does its own validation based on a scheduled process (see "Session Validation & Scheduling" below). If we turned this off, the cache would likely evict Sessions without Shiro knowing about it, which could cause problems.
[#SessionManagement-SessionManager-Storage-EHCacheSessionDAO-CacheName]
@@ -275,7 +275,7 @@
...
----
-Just ensure that a corresponding entry in `ehcache.xml` matches that name and you've configured `overflowToDisk="true"` and `eternal="true"` as mentioned above.
+Just ensure that a corresponding entry in `ehcache.xml` matches that name, and you've configured `overflowToDisk="true"` and `eternal="true"` as mentioned above.
[#SessionManagement-SessionManager-Storage-CustomSessionIDs]
==== Custom Session IDs
@@ -386,19 +386,19 @@
But be careful! If you turn this off, you are responsible for ensuring that your session data store doesn't exhaust its space. You must delete invalid sessions from you data store yourself!
-Note also that even if you prevent Shiro from deleting invalid sessions, you still should enable session validation somehow - either via Shiro's existing validation mechanisms or via a custom mechanism you provide yourself (see the above "Disabling Session Validation" section above for more). The validation mechanism will update your session records to reflect the invalid state (e.g. when it was invalidated, when it was last accessed, etc), even if you will delete them manually yourself at some other time.
+Note also that even if you prevent Shiro from deleting invalid sessions, you still should enable session validation somehow - either via Shiro's existing validation mechanisms or via a custom mechanism you provide yourself (see the above "Disabling Session Validation" section above for more). The validation mechanism will update your session records to reflect the invalid state (e.g. when it was invalidated, when it was last accessed, etc.), even if you will delete them manually yourself at some other time.
[DANGER]
====
.Warning
-If you configure Shiro so it does not delete invalid sessions, you are responsible for ensuring that your session data store doesn 't exhaust its space. You must delete invalid sessions from you data store yourself!
+If you configure Shiro, so it does not delete invalid sessions, you are responsible for ensuring that your session data store doesn't exhaust its space. You must delete invalid sessions from you data store yourself!
Also note that disabling session deletion is *not* the same as disabling session validation scheduling. You should almost always use a session validation scheduling mechanism - either one supported by Shiro directly or your own.
====
[#SessionManagement-SessionClustering]
== Session Clustering
-One of the very exciting things about Apache Shiro's session capabilities is that you can cluster Subject sessions natively and never need to worry again about how to cluster sessions based on your container environment. That is, if you use Shiro's native sessions and configure a session cluster, you can, say, deploy to Jetty or Tomcat in development, JBoss or Geronimo in production, or any other environment - all the while never worrying about container/environment-specific clustering setup or configuration. Configure session clustering once in Shiro and it works no matter your deployment environment.
+One of the very exciting things about Apache Shiro's session capabilities is that you can cluster Subject sessions natively and never need to worry again about how to cluster sessions based on your container environment. That is, if you use Shiro's native sessions and configure a session cluster, you can, say, deploy to Jetty or Tomcat in development, JBoss or Geronimo in production, or any other environment - all the while never worrying about container/environment-specific clustering setup or configuration. Configure session clustering once in Shiro, and it works no matter your deployment environment.
So how does it work?
@@ -406,7 +406,7 @@
*Distributed Caches*
-Distributed Caches such as https://www.ehcache.org/documentation/2.7/configuration/distributed-cache-configuration.html[Ehcache+TerraCotta], https://www.gigaspaces.com/[GigaSpaces] https://www.oracle.com/technetwork/middleware/coherence/overview/index.html[Oracle Coherence], and https://memcached.org/[Memcached] (and many others) already solve the distributed-data-at-the-persistence-level problem. Therefore enabling Session clustering in Shiro is as simple as configuring Shiro to use a distributed cache.
+Distributed Caches such as https://www.ehcache.org/documentation/2.7/configuration/distributed-cache-configuration.html[Ehcache+TerraCotta], https://www.gigaspaces.com/[GigaSpaces] https://www.oracle.com/technetwork/middleware/coherence/overview/index.html[Oracle Coherence], and https://memcached.org/[Memcached] (and many others) already solve the distributed-data-at-the-persistence-level problem. Therefore, enabling Session clustering in Shiro is as simple as configuring Shiro to use a distributed cache.
This gives you the flexibility of choosing the exact clustering mechanism that is suitable for _your_ environment.
@@ -424,7 +424,7 @@
[#SessionManagement-SessionClustering-EnterpriseCacheSessionDAO]
=== `EnterpriseCacheSessionDAO`
-As you might expect, Shiro already provides a `SessionDAO` implementation that will persist data to an enterprise/distributed Cache. The link:static/current/apidocs/org/apache/shiro/session/mgt/eis/EnterpriseCacheSessionDAO.html[EnterpriseCacheSessionDAO] expects a Shiro `Cache` or `CacheManager` to be configured on it so it can leverage the caching mechanism.
+As you might expect, Shiro already provides a `SessionDAO` implementation that will persist data to an enterprise/distributed Cache. The link:static/current/apidocs/org/apache/shiro/session/mgt/eis/EnterpriseCacheSessionDAO.html[EnterpriseCacheSessionDAO] expects a Shiro `Cache` or `CacheManager` to be configured on it, so it can leverage the caching mechanism.
For example, in `shiro.ini`:
@@ -469,7 +469,7 @@
So when Shiro evaluates the `securityManager.cacheManager = $cacheManager` line, it will discover that the `EnterpriseCacheSessionDAO` implements the `CacheManagerAware` interface and call the `setCacheManager` method with your configured `CacheManager` as the method argument.
-Then at runtime, when the `EnterpriseCacheSessionDAO` needs the `activeSessionsCache` it will ask the `CacheManager` instance to return it it, using the `activeSessionsCacheName` as the lookup key to get a `Cache` instance. That `Cache` instance (backed by your distributed/enterprise caching product's API) will be used to store and retrieve sessions for all of the `SessionDAO` CRUD operations.
+Then at runtime, when the `EnterpriseCacheSessionDAO` needs the `activeSessionsCache` it will ask the `CacheManager` instance to return it, using the `activeSessionsCacheName` as the lookup key to get a `Cache` instance. That `Cache` instance (backed by your distributed/enterprise caching product's API) will be used to store and retrieve sessions for all of the `SessionDAO` CRUD operations.
[#SessionManagement-SessionClustering-EhcacheTerracotta]
=== Ehcache + Terracotta
@@ -512,7 +512,7 @@
</ehcache>
----
-Of course you will want to change your `<terracottaConfig url="localhost:9510"/>` entry to reference the appropriate host/port of your Terracotta server array. Also notice that, unlike the <<SessionManagement-SessionManager-Storage-EHCacheSessionDAO-CacheConfiguration,previous>> configuration, the `ehcache-activeSessionCache` element *_DOES NOT_* set `diskPersistent` or `overflowToDisk` attributes to `true`. They should both be `false` as true values are not supported in clustered configuration.
+Of course, you will want to change your `<terracottaConfig url="localhost:9510"/>` entry to reference the appropriate host/port of your Terracotta server array. Also notice that, unlike the <<SessionManagement-SessionManager-Storage-EHCacheSessionDAO-CacheConfiguration,previous>> configuration, the `ehcache-activeSessionCache` element *_DOES NOT_* set `diskPersistent` or `overflowToDisk` attributes to `true`. They should both be `false` as true values are not supported in clustered configuration.
After you've saved this `ehcache.xml` file, we'll need to reference it in Shiro's configuration. Assuming you've made the terracotta-specific `ehcache.xml` file accessible at the root of the classpath, here is the final Shiro configuration that enables Terracotta+Ehcache clustering for all of Shiro's needs (including Sessions):
@@ -632,7 +632,7 @@
[#SessionManagement-SessionsSubjectState-HybridApproach-SessionStorageEvaluator-SubjectInspection]
===== Subject Inspection
-When implementing the `isSessionStorageEnabled(subject)` interface method, you can always look at the `Subject` and get access to whatever you need to make your decision. Of course all of the expected Subject methods are available to use (`getPrincipals()`, etc), but environment-specific `Subject` instances are valuable as well.
+When implementing the `isSessionStorageEnabled(subject)` interface method, you can always look at the `Subject` and get access to whatever you need to make your decision. Of course all the expected Subject methods are available to use (`getPrincipals()`, etc.), but environment-specific `Subject` instances are valuable as well.
For example, in web applications, if that decision must be made based on data in the current `ServletRequest`, you can get the request or the response because the runtime `Subject` instance is actually a link:static/current/apidocs/org/apache/shiro/web/subject/WebSubject.html[`WebSubject`] instance:
@@ -675,7 +675,7 @@
[#SessionManagement-SessionsSubjectState-WebApplications]
=== Web Applications
-Often web applications wish to simply enable or disable session creation on a per request basis, regardless of which Subject is executing a request. This is often used to good effect in supporting REST and Messaging/RMI architectures. For example, perhaps normal end-users (humans using a browser) are allowed to create and use sessions, but remote API clients use REST or SOAP and shouldn't have sessions at all (because they authenticate on every request, as is common in REST/SOAP architectures).
+Often web applications wish to simply enable or disable session creation on a per-request basis, regardless of which Subject is executing a request. This is often used to good effect in supporting REST and Messaging/RMI architectures. For example, perhaps normal end-users (humans using a browser) are allowed to create and use sessions, but remote API clients use REST or SOAP and shouldn't have sessions at all (because they authenticate on every request, as is common in REST/SOAP architectures).
To support this hybrid/per-request capability, a `noSessionCreation` filter has been added to Shiro's 'pool' of default filters enabled for web applications. This filter will prevent new sessions from being created during a request to guarantee a stateless experience. In `shiro.ini` `[urls]` section, you typically define this filter in front of all others to ensure a session will never be used.
diff --git a/src/site/content/spring-boot.adoc b/src/site/content/spring-boot.adoc
index 7a47352..5ccf5e7 100644
--- a/src/site/content/spring-boot.adoc
+++ b/src/site/content/spring-boot.adoc
@@ -6,14 +6,14 @@
:idprefix:
:toc:
-Shiro's Spring-Boot integration is the easiest way to integrate Shiro into a Spring-base application, for more general Spring Framework integration, take a the link:spring-framework.html[annotation] or link:spring-xml.html[XML] guides.
+Shiro's Spring-Boot integration is the easiest way to integrate Shiro into a Spring-base application, for more general Spring Framework integration, take the link:spring-framework.html[annotation] or link:spring-xml.html[XML] guides.
[#web_applications]
== Web Applications
Shiro has first-class support for Spring web applications. In a web application, all Shiro-accessible web requests must go through a main Shiro Filter. This filter itself is extremely powerful, allowing for ad-hoc custom filter chains to be executed based on any URL path expression.
-First include the Shiro Spring web starter dependency in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this).
+First include the Shiro Spring web starter dependency in you application classpath (we recommend using a tool such as Apache Maven or Gradle to manage this).
++++
<@dependencies.dependencies anchorId="web" deps=[{"g":"org.apache.shiro", "a":"shiro-spring-boot-web-starter", "v":"${versions.latestRelease}"}] />
@@ -50,7 +50,7 @@
If you are using Shiro's annotations see the link:#annotations_and_web_applications[annotation] section below.
-You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring-boot-web[samples on Github].
+You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring-boot-web[samples on GitHub].
=== Enabling Shiro Annotations
@@ -68,7 +68,7 @@
=== Annotations and Web Applications
-Shiro annotations are fully supported for use in `@Controller` classes, for example:
+Shiro's annotations are fully supported for use in `@Controller` classes, for example:
[source,java]
----
@@ -83,7 +83,7 @@
}
----
-A `ShiroFilterChainDefinition` bean with at least one definition is still required for this to work, either configure all paths to be accessable via the `anon` filter or a filter in 'permissive' mode, for example: `authcBasic[permissive]`.
+A `ShiroFilterChainDefinition` bean with at least one definition is still required for this to work, either configure all paths to be accessible via the `anon` filter or a filter in 'permissive' mode, for example: `authcBasic[permissive]`.
[source,java]
----
@@ -163,7 +163,7 @@
== Standalone Applications
-Include the Shiro Spring starter dependency in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this).
+Include the Shiro Spring starter dependency in you application classpath (we recommend using a tool such as Apache Maven or Gradle to manage this).
++++
<@dependencies.dependencies anchorId="cli" deps=[{"g":"org.apache.shiro", "a":"shiro-spring-boot-starter", "v":"${versions.latestRelease}"}] />
@@ -179,7 +179,7 @@
}
----
-The easiest way to setup Shiro, so that all SecurityUtils.* methods work in all cases, is to make the `SecurityManager` bean a static singleton. DO NOT do this in web applications - see the link:#web_applications[Web Applications] section below instead.
+The easiest way to set up Shiro, so that all SecurityUtils.* methods work in all cases, is to make the `SecurityManager` bean a static singleton. DO NOT do this in web applications - see the link:#web_applications[Web Applications] section below instead.
[source,java]
----
@@ -199,4 +199,4 @@
SecurityUtils.getSubject();
----
-You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring-boot[samples on Github].
+You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring-boot[samples on GitHub].
diff --git a/src/site/content/spring-framework.adoc b/src/site/content/spring-framework.adoc
index 948e7c2..fe1be7d 100644
--- a/src/site/content/spring-framework.adoc
+++ b/src/site/content/spring-framework.adoc
@@ -10,7 +10,7 @@
== Standalone Applications
-Include the Shiro Spring dependency in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this).
+Include the Shiro Spring dependency in you application classpath (we recommend using a tool such as Apache Maven or Gradle to manage this).
++++
<@dependencies.dependencies anchorId="cli" deps=[{'g':'org.apache.shiro', 'a':'shiro-spring', "v":"${versions.latestRelease}"},{"g":'org.springframework', "a":'spring-context', "v":'${r"${spring.version}"}'}] />
@@ -55,7 +55,7 @@
}
----
-The easiest way to setup Shiro, so that all SecurityUtils.* methods work in all cases, is to make the `SecurityManager` bean a static singleton.
+The easiest way to set up Shiro, so that all SecurityUtils.* methods work in all cases, is to make the `SecurityManager` bean a static singleton.
DO NOT do this in web applications - see the link:#web_applications[Web Applications] section below instead.
[source,java]
@@ -75,14 +75,14 @@
SecurityUtils.getSubject();
----
-You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring[samples on Github].
+You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring[samples on GitHub].
[#web_applications]
== Web Applications
Shiro has first-class support for Spring web applications. In a web application, all Shiro-accessible web requests must go through a main Shiro Filter. This filter itself is extremely powerful, allowing for ad-hoc custom filter chains to be executed based on any URL path expression.
-Include the Shiro Spring web dependencies in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this).
+Include the Shiro Spring web dependencies in you application classpath (we recommend using a tool such as Apache Maven or Gradle to manage this).
++++
<@dependencies.dependencies anchorId="web" deps=[{"g":'org.apache.shiro', "a":'shiro-spring', "v":"${versions.latestRelease}"}, {"g":'org.apache.shiro', "a":'shiro-web', "v":"${versions.latestRelease}"},{"g":'org.springframework', "a":'spring-webmvc', "v":'${r"${spring.version}"}'}] />
@@ -156,7 +156,7 @@
If you are using Shiro's annotations see the link:#annotations_and_web_applications[annotation] section below.
-You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring-mvc[samples on Github].
+You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring-mvc[samples on GitHub].
== Enabling Shiro Annotations
@@ -189,7 +189,7 @@
}
----
-A `ShiroFilterChainDefinition` bean with at least one definition is still required for this to work, either configure all paths to be accessable via the `anon` filter or a filter in 'permissive' mode, for example: `authcBasic[permissive]`.
+A `ShiroFilterChainDefinition` bean with at least one definition is still required for this to work, either configure all paths to be accessible via the `anon` filter or a filter in 'permissive' mode, for example: `authcBasic[permissive]`.
[source,java]
----
diff --git a/src/site/content/spring-xml.adoc b/src/site/content/spring-xml.adoc
index 612f1f0..c878ee3 100644
--- a/src/site/content/spring-xml.adoc
+++ b/src/site/content/spring-xml.adoc
@@ -7,7 +7,7 @@
This page covers the ways to integrate Shiro into https://spring.io[Spring]-based applications.
-Shiro's JavaBeans compatibility makes it perfectly suited to be configured via Spring XML or other Spring-based configuration mechanisms. Shiro applications need an application singleton `SecurityManager` instance. Note that this does not have to be a _static_ singleton, but there should only be a single instance used by the application, whether its a static singleton or not.
+Shiro's JavaBeans compatibility makes it perfectly suited to be configured via Spring XML or other Spring-based configuration mechanisms. Shiro's applications need an application singleton `SecurityManager` instance. Note that this does not have to be a _static_ singleton, but there should only be a single instance used by the application, whether it is a static singleton or not.
== Standalone Applications
@@ -81,7 +81,7 @@
</filter-mapping>
----
-You can see a full example in our https://github.com/apache/shiro/tree/main/samples/spring-xml[samples on Github].
+You can see a full example in our https://github.com/apache/shiro/tree/main/samples/spring-xml[samples on GitHub].
=== applicationContext.xml
diff --git a/src/site/content/subject.adoc b/src/site/content/subject.adoc
index 6b92aa9..aa438a3 100644
--- a/src/site/content/subject.adoc
+++ b/src/site/content/subject.adoc
@@ -23,7 +23,7 @@
Also, in the security world, the term 'Subject' is actually the recognized nomenclature.
Shiro's API encourages a `Subject`-centric programming paradigm for applications. When coding application logic, most application developers want to know who the _currently executing_ user is.
-While the application can usually look up any user via their own mechanisms (UserService, etc), when it comes to security, the most important question is *"Who is the _current_ user?"*
+While the application can usually look up any user via their own mechanisms (UserService, etc.), when it comes to security, the most important question is *"Who is the _current_ user?"*
While any Subject can be acquired by using the `SecurityManager`, application code based on only the current user/`Subject` is much more natural and intuitive.
@@ -104,7 +104,7 @@
There are many different types of exceptions you can check, or throw your own for custom conditions Shiro might not account for.
See the link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[AuthenticationException JavaDoc] for more.
-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:
@@ -251,7 +251,7 @@
The important thing to know about thread association is that 2 things must always occur:
-. The Subject is _bound_ to the thread so it is available at all points of the thread's execution. Shiro does this via its `ThreadState` mechanism which is an abstraction on top of a `ThreadLocal`.
+. The Subject is _bound_ to the thread, so it is available at all points of the thread's execution. Shiro does this via its `ThreadState` mechanism which is an abstraction on top of a `ThreadLocal`.
. The Subject is _unbound_ at some point later, even if the thread execution results in an error. This ensures the thread remains clean and clear of any previous `Subject` state in a pooled/reusable thread environment.
These principles are guaranteed to occur in the 3 mechanisms listed above. Their usage is elaborated next.
@@ -277,7 +277,7 @@
//with the current thread and everything is as it was before
----
-Of course `Callable` instances are supported as well so you can have return values and catch exceptions:
+Of course `Callable` instances are supported as well, so you can have return values and catch exceptions:
[source,java]
----
@@ -344,7 +344,7 @@
[CAUTION]
.Web Use
====
-Don''t use the above 'ThreadState' code example in a thread that is processing a web request. Web-specific ThreadState implementations are used during web requests instead. Instead, ensure the 'ShiroFilter' intercepts web requests to ensure Subject building/binding/cleanup is done properly.
+Don't use the above 'ThreadState' code example in a thread that is processing a web request. Web-specific ThreadState implementations are used during web requests instead. Instead, ensure the 'ShiroFilter' intercepts web requests to ensure Subject building/binding/cleanup is done properly.
====
==== A Different Thread
diff --git a/src/site/content/terminology.adoc b/src/site/content/terminology.adoc
index 7920eef..57cd9a7 100644
--- a/src/site/content/terminology.adoc
+++ b/src/site/content/terminology.adoc
@@ -7,9 +7,9 @@
:idprefix:
:icons: font
-Please just take 2 minutes to read and understand this - it is __really__ important. Really. The terms and concepts here are referred to everywhere in the documentation and it will __greatly__ simplify your understanding of Shiro and security in general.
+Please just take 2 minutes to read and understand this - it is __really__ important. Really. The terms and concepts here are referred to everywhere in the documentation, and it will __greatly__ simplify your understanding of Shiro and security in general.
-Security can be really confusing because of the terminology used. We'll make life easier by clarifying some core concepts and you'll see how nicely the Shiro API reflects them:
+Security can be really confusing because of the terminology used. We'll make life easier by clarifying some core concepts, and you'll see how nicely the Shiro API reflects them:
[#Terminology-authentication]
* *Authentication* +
@@ -21,7 +21,7 @@
[#Terminology-cipher]
* *Cipher* +
-A cipher is an algorithm for performing encryption or decryption. The algorithm generally relies on a piece of information called a key. And the encryption varies based on the key so decyrption is extremely difficult without it.
+A cipher is an algorithm for performing encryption or decryption. The algorithm generally relies on a piece of information called a key. And the encryption varies based on the key so decryption is extremely difficult without it.
+
Ciphers come in different variations. Block Ciphers work on blocks of symbols usually of a fixed size while Stream Ciphers work on a continuous stream of symbols. Symmetric Ciphers use the same key for encryption and decryption while Asymmetric Ciphers use different keys. And if a key in an asymmetric cipher cannot be derived from the other, then one can be shared publicly creating public/private key pairs.
diff --git a/src/site/content/testing.adoc b/src/site/content/testing.adoc
index cd1f10e..5bce7be 100644
--- a/src/site/content/testing.adoc
+++ b/src/site/content/testing.adoc
@@ -138,7 +138,7 @@
But as stated above, the key in Shiro tests is to remember that any Subject instance (mock or real) must be bound to the thread during test execution. So all we need to do is bind the mock Subject to ensure things work as expected.
-(this example uses EasyMock, but Mockito works equally as well):
+(this example uses EasyMock, but Mockito works equally well):
[source,java]
----
@@ -180,7 +180,7 @@
As you can see, we're not setting up a Shiro `SecurityManager` instance or configuring a `Realm` or anything like that. We're simply creating a mock `Subject` instance and binding it to the thread via the `setSubject` method call. This will ensure that any calls in our test code or in the code we're testing to `SecurityUtils.getSubject()` will work correctly.
-Note that the `setSubject` method implementation will bind your mock Subject to the thread and it will remain there until you call `setSubject` with a different `Subject` instance or until you explicitly clear it from the thread via the `clearSubject()` call.
+Note that the `setSubject` method implementation will bind your mock Subject to the thread, and it will remain there until you call `setSubject` with a different `Subject` instance or until you explicitly clear it from the thread via the `clearSubject()` call.
How long you keep the subject bound to the thread (or swap it out for a new instance in a different test) is up to you and your testing requirements.
@@ -189,7 +189,7 @@
The `tearDownSubject()` method in the example uses a Junit 4 annotation to ensure that the Subject is cleared from the thread after every test method is executed, no matter what. This requires you to set up a new `Subject` instance and set it (via `setSubject`) for every test that executes.
-This is not strictly necessary however. For example, you could just bind a new Subject instance (via `setSujbect`) at the beginning of every test, say, in an `@Before`-annotated method. But if you're going to do that, you might as well have the `@After tearDownSubject()` method to keep things symmetrical and 'clean'.
+This is not strictly necessary, however. For example, you could just bind a new Subject instance (via `setSujbect`) at the beginning of every test, say, in an `@Before`-annotated method. But if you're going to do that, you might as well have the `@After tearDownSubject()` method to keep things symmetrical and 'clean'.
You can mix and match this setup/teardown logic in each method manually or use the @Before and @After annotations as you see fit. The `AbstractShiroTest` super class will however unbind the Subject from the thread after all tests because of the `@AfterClass` annotation in its `tearDownShiro()` method.
@@ -198,12 +198,12 @@
Now that we've covered unit test setup, let's talk a bit about integration testing. Integration testing is testing implementations across API boundaries. For example, testing that implementation A works when calling implementation B and that implementation B does what it is supposed to.
-You can easily perform integration testing in Shiro as well. Shiro's `SecurityManager` instance and things it wraps (like Realms and SessionManager, etc) are all very lightweight POJOs that use very little memory. This means you can create and tear down a `SecurityManager` instance for every test class you execute. When your integration tests run, they will be using 'real' `SecurityManager` and `Subject` instances like your application will be using at runtime.
+You can easily perform integration testing in Shiro as well. Shiro's `SecurityManager` instance and things it wraps (like Realms and SessionManager, etc.) are all very lightweight POJOs that use very little memory. This means you can create and tear down a `SecurityManager` instance for every test class you execute. When your integration tests run, they will be using 'real' `SecurityManager` and `Subject` instances like your application will be using at runtime.
[#Testing-ExampleShiroIntegrationTest]
=== ExampleShiroIntegrationTest
-The example code below looks almost identical to the Unit Test example above, but the 3 step process is slightly different:
+The example code below looks almost identical to the Unit Test example above, but the 3-step process is slightly different:
. There is now a step '0', which sets up a 'real' SecurityManager instance.
. Step 1 now constructs a 'real' Subject instance with the `Subject.Builder` and binds it to the thread.
diff --git a/src/site/content/tutorial.adoc b/src/site/content/tutorial.adoc
index 129b707..55dab77 100644
--- a/src/site/content/tutorial.adoc
+++ b/src/site/content/tutorial.adoc
@@ -126,7 +126,7 @@
We'll be running a simple command-line application, so we'll need to create a Java class with a `public static void main(String[] args)` method.
-In the same directory containing your `pom.xml` file, create a *`src/main/java` sub directory. In `src/main/java` create a `Tutorial.java` file with the following contents:
+In the same directory containing your `pom.xml` file, create a *`src/main/java` subdirectory. In `src/main/java` create a `Tutorial.java` file with the following contents:
[source,java]
@@ -157,7 +157,7 @@
== Test Run
-To try our Tutorial application, execute the following in a command prompt in your tutorial project's root dirctory (e.g. `shiro-tutorial`), and type the following:
+To try our Tutorial application, execute the following in a command prompt in your tutorial project's root directory (e.g. `shiro-tutorial`), and type the following:
`mvn compile exec:java`
@@ -171,7 +171,7 @@
The first thing to understand in enabling Shiro in an application is that almost everything in Shiro is related to a central/core component called the `SecurityManager`. For those familiar with Java security, this is Shiro's notion of a SecurityManager - it is _NOT_ the same thing as the `java.lang.SecurityManager`.
-While we will cover Shiro's design in detail in the link:architecture.html[Architecture] chapter, it is good enough for now to know that the Shiro `SecurityManager` is the core of a Shiro environment for an application and one `SecurityManager` must exist per application. So, the first thing we must do in our Tutorial application is set-up the `SecurityManager` instance.
+While we will cover Shiro's design in detail in the link:architecture.html[Architecture] chapter, it is good enough for now to know that the Shiro `SecurityManager` is the core of a Shiro environment for an application and one `SecurityManager` must exist per application. So, the first thing we must do in our Tutorial application is set up the `SecurityManager` instance.
== Configuration
@@ -250,15 +250,15 @@
Here is what the above additions are doing:
-. We use Shiro's `IniSecurityManagerFactory` implementation to ingest our `shiro.ini` file which is located at the root of the classpath. This implementation reflects Shiro's support of the https://en.wikipedia.org/wiki/Factory_method_pattern[Factory Method Design Pattern]. The `classpath:` prefix is an resource indicator that tells shiro where to load the ini file from (other prefixes, like `url:` and `file:` are supported as well).
+. We use Shiro's `IniSecurityManagerFactory` implementation to ingest our `shiro.ini` file which is located at the root of the classpath. This implementation reflects Shiro's support of the https://en.wikipedia.org/wiki/Factory_method_pattern[Factory Method Design Pattern]. The `classpath:` prefix is a resource indicator that tells shiro where to load the ini file from (other prefixes, like `url:` and `file:` are supported as well).
. The `factory.getInstance()` method is called, which parses the INI file and returns a `SecurityManager` instance reflecting the configuration.
-. In this simple example, we set the `SecurityManager` to be a _static_ (memory) singleton, accessible across the JVM. Note however that this is not desireable if you will ever have more than one Shiro-enabled application in a single JVM. For this simple example, it is ok, but more sophisticated application environments will usually place the `SecurityManager` in application-specific memory (such as in a web app's `ServletContext` or a Spring, Guice or JBoss DI container instance).
+. In this simple example, we set the `SecurityManager` to be a _static_ (memory) singleton, accessible across the JVM. Note however that this is not desirable if you will ever have more than one Shiro-enabled application in a single JVM. For this simple example, it is ok, but more sophisticated application environments will usually place the `SecurityManager` in application-specific memory (such as in a web app's `ServletContext` or a Spring, Guice or JBoss DI container instance).
== Using Shiro
-Now that our SecurityManager is set-up and ready-to go, now we can start doing the things we really care about - performing security operations.
+Now that our SecurityManager is set up and ready-to go, now we can start doing the things we really care about - performing security operations.
When securing our applications, probably the most relevant questions we ask ourselves are “Who is the current user?” or “Is the current user allowed to do X”? It is common to ask these questions as we're writing code or designing user interfaces: applications are usually built based on user stories, and you want functionality represented (and secured) based on a per-user basis. So, the most natural way for us to think about security in our application is based on the current user. Shiro’s API fundamentally represents the notion of 'the current user' with its `Subject` concept.
@@ -335,7 +335,7 @@
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:
@@ -485,8 +485,8 @@
== Summary
-Hopefully this introduction tutorial helped you understand how to set-up Shiro in a basic application as well Shiro's primary design concepts, the `Subject` and `SecurityManager`.
+Hopefully this introduction tutorial helped you understand how to set up Shiro in a basic application as well Shiro's primary design concepts, the `Subject` and `SecurityManager`.
-But this was a fairly simple application. You might have asked yourself, "What if I don't want to use INI user accounts and instead want to connect to a more complex user data source?"
+But this was a fairly simple application. You might have asked yourself "What if I don't want to use INI user accounts and instead want to connect to a more complex user data source?"
To answer that question requires a little deeper understanding of Shiro's architecture and supporting configuration mechanisms. We'll cover Shiro's link:architecture.html[Architecture] next.
diff --git a/src/site/content/web-features.adoc b/src/site/content/web-features.adoc
index ca85148..a05d39a 100644
--- a/src/site/content/web-features.adoc
+++ b/src/site/content/web-features.adoc
@@ -22,4 +22,4 @@
The tags allow you to easily control page output based on the current user's state and access rights.
* *Transparent HttpSession support*
-If you are using Shiro's native sessions, we have implemented HTTP Session API and the Servlet 2.5+ API so you don't have to change any of your existing web code to use Shiro.
+If you are using Shiro's native sessions, we have implemented HTTP Session API and the Servlet 2.5+ API, so you don't have to change any of your existing web code to use Shiro.
diff --git a/src/site/content/web.adoc b/src/site/content/web.adoc
index c534087..d9a98b0 100644
--- a/src/site/content/web.adoc
+++ b/src/site/content/web.adoc
@@ -14,7 +14,7 @@
The simplest way to integrate Shiro into any web application is to configure a Servlet ContextListener and Filter in web.xml that understands how to read Shiro's INI configuration. The bulk of the INI config format itself is defined in the Configuration pages's link:/configuration.html#Configuration-INIConfiguration-Sections[INI Sections] section, but we'll cover some additional web-specific sections here.
[INFO]
-.Using Jakart EE?
+.Using Jakarta EE?
====
The below configuration is not required if using link:jakarta-ee.html[Jakarta EE integration] or basic CDI integration module.
====
@@ -81,7 +81,7 @@
===== Custom `WebEnvironment` Class
-By default the `EnvironmentLoaderListener` will create an `IniWebEnvironment` instance, which assumes Shiro's INI-based link:configuration.html[Configuration]. If you like, you may specify a custom `WebEnvironment` instance instead by specifying a `ServletContext` `context-param` in `web.xml`:
+By default, the `EnvironmentLoaderListener` will create an `IniWebEnvironment` instance, which assumes Shiro's INI-based link:configuration.html[Configuration]. If you like, you may specify a custom `WebEnvironment` instance instead by specifying a `ServletContext` `context-param` in `web.xml`:
[source,xml]
----
@@ -210,7 +210,7 @@
* You might edit security configuration a lot and don't want to add revision control 'noise' to the web.xml file
* You might want to separate security config from the rest of web.xml config
-* Your security configuration might become large and you want to keep web.xml lean and easier to read
+* Your security configuration might become large, and you want to keep web.xml lean and easier to read
* You have a complex build system where the same shiro config might need to be referenced in multiple places
It is up to you - use what makes sense for your project.
@@ -269,7 +269,7 @@
/account/** = ssl, authc
----
-This line states that "Any request to my application's path of `/account` or any of it's sub paths (`/account/foo`, `/account/bar/baz`, etc) will trigger the 'ssl, authc' filter chain". We'll cover filter chains below.
+This line states that "Any request to my application's path of `/account` or any of its sub paths (`/account/foo`, `/account/bar/baz`, etc.) will trigger the 'ssl, authc' filter chain". We'll cover filter chains below.
Note that all path expressions are relative to your application's context root. This means that if you deploy your application one day to, say, `www.somehost.com/myapp` and then later deploy it to `www.anotherhost.com` (no 'myapp' sub-path), the pattern matching will still work.
All paths are relative to the link:https://docs.oracle.com/javaee/1.3/api/javax/servlet/http/HttpServletRequest.html#getContextPath()[`HttpServletRequest.getContextPath()`] value.
@@ -278,7 +278,7 @@
.Order Matters!
====
URL path expressions are evaluated against an incoming request in the order they are defined and the _FIRST MATCH WINS_.
-For example, let's asume that there are the following chain definitions:
+For example, let's assume that there are the following chain definitions:
[source,ini]
----
@@ -305,7 +305,7 @@
And because filter tokens define chains (aka a List), remember that order matters! Define your comma-delimited list in the order that you want the request to flow through the chain.
-Finally, each filter is free to handle the response however it wants if its necessary conditions are not met (e.g. perform a redirect, respond with an HTTP error code, direct rendering, etc). Otherwise it is expected to allow the request to continue through the chain on to the final destination view.
+Finally, each filter is free to handle the response however it wants if its necessary conditions are not met (e.g. perform a redirect, respond with an HTTP error code, direct rendering, etc). Otherwise, it is expected to allow the request to continue through the chain on to the final destination view.
[TIP]
.Tip
@@ -377,9 +377,9 @@
== Enabling and Disabling Filters
-As is the case with any filter chain definition mechanism (`web.xml`, Shiro's INI, etc), you enable a filter just by including it in the filter chain definition, and you disable it by removing it from the chain definition.
+As is the case with any filter chain definition mechanism (`web.xml`, Shiro's INI, etc.), you enable a filter just by including it in the filter chain definition, and you disable it by removing it from the chain definition.
-But a new feature added in Shiro 1.2 is the ability to enable or disable filters without removing them from the filter chain. If enabled (the default setting), then a request will be filtered as expected. If disabled, then the filter will allow the request to pass through immediately to the next element in the `FilterChain`. You can trigger a filter's enabled state generally based on a configuration property, or you can even trigger it on a _per request_ basis.
+But a new feature added in Shiro 1.2 is the ability to enable or disable filters without removing them from the filter chain. If enabled (the default setting), then a request will be filtered as expected. If disabled, then the filter will allow the request to pass through immediately to the next element in the `FilterChain`. You can trigger a filter's enabled state generally based on a configuration property, or you can even trigger it on a _per-request_ basis.
This is a powerful concept because it is often more convenient to enable or disable a filter based on certain requirements than to change the static filter chain definition, which would be permanent and inflexible.
@@ -409,7 +409,7 @@
...
----
-This example shows that potentially many URL paths can all require that a request must be secured by an SSL connection. Setting up SSL while in development can be frustrating and time consuming. While in development, you can disable the ssl filter. When deploying to production, you can enable it with one configuration property - something that is much easier than manually changing all of the URL paths or maintaining two Shiro configurations.
+This example shows that potentially many URL paths can all require that a request must be secured by an SSL connection. Setting up SSL while in development can be frustrating and time-consuming. While in development, you can disable the ssl filter. When deploying to production, you can enable it with one configuration property - something that is much easier than manually changing all the URL paths or maintaining two Shiro configurations.
=== Request-specific Enabling/Disabling
@@ -462,7 +462,7 @@
[NOTE]
====
-If you currently allowing URL rewriting to allow for a <code>jsessionid</code> in the URL, you must set `blockSemicolon` to `false`.
+If you're currently allowing URL rewriting to allow for a <code>jsessionid</code> in the URL, you must set `blockSemicolon` to `false`.
URL rewriting for `jsessionid` is defined in section "7.1.3" of the Java Servlet Specification, but it is generally NOT recommended.
====
@@ -499,7 +499,7 @@
This very simple implementation delegates all session management duties (including session clustering if the servlet container supports it) to the runtime Servlet container.
It is essentially a bridge for Shiro's session API to the servlet container and does little else.
-A benefit of using this default is that apps that work with existing servlet container session configuration (timeout, any container-specific clustering mechanisms, etc) will work as expected.
+A benefit of using this default is that apps that work with existing servlet container session configuration (timeout, any container-specific clustering mechanisms, etc.) will work as expected.
A downside of this default is that you are tied to the servlet container's specific session behavior. For example, if you wanted to cluster sessions, but you used Jetty for testing and Tomcat in production, your container-specific configuration (or code) would not be portable.
@@ -559,7 +559,7 @@
====== Session Cookie Configuration
-The DefaultWebSessionManager's `sessionIdCookie` default instance is a link:static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html[`SimpleCookie`]. This simple implementation allows JavaBeans-style property configuration for all of the relevant properties you would want to configure on an http Cookie.
+The DefaultWebSessionManager's `sessionIdCookie` default instance is a link:static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html[`SimpleCookie`]. This simple implementation allows JavaBeans-style property configuration for all the relevant properties you would want to configure on an http Cookie.
For example, you could set the Cookie domain:
@@ -653,7 +653,7 @@
</form>
----
-By default, the `FormAuthenticationFilter` will look for request parameters named `username`, `password` and `rememberMe`. If these are different than the form field names that you use in your form, you'll want to configure the names on the `FormAuthenticationFilter`. For example, in `shiro.ini`:
+By default, the `FormAuthenticationFilter` will look for request parameters named `username`, `password` and `rememberMe`. If these are different from the form field names that you use in your form, you'll want to configure the names on the `FormAuthenticationFilter`. For example, in `shiro.ini`:
[source,ini]
----
@@ -725,7 +725,7 @@
[#web_guesttag]
=== The `guest` tag
-The `guest` tag will display its wrapped content only if the current `Subject` is considered a 'guest'. A guest is any `Subject` that does not have an identity. That is, we don't know who the user is because they have not logged in and they are not remembered (from Remember Me services) from a previous site visit.
+The `guest` tag will display its wrapped content only if the current `Subject` is considered a 'guest'. A guest is any `Subject` that does not have an identity. That is, we don't know who the user is because they have not logged in, and they are not remembered (from Remember Me services) from a previous site visit.
Example:
diff --git a/src/site/content/webapp-tutorial.adoc b/src/site/content/webapp-tutorial.adoc
index eb0382c..52af113 100644
--- a/src/site/content/webapp-tutorial.adoc
+++ b/src/site/content/webapp-tutorial.adoc
@@ -26,7 +26,7 @@
== [[overview]] Overview
-While Apache Shiro's core design goals allow it to be used to secure _any_ JVM-based application, such as command line applications, server daemons, web apps, etc, this guide will focus on the most common use case: securing a web application running in a https://en.wikipedia.org/wiki/Java_servlet[Servlet] container, such as Tomcat or Jetty.
+While Apache Shiro's core design goals allow it to be used to secure _any_ JVM-based application, such as command line applications, server daemons, web apps, etc., this guide will focus on the most common use case: securing a web application running in a https://en.wikipedia.org/wiki/Java_servlet[Servlet] container, such as Tomcat or Jetty.
=== Prerequisites
@@ -39,7 +39,7 @@
=== Tutorial Format
-This is a step-by-step tutorial. The tutorial, and all of its steps, exist as a Git repository. When you clone the git repository, the `main` branch is your starting point. Each step in the tutorial is a separate branch. You can follow along simply by checking out the git branch that reflects the tutorial step you are reviewing.
+This is a step-by-step tutorial. The tutorial and all of its steps, exist as a Git repository. When you clone the git repository, the `main` branch is your starting point. Each step in the tutorial is a separate branch. You can follow along simply by checking out the git branch that reflects the tutorial step you are reviewing.
=== The Application
@@ -104,7 +104,7 @@
Here is what each means:
-* `pom.xml`: the Maven project/build file. It has Jetty configured so you can test your web app right away by running `mvn jetty:run`.
+* `pom.xml`: the Maven project/build file. It has Jetty configured, so you can test your web app right away by running `mvn jetty:run`.
* `README.md`: a simple project readme file
* `LICENSE`: the project's Apache 2.0 license
* `.travis.yml`: A https://travis-ci.org/[Travis CI] config file in case you want to run continuous integration on your project to ensure it always builds.
@@ -146,7 +146,7 @@
=== 1a: Add a `shiro.ini` file
-Shiro can be configured in many different ways in a web application, depending on the web and/or MVC framework you use. For example, you can configure Shiro via Spring, Guice, Tapestry, and many many more.
+Shiro can be configured in many different ways in a web application, depending on the web and/or MVC framework you use. For example, you can configure Shiro via Spring, Guice, Tapestry, and many more.
To keep things simple for now, we'll start a Shiro environment by using Shiro's default (and very simple) https://shiro.apache.org/configuration.html[INI-based configuration].
@@ -199,9 +199,9 @@
* The `<listener>` declaration defines a https://docs.oracle.com/javaee/6/api/javax/servlet/ServletContextListener.html[`ServletContextListener`] that starts up the Shiro environment (including the Shiro `SecurityManager`) upon web application startup. By default, this listener automatically knows to look for our `WEB-INF/shiro.ini` file for Shiro configuration.
-* The `<filter>` declaration defines the main `ShiroFilter`. This filter is expected to filter _all_ requests into the web application so Shiro can peform necessary identity and access control operations before allowing a request to reach the application.
+* The `<filter>` declaration defines the main `ShiroFilter`. This filter is expected to filter _all_ requests into the web application so Shiro can perform necessary identity and access control operations before allowing a request to reach the application.
-* The `<filter-mapping>` declaration ensures that _all_ request types are filed by the `ShiroFilter`. Often `filter-mapping` declarations don't specify `<dispatcher>` elements, but Shiro needs them all defined so it can filter all of the different request types that might execute for a web app.
+* The `<filter-mapping>` declaration ensures that _all_ request types are filed by the `ShiroFilter`. Often `filter-mapping` declarations don't specify `<dispatcher>` elements, but Shiro needs them all defined so it can filter all the different request types that might execute for a web app.
=== 1c: Run the webapp
@@ -233,7 +233,7 @@
Now we have Shiro integrated and running within a webapp. But we haven't actually told Shiro to do anything yet!
-Before we can login, or logout, or perform role-based or permission-based access control, or anything else security related, we need users!
+Before we can log in, or logout, or perform role-based or permission-based access control, or anything else security related, we need users!
We will need to configure Shiro to access a _User Store_ of some type, so it can look up users to perform login attempts, or check roles for security decisions, etc. There are many types of user stores that any application might need to access: maybe you store users in a MySQL database, maybe in MongoDB, maybe your company stores user accounts in LDAP or Active Directory, maybe you store them in a simple file, or some other proprietary data store.
@@ -245,11 +245,11 @@
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. The SecurityManager may be configured with multiple Realms, 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.
____
-So, we need to configure a Realm so we can access users.
+So, we need to configure a Realm, so we can access users.
=== 2a: Set up Stormpath
@@ -402,7 +402,7 @@
Note the optional lines:
-* If you have been using Stormpath for a while and you have more then one Stormpath application, the `stormpathRealm.applicationRestUrl` property must be set.
+* If you have been using Stormpath for a while, and you have more than one Stormpath application, the `stormpathRealm.applicationRestUrl` property must be set.
=== 2d: Run the webapp
@@ -513,11 +513,11 @@
$ mvn jetty:run
----
-=== Step 3d: Try to Login
+=== Step 3d: Try to Log in
-With your web browser, navigate to http://localhost:8080/login.jsp[localhost:8080/login.jsp] and you will see our new shiny login form.
+With your web browser, navigate to http://localhost:8080/login.jsp[localhost:8080/login.jsp], and you will see our new shiny login form.
-Enter in a username and password of the account you created at the end of Step 2, and hit 'Login'. If the login is successful, you will be directed to the home page! If the login fails, you will be shown the login page again.
+Enter a username and password of the account you created at the end of Step 2, and hit 'Login'. If the login is successful, you will be directed to the home page! If the login fails, you will be shown the login page again.
Tip: If you want a successful login to redirect the user to a different page other than the home page (context path `/`), you can set the `authc.successUrl = /whatever` in the INI's `[main]` section.
@@ -633,7 +633,7 @@
=== Step 5a: Add a new restricted section
-A new `src/main/webapp/account` directory was added. This directory (and all paths below it) simulates a 'private' or 'authenticated only' section of a website that you might want to restrict to only logged in users. The `src/main/webapp/account/index.jsp` file is just a placeholder for a simulated 'home account' page.
+A new `src/main/webapp/account` directory was added. This directory (and all paths below it) simulates a 'private' or 'authenticated only' section of a website that you might want to restrict to only logged-in users. The `src/main/webapp/account/index.jsp` file is just a placeholder for a simulated 'home account' page.
=== Step 5b: Configure `shiro.ini`
@@ -661,7 +661,7 @@
=== Step 5c: Update our home page
-The final change for Step 5 is to update the `/home.jsp` page to let the user know they can access the new part of the web site.
+The final change for Step 5 is to update the `/home.jsp` page to let the user know they can access the new part of the website.
These lines were added below the welcome message:
@@ -723,7 +723,7 @@
(to keep with our Star-Trek account theme :) )
-Once you've created the groups, add the `Jean-Luc Picard` account to the `Captains` and `Officers` groups. You might want to create some ad-hoc accounts and add them to whatever groups you like. Make sure some of the accounts don't overlap groups so you can see changes based on separate Groups assigned to user accounts.
+Once you've created the groups, add the `Jean-Luc Picard` account to the `Captains` and `Officers` groups. You might want to create some ad-hoc accounts and add them to whatever groups you like. Make sure some of the accounts don't overlap groups, so you can see changes based on separate Groups assigned to user accounts.
=== Step 6b: Role Based Access Control (RBAC) Tags
@@ -780,7 +780,7 @@
Role-based access control is good for many use cases, but it suffers from one major problem: you can't add or delete roles at runtime. Role checks are hard-coded with role names, so if you changed the role names or role configuration, or add or remove roles, you have to go back and change your code!
-Because of this, Shiro has a powerful marquis feature: built-in support for _permissions_. In Shiro, a permission is a raw statement of functionality, for example 'open a door' 'create a blog entry', 'delete the `jsmith` user', etc. Permissions reflect your application's raw functionality, so you only need to change permission checks when you change your application's functionlity - not if you want to change your role or user model.
+Because of this, Shiro has a powerful marquis feature: built-in support for _permissions_. In Shiro, a permission is a raw statement of functionality, for example 'open a door' 'create a blog entry', 'delete the `jsmith` user', etc. Permissions reflect your application's raw functionality, so you only need to change permission checks when you change your application's functionality - not if you want to change your role or user model.
To demonstrate this, we will create some permissions and assign them to a user, and then customize our web UI based on a user's authorization (permissions).
diff --git a/src/site/content/what-is-shiro.adoc b/src/site/content/what-is-shiro.adoc
index 6f55b72..db1d256 100644
--- a/src/site/content/what-is-shiro.adoc
+++ b/src/site/content/what-is-shiro.adoc
@@ -16,7 +16,7 @@
* Authentication and Authorization functionality should be as pluggable and flexible as possible.
* Authentication and Authorization are only half of a robust security framework. Enterprise Session Management and easy Cryptography services are the other half.
* *Session Management should not be tied to web or EJB applications*. We believe Sessions are a business-tier concern that should be accessible in any client or server environment.
-* Heterogeneous client mediums (HTTP requests, Applets, Java Web Start, C# applications, etc) should be able to participate in the same Session, regardless of the client technology.
+* Heterogeneous client mediums (HTTP requests, Applets, Java Web Start, C# applications, etc.) should be able to participate in the same Session, regardless of the client technology.
* Security code should be eliminated as much as possible in favor of a cleaner declarative security model utilizing JDK 1.5 Annotations or XML, whichever you prefer.
* Last but definitely not least, a security framework should support a *dynamic*, *instance-level* security model out-of-the-box (i.e. changing user/group/role/permission assignments *during runtime*)
@@ -35,7 +35,7 @@
Like most of the Java community, I looked into https://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html[JAAS] to see if it could do what I wanted. After all, it was really the only security technology out there widely accessible to Java developers at the time. I did a *lot* of research, looking for ways that I might be able to coerce JAAS into doing what I wanted. Sometimes it came close. JAAS Authentication could meet my needs with a decent amount of effort, but JAAS Authorization didn't even come close.
-JAAS is tied too heavily tied to virtual machine-level concerns. As an application architect, I usually didn't care one bit about whether or not a *Class* could execute inside the virtual machine. What I really wanted to control is whether or not the *current user* could execute a given method, often based on the method's arguments. So, I hobbled a bit, creating some functionality to piggy-back JAAS and custom-coded the rest. The result was only usable on a few applications and wasn't nearly as robust as I wanted.
+JAAS is tied too heavily tied to virtual machine-level concerns. As an application architect, I usually didn't care one bit about whether a *Class* could execute inside the virtual machine. What I really wanted to control is whether the *current user* could execute a given method, often based on the method's arguments. So, I hobbled a bit, creating some functionality to piggyback JAAS and custom-coded the rest. The result was only usable on a few applications and wasn't nearly as robust as I wanted.
Then I came to work on a really great application that pushed the limits of application security. This application was written for government organizations and needed *extremely* powerful yet flexible security support. The client required the following:
