You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shiro.apache.org by bm...@apache.org on 2021/09/10 20:56:37 UTC
[shiro-site] branch jbake updated (b52106d -> 3478318)
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a change to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git.
from b52106d [JBake][Content] Converted five more pages.
new 3e8f5ea [JBake][Content] convert spring pages.
new be5d041 [JBake] move guice and introduction guides, move lend-a-hand template.
new 2e2d332 [JBake] convert pages web and web-features.
new 55035d3 Merge features and features-overview pages
new bfb3a14 Merge replace contribute.md with how-to-contribute.md
new 3478318 [JBake] convert features.md and how-to-contribute.md.
The 6 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.htaccess | 2 +
contribute.md | 18 -
features-overview.md | 35 -
features.md | 34 -
introduction.md | 52 --
jbake/.gitignore | 3 +
.../images => jbake/assets/img}/ShiroFeatures.png | Bin
jbake/content/features.adoc | 36 +
guice.md.vtl => jbake/content/guice.adoc | 133 +--
.../content/how-to-contribute.adoc | 148 ++--
jbake/content/introduction.adoc | 56 ++
jbake/content/spring-boot.adoc | 200 +++++
jbake/content/spring-framework.adoc | 270 ++++++
spring-xml.md => jbake/content/spring-xml.md | 46 +-
web-features.md => jbake/content/web-features.md | 15 +-
jbake/content/web.adoc | 910 ++++++++++++++++++++
jbake/jbake.properties | 3 +
jbake/templates/header.ftl | 2 +
jbake/templates/macros/dependencies.ftl | 101 +++
.../templates/macros/lend-a-hand.ftl | 12 +-
navigation.md | 2 +-
sitemap.xml | 6 -
spring-boot.md.vtl | 171 ----
spring-framework.md.vtl | 215 -----
templates/macros/dependencies.vtl | 24 -
web.md.vtl | 947 ---------------------
26 files changed, 1760 insertions(+), 1681 deletions(-)
delete mode 100644 contribute.md
delete mode 100644 features-overview.md
delete mode 100644 features.md
delete mode 100644 introduction.md
rename {assets/images => jbake/assets/img}/ShiroFeatures.png (100%)
create mode 100644 jbake/content/features.adoc
rename guice.md.vtl => jbake/content/guice.adoc (65%)
rename how-to-contribute.md => jbake/content/how-to-contribute.adoc (54%)
create mode 100644 jbake/content/introduction.adoc
create mode 100644 jbake/content/spring-boot.adoc
create mode 100644 jbake/content/spring-framework.adoc
rename spring-xml.md => jbake/content/spring-xml.md (92%)
rename web-features.md => jbake/content/web-features.md (89%)
create mode 100644 jbake/content/web.adoc
create mode 100644 jbake/templates/macros/dependencies.ftl
rename templates/macros/lend-a-hand.vtl => jbake/templates/macros/lend-a-hand.ftl (80%)
delete mode 100644 spring-boot.md.vtl
delete mode 100644 spring-framework.md.vtl
delete mode 100644 templates/macros/dependencies.vtl
delete mode 100644 web.md.vtl
[shiro-site] 04/06: Merge features and features-overview pages
Posted by bm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit 55035d37e4a429ee28f2bd0c4aa32c2f7e1f488f
Author: Brian Demers <bd...@apache.org>
AuthorDate: Fri Sep 10 10:25:01 2021 -0400
Merge features and features-overview pages
Added redirect and updated existing references
---
.htaccess | 1 +
features-overview.md | 35 -----------------------------------
features.md | 12 ++++++------
sitemap.xml | 3 ---
4 files changed, 7 insertions(+), 44 deletions(-)
diff --git a/.htaccess b/.htaccess
index 8e122db..39c4ce5 100644
--- a/.htaccess
+++ b/.htaccess
@@ -11,3 +11,4 @@ RedirectMatch ^/shiro-spring(.*) /static/current/shiro-spring/$1
RedirectMatch ^/shiro-guice(.*) /static/current/shiro-guice/$1
RedirectMatch ^/shiro-web(.*) /static/current/shiro-web/$1
RedirectMatch ^/spring.html /spring-framework.html
+RedirectMatch ^/features-overview.html /features.html
\ No newline at end of file
diff --git a/features-overview.md b/features-overview.md
deleted file mode 100644
index 2e91a22..0000000
--- a/features-overview.md
+++ /dev/null
@@ -1,35 +0,0 @@
-<a name="FeaturesOverview-ApacheShiroFeaturesOverview"></a>
-#Apache Shiro Features Overview
-
-Apache Shiro aims to be the most comprehensive, but also the easiest to use Java security framework available. Here are some of the frameworks finer points:
-
-* The easiest to understand Java Security API anywhere. Class and Interface names are intuitive and _make sense_. Anything is pluggable but good defaults exist for everything.
-
-* Support authentication ('logins') across one or more pluggable data sources (LDAP, JDBC, ActiveDirectory, etc).
-
-* Perform authorization ('access control') based on roles or fine-grained permissions, also using pluggable data sources.
-
-* First-class caching support for enhanced application performance.
-
-* Built-in POJO-based Enterprise Session Management. Use in both web and non-web environments or in any environment where Single Sign On (SSO) or clustered or distributed sessions are desired.
-
-* _Heterogeneous_ client session access. You are no longer forced to use only the `HttpSession` or Stateful Session Beans, which often unnecessarily tied applications to specific environments. Flash applets, C# applications, Java Web Start, and Web Applications, etc. can now all share session state regardless of deployment environment.
-
-* Simple Single Sign-On (SSO) support piggybacking the above Enterprise Session Management. If sessions are federated across multiple applications, the user's authentication state can be shared too. Log in once to any application and the others all recognize that log-in.
-
-* Secure data with the easiest possible Cryptography APIs available, giving you power and simplicity beyond what Java provides by default for ciphers and hashes.
-
-* An incredibly robust yet **_low-configuration_** web framework that can secure any url or resource, automatically handle logins and logouts, perform Remember Me services, and more.
-
-* Extremely low number of required dependencies. Standalone configuration requires only `slf4j-api.jar` and one of slf4j's binding .jars. Web configuration additionally requires `commons-beanutils-core.jar`. Feature-based dependencies (Ehcache caching, Quartz-based Session validation, Spring dependency injection, etc.) can be added when needed.
-
-<a name="FeaturesOverview-WantmoreinformationonwhatShirocando%3F"></a>
-##Want more information on what Shiro can do?
-
-Check out the specific features for each of Shiro's major components: [Authentications](authentication-features.html "Authentication Features"), [Authorization](authorization-features.html "Authorization Features"), [Session Management](session-management-features.html "Session Management Features"), and [Cryptography](cryptography-features.html "Cryptography Features").
-
-<a name="FeaturesOverview-GetStartedin10MinuteswithShiro"></a>
-##Get Started in 10 Minutes with Shiro
-
-Try out Shiro for yourself with our [10 Minute Tutorial](10-minute-tutorial.html "10 Minute Tutorial"). And if you have any questions about Shiro, please check out our [community forum](forums.html "Forums") or [user mailing list](mailing-lists.html "Mailing Lists") for answers from the community.
-<input type="hidden" id="ghEditPage" value="features-overview.md"></input>
diff --git a/features.md b/features.md
index 5a359a6..f6e7e69 100644
--- a/features.md
+++ b/features.md
@@ -2,9 +2,9 @@ title: Features-ApacheShiroFeaturesOverview
#Apache Shiro Features Overview
-Apache Shiro aims to be the most comprehensive, but also the easiest to use Java security framework available. Here are some of the frameworks finer points:
+Apache Shiro aims to be the most comprehensive, but also the easiest to use Java security framework available. Here are some of the frameworks finer points:
-* The easiest to understand Java Security API anywhere. Class and Interface names are intuitive and _make sense_. Anything is pluggable but good defaults exist for everything.
+* The easiest to understand Java Security API anywhere. Class and Interface names are intuitive and _make sense_. Anything is pluggable but good defaults exist for everything.
* Support [authentication](authentication-features.html) ('logins') across one or more pluggable data sources (LDAP, JDBC, ActiveDirectory, etc).
@@ -16,7 +16,7 @@ Apache Shiro aims to be the most comprehensive, but also the easiest to use Java
* _Heterogeneous_ client session access. You are no longer forced to use only the <tt>httpSession</tt> or Stateful Session Beans, which often unnecessarily tie applications to specific environments. Flash applets, C# applications, Java Web Start, and Web Applications, etc. can now all share session state regardless of deployment environment.
-* Simple Single Sign-On (SSO) support piggybacking the above Enterprise Session Management. If sessions are federated across multiple applications, the user's authentication state can be shared too. Log in once to any application and the others all recognize that log-in.
+* Simple Single Sign-On (SSO) support piggybacking the above Enterprise Session Management. If sessions are federated across multiple applications, the user's authentication state can be shared too. Log in once to any application and the others all recognize that log-in.
* Secure data with the easiest possible [Cryptography](cryptography-features.html) APIs available, giving you power and simplicity beyond what Java provides by default for ciphers and hashes.
@@ -24,11 +24,11 @@ Apache Shiro aims to be the most comprehensive, but also the easiest to use Java
* Extremely low number of required dependencies. Standalone configuration requires only <tt>slf4j-api.jar</tt> and one of slf4j's binding .jars. Web configuration additionally requires <tt>commons-beanutils-core.jar</tt>. Feature-based dependencies (Ehcache caching, Quartz-based Session validation, Spring dependency injection, etc.) can be added when needed.
-## Want more information on what Shiro can do?
+##Want more information on what Shiro can do?
-Check out the specific features for each of Shiro's major components: [Authentication](authentication-features.html), [Authorization](authorization-features.html), [Session Management](session-management-features.html), and [Cryptography](cryptography-features.html).
+Check out the specific features for each of Shiro's major components: [Authentication](authentication-features.html "Authentication Features"), [Authorization](authorization-features.html "Authorization Features"), [Session Management](session-management-features.html "Session Management Features"), and [Cryptography](cryptography-features.html "Cryptography Features").
##Get Started in 10 Minutes with Shiro
-Try out Shiro for yourself with our [10 Minute Tutorial](10-minute-tutorial.html). And if you have any questions about Shiro, please check out our [community forum](forums.html) or [user mailing list](mailing-lists.html) for answers from the community.
+Try out Shiro for yourself with our [10 Minute Tutorial](10-minute-tutorial.html "10 Minute Tutorial"). And if you have any questions about Shiro, please check out our [community forum](forums.html "Forums") or [user mailing list](mailing-lists.html "Mailing Lists") for answers from the community.
<input type="hidden" id="ghEditPage" value="features.md"></input>
diff --git a/sitemap.xml b/sitemap.xml
index 3b8643e..f8b1bfb 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -103,9 +103,6 @@
<loc>https://shiro.apache.org/events.html</loc>
</url>
<url>
- <loc>https://shiro.apache.org/features-overview.html</loc>
- </url>
- <url>
<loc>https://shiro.apache.org/features.html</loc>
</url>
<url>
[shiro-site] 03/06: [JBake] convert pages web and web-features.
Posted by bm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit 2e2d332500fc3a998719d0a202dff66201252f96
Author: Benjamin Marwell <bm...@apache.org>
AuthorDate: Fri Sep 10 06:23:01 2021 +0200
[JBake] convert pages web and web-features.
---
web-features.md => jbake/content/web-features.md | 15 +-
jbake/content/web.adoc | 910 ++++++++++++++++++++++
web.md.vtl | 947 -----------------------
3 files changed, 918 insertions(+), 954 deletions(-)
diff --git a/web-features.md b/jbake/content/web-features.md
similarity index 89%
rename from web-features.md
rename to jbake/content/web-features.md
index 1597034..150e500 100644
--- a/web-features.md
+++ b/jbake/content/web-features.md
@@ -1,12 +1,14 @@
-title: Apache Shiro for Web Applications
-
-# Apache Shiro for Web Applications
-
-
+title=Apache Shiro for Web Applications
+type=page
+tags=documentation, overview, web
+status=published
+~~~~~~
Although Apache Shiro is designed to be used to secure _any_ JVM-based application, it is most commonly used to secure a web application. It greatly simplifies how you secure web applications base on simple URL pattern matching and filter chain definitions. In addition to Shiro's API, Shiro's web support includes a rich JSP tag library to control page output.
+
-##Features
+
+## Features
* **Simple ShiroFilter web.xml definition**
You can enable Shiro for a web application with one simple filter definition in web.xml.
@@ -23,4 +25,3 @@ The JSP tags allow you to easily control page output based on the current user's
* **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.
-<input type="hidden" id="ghEditPage" value="web-features.md"></input>
diff --git a/jbake/content/web.adoc b/jbake/content/web.adoc
new file mode 100644
index 0000000..7c32590
--- /dev/null
+++ b/jbake/content/web.adoc
@@ -0,0 +1,910 @@
+= Apache Shiro Web Support
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, web
+:idprefix:
+:icons: font
+:toc:
+:toclevels: 5
+
+== Configuration
+
+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-INISections[INI Sections] section, but we'll cover some additional web-specific sections here.
+
+[INFO]
+.Using Spring?
+====
+Spring Framework users will not perform this setup. If you use Spring, you will want to read about link:spring-boot.html#web-applications[Spring-specific web configuration] instead.
+====
+
+=== `web.xml`
+
+==== Shiro 1.2 and later
+
+In Shiro 1.2 and later, standard web applications initialize Shiro by adding the following XML chunks to `web.xml`:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
+</listener>
+
+<!-- ... -->
+
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
+</filter>
+
+<filter-mapping>
+ <filter-name>ShiroFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ <dispatcher>REQUEST</dispatcher>
+ <dispatcher>FORWARD</dispatcher>
+ <dispatcher>INCLUDE</dispatcher>
+ <dispatcher>ERROR</dispatcher>
+ <dispatcher>ASYNC</dispatcher>
+</filter-mapping>
+
+----
+
+This assumes a Shiro INI link:configuration.html[Configuration] file is located at either of the following two locations, using whichever is found first:
+
+. `/WEB-INF/shiro.ini`
+. `shiro.ini` file at the root of the classpath.
+
+Here is what the above config does:
+
+* The `EnvironmentLoaderListener` initializes a Shiro `WebEnvironment` instance (which contains everything Shiro needs to operate, including the `SecurityManager`) and makes it accessible in the `ServletContext`. If you need to obtain this `WebEnvironment` instance at any time, you can call `WebUtils.getRequiredWebEnvironment(servletContext)`.
+
+* The `ShiroFilter` will use this `WebEnvironment` to perform all necessary security operations for any filtered request.
+
+* Finally, the `filter-mapping` definition ensures that all requests are filtered by the `ShiroFilter`, recommended for most web applications to ensure that any request can be secured.
+
+[TIP]
+.ShiroFilter filter-mapping
+====
+It is usually desirable to define the `ShiroFilter filter-mapping` before any other `filter-mapping` declarations to ensure that Shiro can function in those filters as well.
+====
+
+[INFO]
+.ShiroFilter default encoding
+====
+The shiro filter is a standard servlet filter, with a default encoding of ISO-8859-1 according to the <a href="https://javaee.github.io/servlet-spec/downloads/servlet-4.0/servlet-4_0_FINAL.pdf">servlet specification</a>. However, the client can choose to send authentication data with a different encoding using the <code>charset</code> attribute of the <code>Content-Type</code> header.
+====
+
+===== 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`:
+
+[source,xml]
+----
+<context-param>
+ <param-name>shiroEnvironmentClass</param-name>
+ <param-value>com.foo.bar.shiro.MyWebEnvironment</param-value>
+</context-param>
+----
+
+This allows you to customize how a configuration format is parsed and represented as a `WebEnvironment` instance. You could subclass the existing `IniWebEnvironment` for custom behavior, or support different configuration formats entirely. For example, if someone wanted to configure Shiro in XML instead of INI, they could create an XML-based implementation, e.g. `com.foo.bar.shiro.XmlWebEnvironment`.
+
+===== Custom Configuration Locations
+
+The `IniWebEnvironment` class expects to read and load INI configuration files. By default, this class will automatically look in the following two locations for the Shiro `.ini` configuration (in order):
+
+. `/WEB-INF/shiro.ini`
+. `classpath:shiro.ini`
+
+It will use whichever is found first.
+
+However, if you wish to place your config in another location, you may specify that location with another `context-param` in `web.xml`:
+
+[source,xml]
+----
+<context-param>
+ <param-name>shiroConfigLocations</param-name>
+ <param-value>YOUR_RESOURCE_LOCATION_HERE</param-value>
+</context-param>
+----
+
+By default, the `param-value` is expected to be resolvable by the rules defined by link:https://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getResource(java.lang.String)[`ServletContext.getResource`] method.
+For example, `/WEB-INF/some/path/shiro.ini`
+
+But you may also specify specific file-system, classpath or URL locations by using an appropriate resource prefix supported by Shiro's link:static/current/apidocs/org/apache/shiro/io/ResourceUtils.html[ResourceUtils class], for example:
+
+* `file:/home/foobar/myapp/shiro.ini`
+* `classpath:com/foo/bar/shiro.ini`
+* `url:http://confighost.mycompany.com/myapp/shiro.ini`
+
+==== Shiro 1.1 and earlier
+
+The simplest way to enable Shiro in a 1.1 or earlier web application is to define the IniShiroFilter and specify a `filter-mapping`:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class>
+</filter>
+
+<!-- ... -->
+
+<!-- Make sure any request you want accessible to Shiro is filtered. /* catches all -->
+<!-- requests. Usually this filter mapping is defined first (before all others) to -->
+<!-- ensure that Shiro works in subsequent filters in the filter chain: -->
+<filter-mapping>
+ <filter-name>ShiroFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ <dispatcher>REQUEST</dispatcher>
+ <dispatcher>FORWARD</dispatcher>
+ <dispatcher>INCLUDE</dispatcher>
+ <dispatcher>ERROR</dispatcher>
+</filter-mapping>
+----
+
+This definition expects your INI configuration to be in a shiro.ini file at the root of the classpath (e.g. `classpath:shiro.ini`).
+
+===== Custom Path
+
+If you do not want to place your INI config in `/WEB-INF/shiro.ini` or `classpath:shiro.ini`, you may specify a custom resource location as necessary. Add a `configPath init-param` and specify a resource location:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class>
+ <init-param>
+ <param-name>configPath</param-name>
+ <param-value>/WEB-INF/anotherFile.ini</param-value>
+ </init-param>
+</filter>
+
+...
+----
+
+Unqualified (schemeless or 'non-prefixed') `configPath` values are assumed to be `ServletContext` resource paths, resolvable via the rules defined by the
+link:https://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getResource(java.lang.String)[`ServletContext.getResource`] method.
+
+[WARNING]
+.ServletContext resource paths - Shiro 1.2+
+====
+ServletContext resource paths are available in Shiro 1.2 and later. In 1.1 and earlier, all `configPath` definitions must specify a `classpath:`, `file:` or `url:` prefix.
+====
+
+You may also specify other non-`ServletContext` resource locations by using `classpath:`, `url:`, or `file:` prefixes indicating classpath, url, or filesystem locations respectively. For example:
+
+[source,xml]
+----
+...
+<init-param>
+ <param-name>configPath</param-name>
+ <param-value>url:http://configHost/myApp/shiro.ini</param-value>
+</init-param>
+...
+----
+
+===== Inline Config
+
+Finally, it is also possible to embed your INI configuration inline in web.xml without using an INI file at all. You do this by using the `config init-param` instead of `configPath`:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class>
+ <init-param><param-name>config</param-name><param-value>
+
+ # INI Config Here
+
+ </param-value></init-param>
+</filter>
+...
+----
+
+Inline config is often fine for small or simple applications, but it is usually more convenient to externalize it in a dedicated shiro.ini file for the following reasons:
+
+* 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
+* 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.
+
+=== Web INI configuration
+
+In addition to the standard `[main]`, `[users]` and `[roles]` sections already described in the main link:configuration.html[Configuration] chapter, you can additionally specify a web-specific `[urls]` section in your `shiro.ini` file:
+
+[source,ini]
+----
+# [main], [users] and [roles] above here
+...
+[urls]
+...
+----
+
+The `[urls]` section allows you to do something that doesn't exist in any web framework that we've seen yet: the ability to define ad-hoc filter chains for any matching URL path in your application!
+
+This is _far_ more flexible, powerful and concise than how you define filter chains normally in `web.xml`: even if you never used any other feature that Shiro provided and used only this, it alone would make it worth using.
+
+==== `[urls]`
+
+The format of each line in the `urls` section is as follows:
+
+[source,ini]
+----
+_URL_Ant_Path_Expression_ = _Path_Specific_Filter_Chain_
+----
+
+For example:
+
+[source,ini]
+----
+...
+[urls]
+
+/index.html = anon
+/user/create = anon
+/user/** = authc
+/admin/** = authc, roles[administrator]
+/rest/** = authc, rest
+/remoting/rpc/** = authc, perms["remote:invoke"]
+----
+
+Next we'll cover exactly what these lines mean.
+
+===== URL Path Expressions
+
+The token on the left of the equals sign (=) is an http://ant.apache.org[Ant]-style path expression relative to your web application's context root.
+
+For example, let's say you had the following `[urls]` line:
+
+[source,ini]
+----
+/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.
+
+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.
+
+[CAUTION]
+.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:
+
+[source,ini]
+----
+/account/** = ssl, authc
+/account/signup = anon
+----
+
+Always remember to define your filter chains based on a _FIRST MATCH WINS_ policy!
+====
+
+===== Filter Chain Definitions
+
+The token on the right of the equals sign (=) is comma-delimited list of filters to execute for a request matching that path. It must match the following format:
+
+[source,ini]
+----
+filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN]
+----
+
+where:
+
+* _filterN_ is the name of a filter bean defined in the `[main]` section and
+* `[optional_configN]` is an optional bracketed string that has meaning for that particular filter for _that particular path_ (per-filter, _path-specific_ configuration!). If the filter does not need specific config for that URL path, you may discard the brackets so `filterN[]` just becomes `filterN`.
+
+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.
+
+[TIP]
+.Tip
+====
+Being able to react to path specific configuration, i.e. the `[optional_configN]` part of a filter token, is a unique feature available to Shiro filters.
+
+If you want to create your own `javax.servlet.Filter` implementation that can also do this, make sure your filter subclasses link:static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html[org.apache.shiro.web.filter.PathMatchingFilter].
+====
+
+===== Available Filters
+
+The 'pool' of filters available for use in filter chain definitions are defined in the `[main]` section.
+The name assigned to them in the main section is the name to use in the filter chain definitions. For example:
+
+[source,ini]
+----
+[main]
+...
+myFilter = com.company.web.some.FilterImplementation
+myFilter.property1 = value1
+...
+
+[urls]
+...
+/some/path/** = myFilter
+----
+
+== Default Filters
+
+When running a web-app, Shiro will create some useful default `Filter` instances and make them available in the `[main]` section automatically. You can configure them in `main` as you would any other bean and reference them in your chain definitions. For example:
+
+[source,ini]
+----
+[main]
+...
+# Notice how we didn't define the class for the FormAuthenticationFilter ('authc') - it is instantiated and available already:
+authc.loginUrl = /login.jsp
+...
+
+[urls]
+...
+# make sure the end-user is authenticated. If not, redirect to the 'authc.loginUrl' above,
+# and after successful authentication, redirect them back to the original account page they
+# were trying to view:
+/account/** = authc
+...
+----
+
+The default Filter instances available automatically are defined by the link:static/current/apidocs/org/apache/shiro/web/filter/mgt/DefaultFilter.html[DefaultFilter enum] and the enum's `name` field is the name available for configuration. They are:
+
+|===
+|Filter Name |Class
+
+|anon |link:static/current/apidocs/org/apache/shiro/web/filter/authc/AnonymousFilter.html[org.apache.shiro.web.filter.authc.AnonymousFilter]
+|authc |link:static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html[org.apache.shiro.web.filter.authc.FormAuthenticationFilter]
+|authcBasic |link:static/current/apidocs/org/apache/shiro/web/filter/authc/BasicHttpAuthenticationFilter.html[org.apache.shiro.web.filter.authc.BasicHttpAuthenticationFilter]
+|authcBearer |link:static/current/apidocs/org/apache/shiro/web/filter/authc/BearerHttpAuthenticationFilter.html[org.apache.shiro.web.filter.authc.BearerHttpAuthenticationFilter]
+|invalidRequest |link:static/current/apidocs/org/apache/shiro/web/filter/InvalidRequestFilter.html[org.apache.shiro.web.filter.InvalidRequestFilter]
+|logout |link:static/current/apidocs/org/apache/shiro/web/filter/authc/LogoutFilter.html[org.apache.shiro.web.filter.authc.LogoutFilter]
+|noSessionCreation |link:static/current/apidocs/org/apache/shiro/web/filter/session/NoSessionCreationFilter.html[org.apache.shiro.web.filter.session.NoSessionCreationFilter]
+|perms |link:static/current/apidocs/org/apache/shiro/web/filter/authz/PermissionsAuthorizationFilter.html[org.apache.shiro.web.filter.authz.PermissionsAuthorizationFilter]
+|port |link:static/current/apidocs/org/apache/shiro/web/filter/authz/PortFilter.html[org.apache.shiro.web.filter.authz.PortFilter]
+|rest |link:static/current/apidocs/org/apache/shiro/web/filter/authz/HttpMethodPermissionFilter.html[org.apache.shiro.web.filter.authz.HttpMethodPermissionFilter]
+|roles |link:static/current/apidocs/org/apache/shiro/web/filter/authz/RolesAuthorizationFilter.html[org.apache.shiro.web.filter.authz.RolesAuthorizationFilter]
+|ssl |link:static/current/apidocs/org/apache/shiro/web/filter/authz/SslFilter.html[org.apache.shiro.web.filter.authz.SslFilter]
+|user |link:static/current/apidocs/org/apache/shiro/web/filter/authc/UserFilter.html[org.apache.shiro.web.filter.authc.UserFilter]
+|===
+
+== 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.
+
+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.
+
+Shiro accomplishes this via its link:static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html[OncePerRequestFilter] abstract parent class. All of Shiro's out-of-the-box Filter implementations subclass this one and therefore are able to be enabled or disabled without removing them from the filter chain. You can subclass this class for your own filter implementations if you need this functionality as well*.
+
+*https://issues.apache.org/jira/browse/SHIRO-224[SHIRO-224] will hopefully enable this feature for any filter, not just those subclassing `OncePerRequestFilter`. If this is important to you, please vote for the issue.
+
+=== General Enabling/Disabling
+
+The link:static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html[OncePerRequestFilter] (and all of its subclasses) supports enabling/disabling across all requests as well as on a per-request basis.
+
+General enabling or disabling of a filter for all requests is done by setting its `enabled` property to true or false. The default setting is `true` since most filters inherently need to execute if they are configured in a chain.
+
+For example, in shiro.ini:
+
+[source,ini]
+----
+[main]
+...
+# configure Shiro's default 'ssl' filter to be disabled while testing:
+ssl.enabled = false
+
+[urls]
+...
+/some/path = ssl, authc
+/another/path = ssl, roles[admin]
+...
+----
+
+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.
+
+=== Request-specific Enabling/Disabling
+
+`OncePerRequestFilter` actually determines if the filter is enabled or disabled based on its `isEnabled(request, response)` method.
+
+This method defaults to returning the value of the `enabled` property, which is used for generally enabling/disabling all requests as mentioned above. If you wanted to enable or disable a filter based on _request specific_ criteria, you can override the `OncePerRequestFilter` `isEnabled(request,response)` method to perform more specific checks.
+
+=== Path-specific Enabling/Disabling
+
+Shiro's link:static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html[PathMatchingFilter] (a subclass of `OncePerRequestFilter` has the ability to react to configuration based on a _specific path_ being filtered. This means you can enable or disable a filter based on the path and the path-specific configuration in addition to the incoming request and response.
+
+If you need to be able to react to the matching path and the path-specific configuration to determine if a filter is enabled or disabled, instead of overriding `OncePerRequestFilter` `isEnabled(request,response)` method, you would override the `PathMatchingFilter` `isEnabled(request,response,path,pathConfig)` method instead.
+
+=== Global Filters
+
+Starting with Shiro 1.6 the ability to define global filters has been added. Adding "global filters" will add additional filters to ALL routes, this includes previously configured filter chains as well as unconfigured paths.
+
+By default, the global filters contains the `invalidRequest` filter. This filter blocks known malicious attacks, see below for configuration details.
+
+Global filters can be customized or disabled, for example
+
+[source,ini]
+----
+[main]
+...
+# disable Global Filters
+filterChainResolver.globalFilters = null
+----
+
+Define the list of global filters:
+
+[source,ini]
+----
+[main]
+...
+filterChainResolver.globalFilters = invalidRequest, port
+----
+
+The `invalidRequest` filter blocks requests with non-ascii characters, semicolons, and backslashes, each of these can be disabled independently to allow for backward compatibility.
+
+[source,ini]
+----
+[main]
+...
+invalidRequest.blockBackslash = true
+invalidRequest.blockSemicolon = true
+invalidRequest.blockNonAscii = true
+...
+----
+
+[NOTE]
+====
+If you 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.
+====
+
+
+=== HTTP Strict Transport Security (HSTS)
+
+The link:static/current/apidocs/org/apache/shiro/web/filter/authz/SslFilter.html[SslFilter] (and all of its subclasses) supports enabling/disabling HTTP Strict Transport Security (HSTS).
+
+For example, in shiro.ini:
+
+[source,ini]
+----
+[main]
+...
+# configure Shiro's default 'ssl' filter to enabled HSTS:
+ssl.enabled = true
+ssl.hsts.enabled = true
+ssl.hsts.includeSubDomains = true
+
+[urls]
+...
+/some/path = ssl, authc
+/another/path = ssl, roles[admin]
+...
+----
+
+== Session Management
+
+=== Servlet Container Sessions
+
+In web environments, Shiro's default session manager link:static/current/apidocs/org/apache/shiro/session/mgt/SessionManager.html[`SessionManager`] implementation is the link:static/current/apidocs/org/apache/shiro/web/session/mgt/ServletContainerSessionManager.html[`ServletContainerSessionManager`].
+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 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.
+
+==== Servlet Container Session Timeout
+
+If using the default servlet container support, you configure session timeout as expected in your web application's `web.xml` file. For example:
+
+[source,xml]
+----
+<session-config>
+ <!-- web.xml expects the session timeout in minutes: -->
+ <session-timeout>30</session-timeout>
+</session-config>
+----
+
+=== Native Sessions
+
+If you want your session configuration settings and clustering to be portable across servlet containers (e.g. Jetty in testing, but Tomcat or JBoss in production), or you want to control specific session/clustering features, you can enable Shiro's native session management.
+
+The word 'Native' here means that Shiro's own enterprise session management implementation will be used to support all `Subject` and `HttpServletRequest` sessions and bypass the servlet container completely. But rest assured - Shiro implements the relevant parts of the Servlet specification directly so any existing web/http related code works as expected and never needs to 'know' that Shiro is transparently managing sessions.
+
+==== `DefaultWebSessionManager`
+
+To enable native session management for your web application, you will need to configure a native web-capable session manager to override the default servlet container-based one. You can do that by configuring an instance of link:static/current/apidocs/org/apache/shiro/web/session/mgt/DefaultWebSessionManager.html[`DefaultWebSessionManager`] on Shiro's `SecurityManager`. For example, in `shiro.ini`:
+
+*shiro.ini native web session management*
+
+[source,ini]
+----
+[main]
+...
+sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
+# configure properties (like session timeout) here if desired
+
+# Use the configured native session manager:
+securityManager.sessionManager = $sessionManager
+----
+
+Once declared, you can configure the `DefaultWebSessionManager` instance with native session options like session timeout and clustering configuration as described in the link:session-management.html[Session Management] section.
+
+===== Native Session Timeout
+
+After configuring the `DefaultWebSessionManager` instance, session timeout is configured as described in link:session-management.html#[[#]]#SessionManagement-sessionTimeout[Session Management: Session Timeout]
+
+===== Session Cookie
+
+The `DefaultWebSessionManager` supports two web-specific configuration properties:
+
+* `sessionIdCookieEnabled` (a boolean)
+* `sessionIdCookie`, a link:static/current/apidocs/org/apache/shiro/web/servlet/Cookie.html[Cookie] instance.
+
+[INFO]
+.Cookie as a template
+====
+The `sessionIdCookie` property is essentially a template - you configure the `Cookie` instance properties, and this template will be used to set the actual HTTP `Cookie` header at runtime with an appropriate session ID value.
+====
+
+====== 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.
+
+For example, you could set the Cookie domain:
+
+[source,ini]
+----
+[main]
+...
+securityManager.sessionManager.sessionIdCookie.domain = foo.com
+----
+
+See the link:static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html[SimpleCookie JavaDoc] for additional properties.
+
+The cookie's default name is `JSESSIONID` in accordance with the servlet specification. Additionally, Shiro's cookie supports the https://en.wikipedia.org/wiki/HTTP_cookie#HttpOnly_cookie[`HttpOnly`] and https://en.wikipedia.org/wiki/HTTP_cookie#Same-site_cookie[`SameSite`] flags. The `sessionIdCookie` sets `HttpOnly` to `true` and `SameSite` to `LAX` by default for extra security.
+
+[NOTE]
+====
+Shiro's `Cookie` concept supports the `HttpOnly` flag even in Servlet 2.4 and 2.5 environments (whereas the Servlet API only supports it natively in 2.6 or later).
+====
+
+====== Disabling the Session Cookie
+
+If you do not want session cookies to be used, you can disable their use by configuring the `sessionIdCookieEnabled` property to false. For example:
+
+*Disabling native session cookies*
+
+[source,ini]
+----
+[main]
+...
+securityManager.sessionManager.sessionIdCookieEnabled = false
+----
+
+== Remember Me Services
+
+Shiro will perform 'rememberMe' services if the `AuthenticationToken` implements the link:static/current/apidocs/org/apache/shiro/authc/RememberMeAuthenticationToken.html[`org.apache.shiro.authc.RememberMeAuthenticationToken`] interface. This interface specifies a method:
+
+[source,java]
+----
+boolean isRememberMe();
+----
+
+If this method returns `true`, Shiro will remember the end-user's identity across sessions.
+
+[TIP]
+.UsernamePasswordToken and RememberMe
+====
+The frequently-used `UsernamePasswordToken` already implements the `RememberMeAuthenticationToken` interface and supports rememberMe logins.
+====
+
+
+=== Programmatic Support
+
+To use rememberMe programmatically, you can set the value to `true` on a class that supports this configuration. For example, using the standard `UsernamePasswordToken`:
+
+[source,java]
+----
+UsernamePasswordToken token = new UsernamePasswordToken(username, password);
+
+token.setRememberMe(true);
+
+SecurityUtils.getSubject().login(token);
+...
+----
+
+=== Form-based Login
+
+For web applications, the `authc` filter is by default a link:static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html[`FormAuthenticationFilter`]. This supports reading the 'rememberMe' boolean as a form/request parameter. By default, it expects the request param to be named `rememberMe`. Here is an example shiro.ini config supporting this:
+
+[source,ini]
+----
+[main]
+authc.loginUrl = /login.jsp
+
+[urls]
+
+# your login form page here:
+login.jsp = authc
+----
+
+And in your web form, have a checkbox named 'rememberMe':
+
+[source,html]
+----
+<form ...>
+
+ Username: <input type="text" name="username"/> <br/>
+ Password: <input type="password" name="password"/>
+ ...
+ <input type="checkbox" name="rememberMe" value="true"/>Remember Me?
+ ...
+</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`:
+
+[source,ini]
+----
+[main]
+...
+authc.loginUrl = /whatever.jsp
+authc.usernameParam = somethingOtherThanUsername
+authc.passwordParam = somethingOtherThanPassword
+authc.rememberMeParam = somethingOtherThanRememberMe
+...
+----
+
+=== Cookie configuration
+
+You can configure how the `rememberMe` cookie functions by setting the default {{RememberMeManager}}s various cookie properties. For example, in shiro.ini:
+
+[source,ini]
+----
+[main]
+...
+
+securityManager.rememberMeManager.cookie.name = foo
+securityManager.rememberMeManager.cookie.maxAge = blah
+...
+----
+
+See the link:static/current/apidocs/org/apache/shiro/web/mgt/CookieRememberMeManager.html[`CookieRememberMeManager`] and the supporting link:static/current/apidocs/src-html/org/apache/shiro/web/servlet/SimpleCookie.html[`SimpleCookie`] JavaDoc for configuration properties.
+
+=== Custom `RememberMeManager`
+
+It should be noted that if the default cookie-based `RememberMeManager` implementation does not meet your needs, you can plug in any you like in to the `securityManager` like you would configure any other object reference:
+
+[source,ini]
+----
+[main]
+...
+rememberMeManager = com.my.impl.RememberMeManager
+securityManager.rememberMeManager = $rememberMeManager
+----
+
+== JSP / GSP Tag Library
+
+Apache Shiro provides a `Subject`-aware JSP/GSP tag library that allows you to control your JSP, JSTL or GSP page output based on the current Subject's state. This is quite useful for personalizing views based on the identity and authorization state of the current user viewing the web page.
+
+===Tag Library Configuration
+
+The Tag Library Descriptor (TLD) file is bundled in `shiro-web.jar` in the `META-INF/shiro.tld` file. To use any of the tags, add the following line to the top of your JSP page (or wherever you define page directives):
+
+[source,html]
+----
+<%@ taglib prefix="shiro" uri="http://shiro.apache.org/tags" %>
+----
+
+We've used the `shiro` prefix to indicate the shiro tag library namespace, but you can assign whatever name you like.
+
+Now we'll cover each tag and show how it might be used to render a page.
+
+=== 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.
+
+Example:
+
+[source,html]
+----
+<shiro:guest>
+ Hi there! Please <a href="login.jsp">Login</a> or <a href="signup.jsp">Signup</a> today!
+</shiro:guest>
+----
+
+The `guest` tag is the logical opposite of the <<Web-usertag,`user`>> tag.
+
+=== The `user` tag
+
+The `user` tag will display its wrapped content only if the current `Subject` is considered a 'user'. A 'user' in this context is defined as a `Subject` with a known identity, either from a successful authentication or from 'RememberMe' services. Note that this tag is semantically different from the <<Web-authenticatedtag,authenticated>> tag, which is more restrictive than this tag.
+
+Example:
+
+[source,html]
+----
+<shiro:user>
+ Welcome back John! Not John? Click <a href="login.jsp">here<a> to login.
+</shiro:user>
+----
+
+The `user` tag is the logical opposite of the <<Web-guesttag,`guest`>> tag.
+
+=== The `authenticated` tag
+
+Displays body content only if the current user has successfully authenticated _during their current session_. It is more restrictive than the 'user' tag. It is logically opposite to the 'notAuthenticated' tag.
+
+The `authenticated` tag will display its wrapped content only if the current `Subject` has successfully authenticated _during their current session_. It is a more restrictive tag than the <<Web-usertag,user>>, which is used to guarantee identity in sensitive workflows.
+
+Example:
+
+[source,html]
+----
+<shiro:authenticated>
+ <a href="updateAccount.jsp">Update your contact information</a>.
+</shiro:authenticated>
+----
+
+The `authenticated` tag is the logical opposite of the <<Web-notauthenticatedtag,`notAuthenticated`>> tag.
+
+=== The `notAuthenticated` tag
+
+The `notAuthenticated` tag will display its wrapped content if the current `Subject` has *NOT* yet successfully authenticated during the current session.
+
+Example:
+
+[source,html]
+----
+<shiro:notAuthenticated>
+ Please <a href="login.jsp">login</a> in order to update your credit card information.
+</shiro:notAuthenticated>
+----
+
+The `notAuthenticated` tag is the logical opposite of the <<Web-authenticatedtag,`authenticated`>> tag.
+
+=== The `principal` tag
+
+The `principal` tag will output the Subject's link:static/current/apidocs/org/apache/shiro/subject/Subject.html#[[#]]#getPrincipal--[`principal`] (identifying attribute) or a property of that principal.
+
+Without any tag attributes, the tag will render the `toString()` value of the principal. For example (assuming the principal is a String username):
+
+[source,html]
+----
+Hello, <shiro:principal/>, how are you today?
+----
+
+This is (mostly) equivalent to the following:
+
+[source,jsp]
+----
+Hello, <%= SecurityUtils.getSubject().getPrincipal().toString() %>, how are you today?
+----
+
+==== Typed principal
+
+The `principal` tag assumes by default that the principal to print is the `subject.getPrincipal()` value. But if you wanted to print a value that is _not_ the primary principal, but another in the Subject's {link:static/current/apidocs/org/apache/shiro/subject/Subject.html#[[#]]#getPrincipals--[principal collection], you can acquire that principal by type and print that value instead.
+
+For example, printing the Subject's user ID (and not the username), assuming the ID was in the principal collection:
+
+[source,html]
+----
+User ID: <principal type="java.lang.Integer"/>
+----
+
+This is (mostly) equivalent to the following:
+
+[source,jsp]
+----
+User ID: <%= SecurityUtils.getSubject().getPrincipals().oneByType(Integer.class).toString() %>
+----
+
+==== Principal property
+
+But what if the principal (either the default primary principal or 'typed' principal above) is a complex object and not a simple string, and you wanted to reference a property on that principal? You can use the `property` attribute to indicate the name of the property to read (must be accessible via a JavaBeans-compatible getter method). For example (assuming the primary principal is a User object):
+
+[source,html]
+----
+Hello, <shiro:principal property="firstName"/>, how are you today?
+----
+
+This is (mostly) equivalent to the following:
+
+[source,jsp]
+----
+Hello, <%= SecurityUtils.getSubject().getPrincipal().getFirstName().toString() %>, how are you today?
+----
+
+Or, combined with the type attribute:
+
+[source,html]
+----
+Hello, <shiro:principal type="com.foo.User" property="firstName"/>, how are you today?
+----
+
+this is largely equivalent to the following:
+
+[source,jsp]
+----
+Hello, <%= SecurityUtils.getSubject().getPrincipals().oneByType(com.foo.User.class).getFirstName().toString() %>, how are you today?
+----
+
+=== The `hasRole` tag
+
+The `hasRole` tag will display its wrapped content only if the current `Subject` is assigned the specified role.
+
+For example:
+
+[source,html]
+----
+<shiro:hasRole name="administrator">
+ <a href="admin.jsp">Administer the system</a>
+</shiro:hasRole>
+----
+
+The `hasRole` tag is the logical opposite of the <<Web-lacksroletag,lacksRole>> tag.
+
+=== The `lacksRole` tag
+
+The `lacksRole` tag will display its wrapped content only if the current `Subject` *is NOT* assigned the specified role.
+
+For example:
+
+[source,html]
+----
+<shiro:lacksRole name="administrator">
+ Sorry, you are not allowed to administer the system.
+</shiro:lacksRole>
+----
+
+The `lacksRole` tag is the logical opposite of the <<Web-hasroletag,hasRole>> tag.
+
+=== The `hasAnyRole` tag
+
+The `hasAnyRole` tag will display its wrapped content if the current `Subject` is assigned _any_ of the specified roles from a comma-delimited list of role names.
+
+For example:
+
+[source,html]
+----
+<shiro:hasAnyRoles name="developer, project manager, administrator">
+ You are either a developer, project manager, or administrator.
+</shiro:hasAnyRoles>
+----
+
+The `hasAnyRole` tag does not currently have a logically opposite tag.
+
+=== The `hasPermission` tag
+
+The `hasPermission` tag will display its wrapped content only if the current `Subject` 'has' (implies) the specified permission. That is, the user has the specified ability.
+
+For example:
+
+[source,html]
+----
+<shiro:hasPermission name="user:create">
+ <a href="createUser.jsp">Create a new User</a>
+</shiro:hasPermission>
+----
+
+The `hasPermission` tag is the logical opposite of the <<Web-lackspermissiontag,lacksPermission>> tag.
+
+=== The `lacksPermission` tag
+
+The `lacksPermission` tag will display its wrapped content only if the current `Subject` *DOES NOT* have (imply) the specified permission. That is, the user *DOES NOT* have the specified ability.
+
+For example:
+
+[source,html]
+----
+<shiro:lacksPermission name="user:delete">
+ Sorry, you are not allowed to delete user accounts.
+</shiro:lacksPermission>
+----
+
+The `lacksPermission` tag is the logical opposite of the <<Web-haspermissiontag,hasPermission>> tag.
+
+++++
+<@lendahand />
+++++
diff --git a/web.md.vtl b/web.md.vtl
deleted file mode 100644
index 2933dcd..0000000
--- a/web.md.vtl
+++ /dev/null
@@ -1,947 +0,0 @@
-#mdStyle()
-
-<a name="Web-ApacheShiroWebSupport"></a>
-Apache Shiro Web Support
-========================
-
-* [Configuration](#Web-Configuration)
-
- * [`web.xml`](#Web-%7B%7Bweb.xml%7D%7D)
-
- * [Shiro 1.2 and later](#Web-Shiro1.2andlater)
-
- * [Custom `WebEnvironment` Class](#Web-Custom%7B%7BWebEnvironment%7D%7DClass)
- * [Custom Configuration Locations](#Web-CustomConfigurationLocations)
-
- * [Shiro 1.1 and earlier](#Web-Shiro1.1andearlier)
-
- * [Custom Path](#Web-CustomPath)
- * [Inline Config](#Web-InlineConfig)
-
- * [Web INI configuration](#Web-WebINIconfiguration)
-
- * [`[urls]`](#Web-%7B%7B%5Curls%5C%7D%7D)
-
- * [URL Path Expressions](#Web-URLPathExpressions)
- * [Filter Chain Definitions](#Web-FilterChainDefinitions)
-
- * [Available Filters](#Web-AvailableFilters)
-
-* [Default Filters](#Web-DefaultFilters)
-* [Enabling and Disabling Filters](#Web-EnablingandDisablingFilters)
-
- * [General Enabling/Disabling](#Web-GeneralEnabling%2FDisabling)
- * [Request-specific Enabling/Disabling](#Web-RequestspecificEnabling%2FDisabling)
- * [Path-specific Enabling/Disabling](#Web-PathspecificEnabling%2FDisabling)
- * [Global Filters](#Web-globalFilters)
- * [HTTP Strict Transport Security (HSTS)](#Web-HSTS)
-
-* [Session Management](#Web-SessionManagement)
-
- * [Servlet Container Sessions](#Web-ServletContainerSessions)
-
- * [Servlet Container Session Timeout](#Web-ServletContainerSessionTimeout)
-
- * [Native Sessions](#Web-NativeSessions)
-
- * [`DefaultWebSessionManager`](#Web-%7B%7BDefaultWebSessionManager%7D%7D)
-
- * [Native Session Timeout](#Web-NativeSessionTimeout)
- * [Session Cookie](#Web-SessionCookie)
-
- * [Session Cookie Configuration](#Web-SessionCookieConfiguration)
- * [Disabling the Session Cookie](#Web-DisablingtheSessionCookie)
-
-* [Remember Me Services](#Web-RememberMeServices)
-
- * [Programmatic Support](#Web-ProgrammaticSupport)
- * [Form-based Login](#Web-FormbasedLogin)
- * [Cookie configuration](#Web-Cookieconfiguration)
- * [Custom `RememberMeManager`](#Web-Custom%7B%7BRememberMeManager%7D%7D)
-
-* [JSP / GSP Tag Library](#Web-JSP%2FGSPTagLibrary)
-
- * [Tag Library Configuration](#Web-TagLibraryConfiguration)
- * [The `guest` tag](#Web-The%7B%7Bguest%7D%7Dtag)
- * [The `user` tag](#Web-The%7B%7Buser%7D%7Dtag)
- * [The `authenticated` tag](#Web-The%7B%7Bauthenticated%7D%7Dtag)
- * [The `notAuthenticated` tag](#Web-The%7B%7BnotAuthenticated%7D%7Dtag)
- * [The `principal` tag](#Web-The%7B%7Bprincipal%7D%7Dtag)
-
- * [Typed principal](#Web-Typedprincipal)
- * [Principal property](#Web-Principalproperty)
-
- * [The `hasRole` tag](#Web-The%7B%7BhasRole%7D%7Dtag)
- * [The `lacksRole` tag](#Web-The%7B%7BlacksRole%7D%7Dtag)
- * [The `hasAnyRole` tag](#Web-The%7B%7BhasAnyRole%7D%7Dtag)
- * [The `hasPermission` tag](#Web-The%7B%7BhasPermission%7D%7Dtag)
- * [The `lacksPermission` tag](#Web-The%7B%7BlacksPermission%7D%7Dtag)
-
-
-<a name="Web-configuration"></a>
-<a name="Web-Configuration"></a>
-Configuration
--------------
-
-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 [INI Sections](configuration.html#[[#]]#Configuration-INISections) section, but we'll cover some additional web-specific sections here.
-
-#info('Using Spring?', 'Spring Framework users will not perform this setup. If you use Spring, you will want to read about <a href="spring-boot.html#web-applications">Spring-specific web configuration</a> instead.')
-
-<a name="Web-%7B%7Bweb.xml%7D%7D"></a>
-#[[###`web.xml`]]#
-
-<a name="Web-Shiro1.2andlater"></a>
-#[[####Shiro 1.2 and later]]#
-
-In Shiro 1.2 and later, standard web applications initialize Shiro by adding the following XML chunks to `web.xml`:
-
-``` xml
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-
-...
-
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
- <dispatcher>REQUEST</dispatcher>
- <dispatcher>FORWARD</dispatcher>
- <dispatcher>INCLUDE</dispatcher>
- <dispatcher>ERROR</dispatcher>
-</filter-mapping>
-```
-
-This assumes a Shiro INI [Configuration](configuration.html "Configuration") file is located at either of the following two locations, using whichever is found first:
-
-1. `/WEB-INF/shiro.ini`
-2. `shiro.ini` file at the root of the classpath.
-
-Here is what the above config does:
-
-* The `EnvironmentLoaderListener` initializes a Shiro `WebEnvironment` instance (which contains everything Shiro needs to operate, including the `SecurityManager`) and makes it accessible in the `ServletContext`. If you need to obtain this `WebEnvironment` instance at any time, you can call `WebUtils.getRequiredWebEnvironment(servletContext)`.
-
-* The `ShiroFilter` will use this `WebEnvironment` to perform all necessary security operations for any filtered request.
-
-* Finally, the `filter-mapping` definition ensures that all requests are filtered by the `ShiroFilter`, recommended for most web applications to ensure that any request can be secured.
-
-#tip('ShiroFilter filter-mapping', 'It is usually desirable to define the `ShiroFilter filter-mapping` before any other `filter-mapping` declarations to ensure that Shiro can function in those filters as well.')
-
-#tip('ShiroFilter default encoding', 'The shiro filter is a standard servlet filter, with a default encoding of ISO-8859-1 according to the <a href="https://javaee.github.io/servlet-spec/downloads/servlet-4.0/servlet-4_0_FINAL.pdf">servlet specification</a>. However, the client can choose to send authentication data with a different encoding using the <code>charset</code> attribute of the <code>Content-Type</code> header.')
-
-<a name="Web-Custom%7B%7BWebEnvironment%7D%7DClass"></a>
-#[[#####Custom `WebEnvironment` Class]]#
-
-By default the `EnvironmentLoaderListener` will create an `IniWebEnvironment` instance, which assumes Shiro's INI-based [Configuration](configuration.html "Configuration"). If you like, you may specify a custom `WebEnvironment` instance instead by specifying a `ServletContext` `context-param` in `web.xml`:
-
-``` xml
-<context-param>
- <param-name>shiroEnvironmentClass</param-name>
- <param-value>com.foo.bar.shiro.MyWebEnvironment</param-value>
-</context-param>
-```
-
-This allows you to customize how a configuration format is parsed and represented as a `WebEnvironment` instance. You could subclass the existing `IniWebEnvironment` for custom behavior, or support different configuration formats entirely. For example, if someone wanted to configure Shiro in XML instead of INI, they could create an XML-based implementation, e.g. `com.foo.bar.shiro.XmlWebEnvironment`.
-
-<a name="Web-CustomConfigurationLocations"></a>
-#[[#####Custom Configuration Locations]]#
-
-The `IniWebEnvironment` class expects to read and load INI configuration files. By default, this class will automatically look in the following two locations for the Shiro `.ini` configuration (in order):
-
-1. `/WEB-INF/shiro.ini`
-2. `classpath:shiro.ini`
-
-It will use whichever is found first.
-
-However, if you wish to place your config in another location, you may specify that location with another `context-param` in `web.xml`:
-
-``` xml
-<context-param>
- <param-name>shiroConfigLocations</param-name>
- <param-value>YOUR_RESOURCE_LOCATION_HERE</param-value>
-</context-param>
-```
-
-By default, the `param-value` is expected to be resolvable by the rules defined by `ServletContext.`[`getResource`](http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#[[#]]#getResource-java.lang.String-) method. For example, `/WEB-INF/some/path/shiro.ini`
-
-But you may also specify specific file-system, classpath or URL locations by using an appropriate resource prefix supported by Shiro's [ResourceUtils class](static/current/apidocs/org/apache/shiro/io/ResourceUtils.html), for example:
-
-* `file:/home/foobar/myapp/shiro.ini`
-* `classpath:com/foo/bar/shiro.ini`
-* `url:http://confighost.mycompany.com/myapp/shiro.ini`
-
-<a name="Web-Shiro1.1andearlier"></a>
-#[[####Shiro 1.1 and earlier]]#
-
-The simplest way to enable Shiro in a 1.1 or earlier web application is to define the IniShiroFilter and specify a `filter-mapping`:
-
-``` xml
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class>
-</filter>
-
-...
-
-<!-- Make sure any request you want accessible to Shiro is filtered. /* catches all -->
-<!-- requests. Usually this filter mapping is defined first (before all others) to -->
-<!-- ensure that Shiro works in subsequent filters in the filter chain: -->
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
- <dispatcher>REQUEST</dispatcher>
- <dispatcher>FORWARD</dispatcher>
- <dispatcher>INCLUDE</dispatcher>
- <dispatcher>ERROR</dispatcher>
-</filter-mapping>
-```
-
-This definition expects your INI configuration to be in a shiro.ini file at the root of the classpath (e.g. `classpath:shiro.ini`).
-
-<a name="Web-CustomPath"></a>
-#[[#####Custom Path]]#
-
-If you do not want to place your INI config in `/WEB-INF/shiro.ini` or `classpath:shiro.ini`, you may specify a custom resource location as necessary. Add a `configPath init-param` and specify a resource location:
-
-``` xml
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class>
- <init-param>
- <param-name>configPath</param-name>
- <param-value>/WEB-INF/anotherFile.ini</param-value>
- </init-param>
-</filter>
-
-...
-```
-
-Unqualified (schemeless or 'non-prefixed') `configPath` values are assumed to be `ServletContext` resource paths, resolvable via the rules defined by the
-`ServletContext.`[`getResource`](http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#[[#]]#getResource-java.lang.String-) method.
-
-#warning('ServletContext resource paths - Shiro 1.2+', 'ServletContext resource paths are available in Shiro 1.2 and later. In 1.1 and earlier, all <code>configPath</code> definitions must specify a <code>classpath:</code>, <code>file:</code> or <code>url:</code> prefix.')
-
-You may also specify other non-`ServletContext` resource locations by using `classpath:`, `url:`, or `file:` prefixes indicating classpath, url, or filesystem locations respectively. For example:
-
-``` xml
-...
-<init-param>
- <param-name>configPath</param-name>
- <param-value>url:http://configHost/myApp/shiro.ini</param-value>
-</init-param>
-...
-```
-
-<a name="Web-InlineConfig"></a>
-#[[#####Inline Config]]#
-
-Finally, it is also possible to embed your INI configuration inline in web.xml without using an INI file at all. You do this by using the `config init-param` instead of `configPath`:
-
-``` xml
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class>
- <init-param><param-name>config</param-name><param-value>
-
- # INI Config Here
-
- </param-value></init-param>
-</filter>
-...
-```
-
-Inline config is often fine for small or simple applications, but it is usually more convenient to externalize it in a dedicated shiro.ini file for the following reasons:
-
-* 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
-* 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.
-
-<a name="Web-webini"></a>
-<a name="Web-WebINIconfiguration"></a>
-#[[###Web INI configuration]]#
-
-In addition to the standard `[main]`, `[users]` and `[roles]` sections already described in the main [Configuration](configuration.html "Configuration") chapter, you can additionally specify a web-specific `[urls]` section in your `shiro.ini` file:
-
-``` ini
-# [main], [users] and [roles] above here
-...
-[urls]
-...
-```
-
-The `[urls]` section allows you to do something that doesn't exist in any web framework that we've seen yet: the ability to define ad-hoc filter chains for any matching URL path in your application!
-
-This is _far_ more flexible, powerful and concise than how you define filter chains normally in `web.xml`: even if you never used any other feature that Shiro provided and used only this, it alone would make it worth using.
-
-<a name="Web-%7B%7B%5Curls%5C%7D%7D"></a>
-#[[####`[urls]`]]#
-
-The format of each line in the `urls` section is as follows:
-
-``` ini
-_URL_Ant_Path_Expression_ = _Path_Specific_Filter_Chain_
-```
-
-For example:
-
-``` ini
-...
-[urls]
-
-/index.html = anon
-/user/create = anon
-/user/** = authc
-/admin/** = authc, roles[administrator]
-/rest/** = authc, rest
-/remoting/rpc/** = authc, perms["remote:invoke"]
-```
-
-Next we'll cover exactly what these lines mean.
-
-##### <a name="Web-URLPathExpressions"></a>URL Path Expressions
-
-The token on the left of the equals sign (=) is an [Ant](http://ant.apache.org)-style path expression relative to your web application's context root.
-
-For example, let's say you had the following `[urls]` line:
-
-``` ini
-/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.
-
-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 [HttpServletRequest.getContextPath()](http://docs.oracle.com/javaee/1.3/api/javax/servlet/http/HttpServletRequest.html#[[#]]#getContextPath--) value.
-
-#warning('Order Matters!', 'URL path expressions are evaluated against an incoming request in the order they are defined and the <em>FIRST MATCH WINS</em>. For example, let''s asume that there are the following chain definitions:
-
-<pre><code class="ini">/account/** = ssl, authc
-/account/signup = anon
-</code></pre>
-<p>If an incoming request is intended to reach <code>/account/signup/index.html</code> (accessible by all ''anon''ymous users), <em>it will never be handled!</em>. The reason is that the <code>/account/**</code> pattern matched the incoming request first and ''short-circuited'' all remaining definitions.</p>
-<p>Always remember to define your filter chains based on a <em>FIRST MATCH WINS</em> policy!</p>')
-
-<a name="Web-FilterChainDefinitions"></a>
-#[[#####Filter Chain Definitions]]#
-
-The token on the right of the equals sign (=) is comma-delimited list of filters to execute for a request matching that path. It must match the following format:
-
-``` ini
-filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN]
-```
-
-where:
-
-* _filterN_ is the name of a filter bean defined in the `[main]` section and
-* `[optional_configN]` is an optional bracketed string that has meaning for that particular filter for _that particular path_ (per-filter, _path-specific_ configuration!). If the filter does not need specific config for that URL path, you may discard the brackets so `filterN[]` just becomes `filterN`.
-
-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.
-
-#tip('Tip', 'Being able to react to path specific configuration, i.e. the <code>[optional_configN]</code> part of a filter token, is a unique feature available to Shiro filters.
-<p>If you want to create your own <code>javax.servlet.Filter</code> implementation that can also do this, make sure your filter subclasses <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html">org.apache.shiro.web.filter.PathMatchingFilter</a></p>')
-
-<a name="Web-AvailableFilters"></a>
-#[[######Available Filters]]#
-
-The 'pool' of filters available for use in filter chain definitions are defined in the `[main]` section. The name assigned to them in the main section is the name to use in the filter chain definitions. For example:
-
-``` ini
-[main]
-...
-myFilter = com.company.web.some.FilterImplementation
-myFilter.property1 = value1
-...
-
-[urls]
-...
-/some/path/** = myFilter
-```
-
-<a name="Web-defaultfilters"></a>
-<a name="Web-DefaultFilters"></a>
-Default Filters
----------------
-
-When running a web-app, Shiro will create some useful default `Filter` instances and make them available in the `[main]` section automatically. You can configure them in `main` as you would any other bean and reference them in your chain definitions. For example:
-
-``` ini
-[main]
-...
-# Notice how we didn't define the class for the FormAuthenticationFilter ('authc') - it is instantiated and available already:
-authc.loginUrl = /login.jsp
-...
-
-[urls]
-...
-# make sure the end-user is authenticated. If not, redirect to the 'authc.loginUrl' above,
-# and after successful authentication, redirect them back to the original account page they
-# were trying to view:
-/account/** = authc
-...
-```
-
-The default Filter instances available automatically are defined by the [DefaultFilter enum](static/current/apidocs/org/apache/shiro/web/filter/mgt/DefaultFilter.html) and the enum's `name` field is the name available for configuration. They are:
-
-| Filter Name | Class |
-| ----------- | ----- |
-| anon | [org.apache.shiro.web.filter.authc.AnonymousFilter](static/current/apidocs/org/apache/shiro/web/filter/authc/AnonymousFilter.html) |
-| authc | [org.apache.shiro.web.filter.authc.FormAuthenticationFilter](static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html) |
-| authcBasic | [org.apache.shiro.web.filter.authc.BasicHttpAuthenticationFilter](static/current/apidocs/org/apache/shiro/web/filter/authc/BasicHttpAuthenticationFilter.html) |
-| authcBearer | [org.apache.shiro.web.filter.authc.BearerHttpAuthenticationFilter](static/current/apidocs/org/apache/shiro/web/filter/authc/BearerHttpAuthenticationFilter.html) |
-| invalidRequest | [org.apache.shiro.web.filter.InvalidRequestFilter](static/current/apidocs/org/apache/shiro/web/filter/InvalidRequestFilter.html) |
-| logout | [org.apache.shiro.web.filter.authc.LogoutFilter](static/current/apidocs/org/apache/shiro/web/filter/authc/LogoutFilter.html) |
-| noSessionCreation | [org.apache.shiro.web.filter.session.NoSessionCreationFilter](static/current/apidocs/org/apache/shiro/web/filter/session/NoSessionCreationFilter.html) |
-| perms | [org.apache.shiro.web.filter.authz.PermissionsAuthorizationFilter](static/current/apidocs/org/apache/shiro/web/filter/authz/PermissionsAuthorizationFilter.html) |
-| port | [org.apache.shiro.web.filter.authz.PortFilter](static/current/apidocs/org/apache/shiro/web/filter/authz/PortFilter.html) |
-| rest| [org.apache.shiro.web.filter.authz.HttpMethodPermissionFilter](static/current/apidocs/org/apache/shiro/web/filter/authz/HttpMethodPermissionFilter.html) |
-| roles |[org.apache.shiro.web.filter.authz.RolesAuthorizationFilter](static/current/apidocs/org/apache/shiro/web/filter/authz/RolesAuthorizationFilter.html) |
-| ssl | [org.apache.shiro.web.filter.authz.SslFilter](static/current/apidocs/org/apache/shiro/web/filter/authz/SslFilter.html) |
-| user | [org.apache.shiro.web.filter.authc.UserFilter](static/current/apidocs/org/apache/shiro/web/filter/authc/UserFilter.html) |
-
-<a name="Web-EnablingandDisablingFilters"></a>
-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.
-
-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.
-
-Shiro accomplishes this via its [OncePerRequestFilter](static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html) abstract parent class. All of Shiro's out-of-the-box Filter implementations subclass this one and therefore are able to be enabled or disabled without removing them from the filter chain. You can subclass this class for your own filter implementations if you need this functionality as well*.
-
-*[SHIRO-224](https://issues.apache.org/jira/browse/SHIRO-224) will hopefully enable this feature for any filter, not just those subclassing `OncePerRequestFilter`. If this is important to you, please vote for the issue.
-
-<a name="Web-GeneralEnabling%2FDisabling"></a>
-#[[###General Enabling/Disabling]]#
-
-The [OncePerRequestFilter](static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html) (and all of its subclasses) supports enabling/disabling across all requests as well as on a per-request basis.
-
-General enabling or disabling of a filter for all requests is done by setting its `enabled` property to true or false. The default setting is `true` since most filters inherently need to execute if they are configured in a chain.
-
-For example, in shiro.ini:
-
-``` ini
-[main]
-...
-# configure Shiro's default 'ssl' filter to be disabled while testing:
-ssl.enabled = false
-
-[urls]
-...
-/some/path = ssl, authc
-/another/path = ssl, roles[admin]
-...
-```
-
-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.
-
-<a name="Web-RequestspecificEnabling%2FDisabling"></a>
-#[[###Request-specific Enabling/Disabling]]#
-
-`OncePerRequestFilter` actually determines if the filter is enabled or disabled based on its `isEnabled(request, response)` method.
-
-This method defaults to returning the value of the `enabled` property, which is used for generally enabling/disabling all requests as mentioned above. If you wanted to enable or disable a filter based on _request specific_ criteria, you can override the `OncePerRequestFilter` `isEnabled(request,response)` method to perform more specific checks.
-
-<a name="Web-PathspecificEnabling%2FDisabling"></a>
-#[[###Path-specific Enabling/Disabling]]#
-
-Shiro's [PathMatchingFilter](static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html) (a subclass of `OncePerRequestFilter` has the ability to react to configuration based on a _specific path_ being filtered. This means you can enable or disable a filter based on the path and the path-specific configuration in addition to the incoming request and response.
-
-If you need to be able to react to the matching path and the path-specific configuration to determine if a filter is enabled or disabled, instead of overriding `OncePerRequestFilter` `isEnabled(request,response)` method, you would override the `PathMatchingFilter` `isEnabled(request,response,path,pathConfig)` method instead.
-
-<a name="Web-globalFilters"></a>
-#[[###Global Filters]]#
-
-Starting with Shiro 1.6 the ability to define global filters has been added. Adding "global filters" will add additional filters to ALL routes, this includes previously configured filter chains as well as unconfigured paths.
-
-By default, the global filters contains the `invalidRequest` filter. This filter blocks known malicious attacks, see below for configuration details.
-
-Global filters can be customized or disabled, for example
-
-``` ini
-[main]
-...
-# disable Global Filters
-filterChainResolver.globalFilters = null
-```
-
-Define the list of global filters:
-
-``` ini
-[main]
-...
-filterChainResolver.globalFilters = invalidRequest, port
-```
-
-The `invalidRequest` filter blocks requests with non-ascii characters, semicolons, and backslashes, each of these can be disabled independently to allow for backward compatibility.
-
-```ini
-[main]
-...
-invalidRequest.blockBackslash = true
-invalidRequest.blockSemicolon = true
-invalidRequest.blockNonAscii = true
-...
-```
-
-#info('Note', 'If you currently allowing URL rewriting to allow for a <code>jsessionid</code> in the URL, you must set <code>blockSemicolon</code> to <code>false</code>.<BR/><BR/>URL rewriting for <code>jsessionid</code> is defined in section "7.1.3" of the Java Servlet Specification, but it is generally NOT recommended.')
-
-<a name="Web-HSTS"></a>
-#[[###HTTP Strict Transport Security (HSTS)]]#
-
-The [SslFilter](static/current/apidocs/org/apache/shiro/web/filter/authz/SslFilter.html) (and all of its subclasses) supports enabling/disabling HTTP Strict Transport Security (HSTS).
-
-For example, in shiro.ini:
-
-``` ini
-[main]
-...
-# configure Shiro's default 'ssl' filter to enabled HSTS:
-ssl.enabled = true
-ssl.hsts.enabled = true
-ssl.hsts.includeSubDomains = true
-
-[urls]
-...
-/some/path = ssl, authc
-/another/path = ssl, roles[admin]
-...
-```
-
-<a name="Web-sessionManagement"></a>
-<a name="Web-SessionManagement"></a>
-Session Management
-------------------
-
-<a name="Web-ServletContainerSessions"></a>
-#[[###Servlet Container Sessions]]#
-
-In web environments, Shiro's default session manager [`SessionManager`](static/current/apidocs/org/apache/shiro/session/mgt/SessionManager.html) implementation is the [`ServletContainerSessionManager`](static/current/apidocs/org/apache/shiro/web/session/mgt/ServletContainerSessionManager.html). 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 br [...]
-
-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.
-
-<a name="Web-ServletContainerSessionTimeout"></a>
-#[[####Servlet Container Session Timeout]]#
-
-If using the default servlet container support, you configure session timeout as expected in your web application's `web.xml` file. For example:
-
-``` xml
-<session-config>
- <!-- web.xml expects the session timeout in minutes: -->
- <session-timeout>30</session-timeout>
-</session-config>
-```
-
-<a name="Web-NativeSessions"></a>
-#[[###Native Sessions]]#
-
-If you want your session configuration settings and clustering to be portable across servlet containers (e.g. Jetty in testing, but Tomcat or JBoss in production), or you want to control specific session/clustering features, you can enable Shiro's native session management.
-
-The word 'Native' here means that Shiro's own enterprise session management implementation will be used to support all `Subject` and `HttpServletRequest` sessions and bypass the servlet container completely. But rest assured - Shiro implements the relevant parts of the Servlet specification directly so any existing web/http related code works as expected and never needs to 'know' that Shiro is transparently managing sessions.
-
-<a name="Web-%7B%7BDefaultWebSessionManager%7D%7D"></a>
-#[[####`DefaultWebSessionManager`]]#
-
-To enable native session management for your web application, you will need to configure a native web-capable session manager to override the default servlet container-based one. You can do that by configuring an instance of [`DefaultWebSessionManager`](static/current/apidocs/org/apache/shiro/web/session/mgt/DefaultWebSessionManager.html) on Shiro's `SecurityManager`. For example, in `shiro.ini`:
-
-**shiro.ini native web session management**
-
-``` ini
-[main]
-...
-sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
-# configure properties (like session timeout) here if desired
-
-# Use the configured native session manager:
-securityManager.sessionManager = $sessionManager
-```
-
-Once declared, you can configure the `DefaultWebSessionManager` instance with native session options like session timeout and clustering configuration as described in the [Session Management](session-management.html "Session Management") section.
-
-<a name="Web-NativeSessionTimeout"></a>
-#[[#####Native Session Timeout]]#
-
-After configuring the `DefaultWebSessionManager` instance, session timeout is configured as described in [Session Management: Session Timeout](session-management.html#[[#]]#SessionManagement-sessionTimeout)
-
-<a name="Web-SessionCookie"></a>
-#[[#####Session Cookie]]#
-
-The `DefaultWebSessionManager` supports two web-specific configuration properties:
-
-* `sessionIdCookieEnabled` (a boolean)
-* `sessionIdCookie`, a [Cookie](static/current/apidocs/org/apache/shiro/web/servlet/Cookie.html) instance.
-
-#info('Cookie as a template', 'The <code>sessionIdCookie</code> property is essentially a template - you configure the <code>Cookie</code> instance properties, and this template will be used to set the actual HTTP `Cookie` header at runtime with an appropriate session ID value.')
-
-<a name="Web-SessionCookieConfiguration"></a>
-#[[######Session Cookie Configuration]]#
-
-The DefaultWebSessionManager's `sessionIdCookie` default instance is a [`SimpleCookie`](static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html). This simple implementation allows JavaBeans-style property configuration for all of the relevant properties you would want to configure on an http Cookie.
-
-For example, you could set the Cookie domain:
-
-``` ini
-[main]
-...
-securityManager.sessionManager.sessionIdCookie.domain = foo.com
-```
-
-See the [SimpleCookie JavaDoc](static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html) for additional properties.
-
-The cookie's default name is `JSESSIONID` in accordance with the servlet specification. Additionally, Shiro's cookie supports the [`HttpOnly`](https://en.wikipedia.org/wiki/HTTP_cookie#HttpOnly_cookie) and [`SameSite`](https://en.wikipedia.org/wiki/HTTP_cookie#Same-site_cookie) flags. The `sessionIdCookie` sets `HttpOnly` to `true` and `SameSite` to `LAX` by default for extra security.
-
-#info('Note', 'Shiro''s <code>Cookie</code> concept supports the <code>HttpOnly</code> flag even in Servlet 2.4 and 2.5 environments (whereas the Servlet API only supports it natively in 2.6 or later).')
-
-<a name="Web-DisablingtheSessionCookie"></a>
-#[[######Disabling the Session Cookie]]#
-
-If you do not want session cookies to be used, you can disable their use by configuring the `sessionIdCookieEnabled` property to false. For example:
-
-**Disabling native session cookies**
-
-``` ini
-[main]
-...
-securityManager.sessionManager.sessionIdCookieEnabled = false
-```
-
-<a name="Web-rememberme"></a>
-<a name="Web-RememberMeServices"></a>
-Remember Me Services
---------------------
-
-Shiro will perform 'rememberMe' services if the `AuthenticationToken` implements the [`org.apache.shiro.authc.RememberMeAuthenticationToken`](static/current/apidocs/org/apache/shiro/authc/RememberMeAuthenticationToken.html) interface. This interface specifies a method:
-
-``` java
-boolean isRememberMe();
-```
-
-If this method returns `true`, Shiro will remember the end-user's identity across sessions.
-
-#tip('UsernamePasswordToken and RememberMe', 'The frequently-used <code>UsernamePasswordToken</code> already implements the <code>RememberMeAuthenticationToken</code> interface and supports rememberMe logins.')
-
-<a name="Web-ProgrammaticSupport"></a>
-#[[###Programmatic Support]]#
-
-To use rememberMe programmatically, you can set the value to `true` on a class that supports this configuration. For example, using the standard `UsernamePasswordToken`:
-
-``` java
-UsernamePasswordToken token = new UsernamePasswordToken(username, password);
-
-token.setRememberMe(true);
-
-SecurityUtils.getSubject().login(token);
-...
-```
-
-<a name="Web-FormbasedLogin"></a>
-#[[###Form-based Login]]#
-
-For web applications, the `authc` filter is by default a [`FormAuthenticationFilter`](static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html). This supports reading the 'rememberMe' boolean as a form/request parameter. By default, it expects the request param to be named `rememberMe`. Here is an example shiro.ini config supporting this:
-
-``` ini
-[main]
-authc.loginUrl = /login.jsp
-
-[urls]
-
-# your login form page here:
-login.jsp = authc
-```
-
-And in your web form, have a checkbox named 'rememberMe':
-
-``` html
-<form ...>
-
- Username: <input type="text" name="username"/> <br/>
- Password: <input type="password" name="password"/>
- ...
- <input type="checkbox" name="rememberMe" value="true"/>Remember Me?
- ...
-</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`:
-
-``` ini
-[main]
-...
-authc.loginUrl = /whatever.jsp
-authc.usernameParam = somethingOtherThanUsername
-authc.passwordParam = somethingOtherThanPassword
-authc.rememberMeParam = somethingOtherThanRememberMe
-...
-```
-
-<a name="Web-Cookieconfiguration"></a>
-#[[###Cookie configuration]]#
-
-You can configure how the `rememberMe` cookie functions by setting the default {{RememberMeManager}}s various cookie properties. For example, in shiro.ini:
-
-``` ini
-[main]
-...
-
-securityManager.rememberMeManager.cookie.name = foo
-securityManager.rememberMeManager.cookie.maxAge = blah
-...
-```
-
-See the [`CookieRememberMeManager`](static/current/apidocs/org/apache/shiro/web/mgt/CookieRememberMeManager.html) and the supporting [`SimpleCookie`](static/current/apidocs/src-html/org/apache/shiro/web/servlet/SimpleCookie.html) JavaDoc for configuration properties.
-
-<a name="Web-Custom%7B%7BRememberMeManager%7D%7D"></a>
-#[[###Custom `RememberMeManager`]]#
-
-It should be noted that if the default cookie-based `RememberMeManager` implementation does not meet your needs, you can plug in any you like in to the `securityManager` like you would configure any other object reference:
-
-``` ini
-[main]
-...
-rememberMeManager = com.my.impl.RememberMeManager
-securityManager.rememberMeManager = $rememberMeManager
-```
-<a name="Web-taglibrary"></a>
-<a name="Web-JSP%2FGSPTagLibrary"></a>
-JSP / GSP Tag Library
----------------------
-
-Apache Shiro provides a `Subject`-aware JSP/GSP tag library that allows you to control your JSP, JSTL or GSP page output based on the current Subject's state. This is quite useful for personalizing views based on the identity and authorization state of the current user viewing the web page.
-
-<a name="Web-taglibrary"></a>
-<a name="Web-TagLibraryConfiguration"></a>
-#[[###Tag Library Configuration]]#
-
-The Tag Library Descriptor (TLD) file is bundled in `shiro-web.jar` in the `META-INF/shiro.tld` file. To use any of the tags, add the following line to the top of your JSP page (or wherever you define page directives):
-
-``` html
-<%@ taglib prefix="shiro" uri="http://shiro.apache.org/tags" %>
-```
-
-We've used the `shiro` prefix to indicate the shiro tag library namespace, but you can assign whatever name you like.
-
-Now we'll cover each tag and show how it might be used to render a page.
-
-<a name="Web-guesttag"></a>
-<a name="Web-The%7B%7Bguest%7D%7Dtag"></a>
-#[[### 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.
-
-Example:
-
-``` html
-<shiro:guest>
- Hi there! Please <a href="login.jsp">Login</a> or <a href="signup.jsp">Signup</a> today!
-</shiro:guest>
-```
-
-The `guest` tag is the logical opposite of the [`user`](#Web-usertag) tag.
-
-<a name="Web-usertag"></a>
-<a name="Web-The%7B%7Buser%7D%7Dtag"></a>
-#[[###The `user` tag]]#
-
-The `user` tag will display its wrapped content only if the current `Subject` is considered a 'user'. A 'user' in this context is defined as a `Subject` with a known identity, either from a successful authentication or from 'RememberMe' services. Note that this tag is semantically different from the [authenticated](#Web-authenticatedtag) tag, which is more restrictive than this tag.
-
-Example:
-
-``` html
-<shiro:user>
- Welcome back John! Not John? Click <a href="login.jsp">here<a> to login.
-</shiro:user>
-```
-
-The `user` tag is the logical opposite of the [`guest`](#Web-guesttag) tag.
-
-<a name="Web-authenticatedtag"></a>
-<a name="Web-The%7B%7Bauthenticated%7D%7Dtag"></a>
-#[[###The `authenticated` tag]]#
-
-Displays body content only if the current user has successfully authenticated _during their current session_. It is more restrictive than the 'user' tag. It is logically opposite to the 'notAuthenticated' tag.
-
-The `authenticated` tag will display its wrapped content only if the current `Subject` has successfully authenticated _during their current session_. It is a more restrictive tag than the [user](#Web-usertag), which is used to guarantee identity in sensitive workflows.
-
-Example:
-
-``` html
-<shiro:authenticated>
- <a href="updateAccount.jsp">Update your contact information</a>.
-</shiro:authenticated>
-```
-
-The `authenticated` tag is the logical opposite of the [`notAuthenticated`](#Web-notauthenticatedtag) tag.
-
-<a name="Web-notauthenticatedtag"></a>
-<a name="Web-The%7B%7BnotAuthenticated%7D%7Dtag"></a>
-#[[###The `notAuthenticated` tag]]#
-
-The `notAuthenticated` tag will display its wrapped content if the current `Subject` has **NOT** yet successfully authenticated during the current session.
-
-Example:
-
-``` html
-<shiro:notAuthenticated>
- Please <a href="login.jsp">login</a> in order to update your credit card information.
-</shiro:notAuthenticated>
-```
-
-The `notAuthenticated` tag is the logical opposite of the [`authenticated`](#Web-authenticatedtag) tag.
-
-<a name="Web-principaltag"></a>
-<a name="Web-The%7B%7Bprincipal%7D%7Dtag"></a>
-#[[###The `principal` tag]]#
-
-The `principal` tag will output the Subject's [`principal`](static/current/apidocs/org/apache/shiro/subject/Subject.html#[[#]]#getPrincipal--) (identifying attribute) or a property of that principal.
-
-Without any tag attributes, the tag will render the `toString()` value of the principal. For example (assuming the principal is a String username):
-
-``` html
-Hello, <shiro:principal/>, how are you today?
-```
-
-This is (mostly) equivalent to the following:
-
-``` html
-Hello, <%= SecurityUtils.getSubject().getPrincipal().toString() %>, how are you today?
-```
-
-<a name="Web-Typedprincipal"></a>
-#[[####Typed principal]]#
-
-The `principal` tag assumes by default that the principal to print is the `subject.getPrincipal()` value. But if you wanted to print a value that is _not_ the primary principal, but another in the Subject's {[principal collection](static/current/apidocs/org/apache/shiro/subject/Subject.html#[[#]]#getPrincipals--), you can acquire that principal by type and print that value instead.
-
-For example, printing the Subject's user ID (and not the username), assuming the ID was in the principal collection:
-
-``` html
-User ID: <principal type="java.lang.Integer"/>
-```
-
-This is (mostly) equivalent to the following:
-
-``` html
-User ID: <%= SecurityUtils.getSubject().getPrincipals().oneByType(Integer.class).toString() %>
-```
-
-<a name="Web-Principalproperty"></a>
-#[[####Principal property]]#
-
-But what if the principal (either the default primary principal or 'typed' principal above) is a complex object and not a simple string, and you wanted to reference a property on that principal? You can use the `property` attribute to indicate the name of the property to read (must be accessible via a JavaBeans-compatible getter method). For example (assuming the primary principal is a User object):
-
-``` html
-Hello, <shiro:principal property="firstName"/>, how are you today?
-```
-
-This is (mostly) equivalent to the following:
-
-``` html
-Hello, <%= SecurityUtils.getSubject().getPrincipal().getFirstName().toString() %>, how are you today?
-```
-
-Or, combined with the type attribute:
-
-``` html
-Hello, <shiro:principal type="com.foo.User" property="firstName"/>, how are you today?
-```
-
-this is largely equivalent to the following:
-
-``` html
-Hello, <%= SecurityUtils.getSubject().getPrincipals().oneByType(com.foo.User.class).getFirstName().toString() %>, how are you today?
-```
-
-<a name="Web-hasroletag"></a>
-<a name="Web-The%7B%7BhasRole%7D%7Dtag"></a>
-#[[###The `hasRole` tag]]#
-
-The `hasRole` tag will display its wrapped content only if the current `Subject` is assigned the specified role.
-
-For example:
-
-``` html
-<shiro:hasRole name="administrator">
- <a href="admin.jsp">Administer the system</a>
-</shiro:hasRole>
-```
-
-The `hasRole` tag is the logical opposite of the [lacksRole](#Web-lacksroletag) tag.
-
-<a name="Web-lacksroletag"></a>
-<a name="Web-The%7B%7BlacksRole%7D%7Dtag"></a>
-#[[###The `lacksRole` tag]]#
-
-The `lacksRole` tag will display its wrapped content only if the current `Subject` **is NOT** assigned the specified role.
-
-For example:
-
-``` html
-<shiro:lacksRole name="administrator">
- Sorry, you are not allowed to administer the system.
-</shiro:lacksRole>
-```
-
-The `lacksRole` tag is the logical opposite of the [hasRole](#Web-hasroletag) tag.
-
-<a name="Web-hasanyroletag"></a>
-<a name="Web-The%7B%7BhasAnyRole%7D%7Dtag"></a>
-#[[###The `hasAnyRole` tag]]#
-
-The `hasAnyRole` tag will display its wrapped content if the current `Subject` is assigned _any_ of the specified roles from a comma-delimited list of role names.
-
-For example:
-
-``` html
-<shiro:hasAnyRoles name="developer, project manager, administrator">
- You are either a developer, project manager, or administrator.
-</shiro:hasAnyRoles>
-```
-
-The `hasAnyRole` tag does not currently have a logically opposite tag.
-
-<a name="Web-haspermissiontag"></a>
-<a name="Web-The%7B%7BhasPermission%7D%7Dtag"></a>
-#[[###The `hasPermission` tag]]#
-
-The `hasPermission` tag will display its wrapped content only if the current `Subject` 'has' (implies) the specified permission. That is, the user has the specified ability.
-
-For example:
-
-``` html
-<shiro:hasPermission name="user:create">
- <a href="createUser.jsp">Create a new User</a>
-</shiro:hasPermission>
-```
-
-The `hasPermission` tag is the logical opposite of the [lacksPermission](#Web-lackspermissiontag) tag.
-
-<a name="Web-lackspermissiontag"></a>
-<a name="Web-The%7B%7BlacksPermission%7D%7Dtag"></a>
-#[[###The `lacksPermission` tag]]#
-
-The `lacksPermission` tag will display its wrapped content only if the current `Subject` **DOES NOT** have (imply) the specified permission. That is, the user **DOES NOT** have the specified ability.
-
-For example:
-
-``` html
-<shiro:lacksPermission name="user:delete">
- Sorry, you are not allowed to delete user accounts.
-</shiro:lacksPermission>
-```
-
-The `lacksPermission` tag is the logical opposite of the [hasPermission](#Web-haspermissiontag) tag.
-
-#lendAHandDoc()
-
-<input type="hidden" id="ghEditPage" value="web.md.vtl"></input>
[shiro-site] 02/06: [JBake] move guice and introduction guides,
move lend-a-hand template.
Posted by bm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit be5d041c62ac62152cce67429011eeb54dcc4230
Author: Benjamin Marwell <bm...@apache.org>
AuthorDate: Fri Sep 10 06:21:01 2021 +0200
[JBake] move guice and introduction guides, move lend-a-hand template.
---
introduction.md | 52 --------
.../images => jbake/assets/img}/ShiroFeatures.png | Bin
guice.md.vtl => jbake/content/guice.adoc | 133 ++++++++++++---------
jbake/content/introduction.adoc | 56 +++++++++
jbake/templates/header.ftl | 1 +
.../templates/macros/lend-a-hand.ftl | 12 +-
6 files changed, 136 insertions(+), 118 deletions(-)
diff --git a/introduction.md b/introduction.md
deleted file mode 100644
index 28d8d4a..0000000
--- a/introduction.md
+++ /dev/null
@@ -1,52 +0,0 @@
-<a name="Introduction-IntroductiontoApacheShiro"></a>
-#Introduction to Apache Shiro
-
-<a name="Introduction-WhatisApacheShiro%3F"></a>
-##What is Apache Shiro?
-
-Apache Shiro is a powerful and flexible open-source security framework that cleanly handles authentication, authorization, enterprise session management and cryptography.
-
-Apache Shiro's first and foremost goal is to be easy to use and understand. Security can be very complex at times, even painful, but it doesn't have to be. A framework should mask complexities where possible and expose a clean and intuitive API that simplifies the developer's effort to make their application(s) secure.
-
-Here are some things that you can do with Apache Shiro:
-
-* Authenticate a user to verify their identity
-* Perform access control for a user, such as:
- * Determine if a user is assigned a certain security role or not
- * Determine if a user is permitted to do something or not
-* Use a Session API in any environment, even without web or EJB containers.
-* React to events during authentication, access control, or during a session's lifetime.
-* Aggregate 1 or more data sources of user security data and present this all as a single composite user 'view'.
-* Enable Single Sign On (SSO) functionality
-* Enable 'Remember Me' services for user association without login
-...
-and much more - all integrated into a cohesive easy-to-use API.
-
-Shiro attempts to achieve these goals for all application environments - from the simplest command line application to the largest enterprise applications, without forcing dependencies on other 3rd party frameworks, containers, or application servers. Of course the project aims to integrate into these environments wherever possible, but it could be used out-of-the-box in any environment.
-
-<a name="Introduction-ApacheShiroFeatures"></a>
-##Apache Shiro Features
-
-Apache Shiro is a comprehensive application security framework with many features. The following diagram shows where Shiro focuses its energy, and this reference manual will be organized similarly:
-
-<img src="assets/images/ShiroFeatures.png" style="margin:0px auto;display:block"></img>
-
-Shiro targets what the Shiro development team calls "the four cornerstones of application security" - Authentication, Authorization, Session Management, and Cryptography:
-
-* **Authentication:** Sometimes referred to as 'login', this is the act of proving a user is who they say they are.
-
-* **Authorization:** The process of access control, i.e. determining 'who' has access to 'what'.
-
-* **Session Management:** Managing user-specific sessions, even in non-web or EJB applications.
-
-* **Cryptography:** Keeping data secure using cryptographic algorithms while still being easy to use.
-
-There are also additional features to support and reinforce these concerns in different application environments, especially:
-
-* 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.
-* 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.
-<input type="hidden" id="ghEditPage" value="introduction.md"></input>
diff --git a/assets/images/ShiroFeatures.png b/jbake/assets/img/ShiroFeatures.png
similarity index 100%
rename from assets/images/ShiroFeatures.png
rename to jbake/assets/img/ShiroFeatures.png
diff --git a/guice.md.vtl b/jbake/content/guice.adoc
similarity index 65%
rename from guice.md.vtl
rename to jbake/content/guice.adoc
index abe4cc2..2b6ee05 100644
--- a/guice.md.vtl
+++ b/jbake/content/guice.adoc
@@ -1,34 +1,42 @@
-<a name="Guice-IntegratingApacheShirointoGuicebasedApplication"></a>
-Integrating Apache Shiro into Guice based Application
-=====================================================
+= Integrating Apache Shiro into Guice based Application
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, integration, guice
+:idprefix:
+:icons: font
+:toc:
-Shiro [Guice](https://github.com/google/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 a least somewhat familiar with Guice.
-<a name="Guice-Overview"></a>
-Overview
---------
+== Overview
shiro-guice provides three Guice modules that can be included in your application.
-* ShiroModule
- * Provides basic integration for setting up the `SecurityManager`, any `Realms`, and any other Shiro configuration.
- * This module is used by extending it and adding your own custom configuration.
+* ShiroModule
-* ShiroWebModule
- * Extension of `ShiroModule` that sets up the web environment and also allows for filter chain configuration. This uses the [Guice Servlet Module](https://github.com/google/guice/wiki/ServletModule) to configure the filters, and so requires that to be setup.
- * Like the `ShiroModule`, this module is used by extending it and adding your own custom configuration.
+** Provides basic integration for setting up the `SecurityManager`, any `Realms`, and any other Shiro configuration.
+** This module is used by extending it and adding your own custom configuration.
+* ShiroWebModule
-* ShiroAopModule
- * Uses [Guice AOP](https://github.com/google/guice/wiki/AOP) to implement the Shiro AOP annotations. This module is primarily concerned with adapting Shiro `AnnotationMethodInterceptors` to the Guice method interceptor model.
- * This module is typically used by simply installing it. However, if you have your own `AnnotationMethodInterceptors` written for Shiro, they can be easily incorporated by extending it.
+** Extension of `ShiroModule` that sets up the web environment and also allows for filter chain configuration. This uses the https://github.com/google/guice/wiki/ServletModule[Guice Servlet Module] to configure the filters, and so requires that to be setup.
+** Like the `ShiroModule`, this module is used by extending it and adding your own custom configuration.
+* ShiroAopModule
-<a name="Guice-GettingStarted"></a>
-Getting Started
----------------
+** Uses https://github.com/google/guice/wiki/AOP[Guice AOP] to implement the Shiro AOP annotations. This module is primarily concerned with adapting Shiro `AnnotationMethodInterceptors` to the Guice method interceptor model.
+** This module is typically used by simply installing it. However, if you have your own `AnnotationMethodInterceptors` written for Shiro, they can be easily incorporated by extending it.
+
+== Getting Started
+
+First, include the shiro-guice dependency in your project:
+
+++++
+<@dependencies anchorId="cli" deps=[{'g':'org.apache.shiro', 'a':'shiro-guice', "v":"${latestRelease}"}] />
+++++
The most simple configuration is to extend `ShiroModule` to install your own `Realm`.
-``` java
+[source,java]
+----
class MyShiroModule extends ShiroModule {
protected void configureShiro() {
try {
@@ -43,50 +51,55 @@ class MyShiroModule extends ShiroModule {
return Ini.fromResourcePath("classpath:shiro.ini");
}
}
-```
+
+----
In this case, user and role configuration would go in the `shiro.ini` file.
-#warning('shiro.ini usage in Guice', 'It is important to note that, in this above configuration, only the `users` and `roles` sections from the ini file are used.')
+[CAUTION]
+.shiro.ini usage in Guice
+====
+It is important to note that, in this above configuration, only the `users` and `roles` sections from the ini file are used.
+====
-Then, the module is used to create a Guice injector, and the injector is used to obtain a `SecurityManager`. The following example serves the same purpose as the first three lines in the [Quickstart](10-minute-tutorial.html#10MinuteTutorial-Quickstart.java) example.
+Then, the module is used to create a Guice injector, and the injector is used to obtain a `SecurityManager`. The following example serves the same purpose as the first three lines in the link:10-minute-tutorial.html#10MinuteTutorial-Quickstart.java[Quickstart] example.
-``` java
+[source,java]
+----
Injector injector = Guice.createInjector(new MyShiroModule());
SecurityManager securityManager = injector.getInstance(SecurityManager.class);
SecurityUtils.setSecurityManager(securityManager);
-```
+----
-<a name="Guice-AOP"></a>
-AOP
----
+== AOP
Shiro includes several annotations and method interceptors useful for performing authorization via AOP. It also provides a simple API for writing Shiro-specific method interceptors. shiro-guice supports this with the `ShiroAopModule`.
To use it, simply instantiate and install the module alongside your application module and your `ShiroModule`.
-``` java
+[source,java]
+----
Injector injector = Guice.createInjector(new MyShiroModule(), new ShiroAopModule(), new MyApplicationModule());
-```
+----
If you have written custom interceptors that conform to Shiro's api, you may find it useful to extend the `ShiroAopModule`.
-``` java
+[source,java]
+----
class MyShiroAopModule extends ShiroAopModule {
protected void configureInterceptors(AnnotationResolver resolver)
{
bindShiroInterceptor(new MyCustomAnnotationMethodInterceptor(resolver));
}
}
-```
+----
-<a name="Guice-Web"></a>
-Web
----
+== Web
shiro-guice's web integration is designed to integrate Shiro and its filter paradigm with Guice's servlet module. If you are using Shiro in a web environment, and using Guice's servlet module, then you should extend ShiroWebModule rather than ShiroModule. Your web.xml should be setup exactly as Guice's servlet module recommends.
-``` java
+[source,java]
+----
class MyShiroWebModule extends ShiroWebModule {
MyShiroWebModule(ServletContext sc) {
super(sc);
@@ -110,62 +123,64 @@ class MyShiroWebModule extends ShiroWebModule {
return Ini.fromResourcePath("classpath:shiro.ini");
}
}
-```
+----
In the previous code, we have bound an `IniRealm` and setup four filter chains. These chains would be equivalent to the following ini configuration.
-``` ini
+[source,ini]
+----
[urls]
/public/** = anon
/stuff/allowed/** = authcBasic, perms["yes"]
/stuff/forbidden/** = authcBasic, perms["no"]
/** = 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
-``` java
+[source,java]
+----
Key customFilter = Key.get(MyCustomFilter.class);
addFilterChain("/custom/**", customFilter);
-```
+----
We still have to tell guice-servlets about our Shiro filter. Since the `ShiroWebModule` is private, and guice-servlets does not give us a way to expose a filter mapping, we have to bind it manually.
-``` java
+[source,java]
+----
ShiroWebModule.guiceFilterModule()
-```
+----
Or, from within an application module,
-``` java
+[source,java]
+----
ShiroWebModule.bindGuiceFilter(binder())
-```
+----
-<a name="Guice-Properties"></a>
-Properties
-----------
+== Properties
-A number of Shiro classes expose configuration parameters via setter methods. shiro-guice will inject these if it finds a binding for `@Named("shiro.{propName}")`. For instance, to set the session timeout, you could do the following.
+A number of Shiro classes expose configuration parameters via setter methods. shiro-guice will inject these if it finds a binding for `@Named("shiro.{propName}")`. For instance, to set the session timeout, you could do the following.
-``` java
+[source,java]
+----
bindConstant().annotatedWith(Names.named("shiro.globalSessionTimeout")).to(30000L);
-```
+----
If this paradigm doesn't work for you, you may also consider using a provider to instantiate the object and invoking the setters directly.
-<a name="Guice-InjectionofShiroObjects"></a>
-Injection of Shiro Objects
---------------------------
+== Injection of Shiro Objects
shiro-guice uses a Guice `TypeListener` to perform injection on native Shiro classes (any class in a subdirectory of `org.apache.shiro` but not `org.apache.shiro.guice`). However, Guice only considers explicitly bound types as candidates for `TypeListeners`, so if you have a Shiro object that you want injected, you have to declare it explicitly. For instance, to set the `CredentialsMatcher` for a realm, we would need to add the following bindings:
-``` java
+[source,java]
+----
bind(CredentialsMatcher.class).to(HashedCredentialsMatcher.class);
bind(HashedCredentialsMatcher.class);
bindConstant().annotatedWith(Names.named("shiro.hashAlgorithmName")).to(Md5Hash.ALGORITHM_NAME);
-```
-
-#lendAHandDoc()
+----
-<input type="hidden" id="ghEditPage" value="guice.md.vtl"></input>
+++++
+<@lendahand />
+++++
diff --git a/jbake/content/introduction.adoc b/jbake/content/introduction.adoc
new file mode 100644
index 0000000..117e51c
--- /dev/null
+++ b/jbake/content/introduction.adoc
@@ -0,0 +1,56 @@
+= Introduction to Apache Shiro
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, introduction
+:idprefix:
+:icons: font
+
+== What is Apache Shiro?
+
+Apache Shiro is a powerful and flexible open-source security framework that cleanly handles authentication, authorization, enterprise session management and cryptography.
+
+Apache Shiro's first and foremost goal is to be easy to use and understand. Security can be very complex at times, even painful, but it doesn't have to be. A framework should mask complexities where possible and expose a clean and intuitive API that simplifies the developer's effort to make their application(s) secure.
+
+Here are some things that you can do with Apache Shiro:
+
+* Authenticate a user to verify their identity
+* Perform access control for a user, such as:
+** Determine if a user is assigned a certain security role or not
+** Determine if a user is permitted to do something or not
+* Use a Session API in any environment, even without web or EJB containers.
+* React to events during authentication, access control, or during a session's lifetime.
+* Aggregate 1 or more data sources of user security data and present this all as a single composite user 'view'.
+* Enable Single Sign On (SSO) functionality
+* Enable 'Remember Me' services for user association without login +
+… +
+and much more - all integrated into a cohesive easy-to-use API.
+
+Shiro attempts to achieve these goals for all application environments - from the simplest command line application to the largest enterprise applications, without forcing dependencies on other 3rd party frameworks, containers, or application servers. Of course the project aims to integrate into these environments wherever possible, but it could be used out-of-the-box in any environment.
+
+== Apache Shiro Features
+
+Apache Shiro is a comprehensive application security framework with many features. The following diagram shows where Shiro focuses its energy, and this reference manual will be organized similarly:
+
+[#img-shiro-features]
+.Apache Shiro Features
+[link=img/ShiroFeatures.png]
+image::img/ShiroFeatures.png["Apache Shiro Features",align="center"]
+
+Shiro targets what the Shiro development team calls "the four cornerstones of application security" - Authentication, Authorization, Session Management, and Cryptography:
+
+* *Authentication:* Sometimes referred to as 'login', this is the act of proving a user is who they say they are.
+
+* *Authorization:* The process of access control, i.e. determining 'who' has access to 'what'.
+
+* *Session Management:* Managing user-specific sessions, even in non-web or EJB applications.
+
+* *Cryptography:* Keeping data secure using cryptographic algorithms while still being easy to use.
+
+There are also additional features to support and reinforce these concerns in different application environments, especially:
+
+* 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.
+* 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.
diff --git a/jbake/templates/header.ftl b/jbake/templates/header.ftl
index e60c075..1bee977 100644
--- a/jbake/templates/header.ftl
+++ b/jbake/templates/header.ftl
@@ -17,6 +17,7 @@
-->
<#include "macros/versions.ftl">
<#include "macros/dependencies.ftl">
+<#include "macros/lend-a-hand.ftl">
<html lang="en">
<head>
<meta charset="utf-8"/>
diff --git a/templates/macros/lend-a-hand.vtl b/jbake/templates/macros/lend-a-hand.ftl
similarity index 80%
rename from templates/macros/lend-a-hand.vtl
rename to jbake/templates/macros/lend-a-hand.ftl
index 4e8cfde..0907f27 100644
--- a/templates/macros/lend-a-hand.vtl
+++ b/jbake/templates/macros/lend-a-hand.ftl
@@ -1,13 +1,11 @@
-#macro(lendAHandDoc)
-<h2><a name="Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+<#macro lendahand>
+<h2 id="Lendahandwithdocumentation">Lend a hand with documentation</h2>
<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider correcting, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p>
<p>The easiest way to contribute your documentation is to submit a pull-request by clicking on the <code>Edit</code> link below, or send it to the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
-#end
+</#macro>
-
-#macro(todoAddDoc)
+<#macro todoAddDoc>
<p>TODO</p>
-#lendAHandDoc()
-#end
\ No newline at end of file
+</#macro>
[shiro-site] 05/06: Merge replace contribute.md with
how-to-contribute.md
Posted by bm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit bfb3a1448a68e4cb6bd2258bab308de4299a28de
Author: Brian Demers <bd...@apache.org>
AuthorDate: Fri Sep 10 10:36:10 2021 -0400
Merge replace contribute.md with how-to-contribute.md
Updated ref in navigation.md (which isn't actually used)
Added redirect
---
.htaccess | 3 ++-
contribute.md | 18 ------------------
navigation.md | 2 +-
sitemap.xml | 3 ---
4 files changed, 3 insertions(+), 23 deletions(-)
diff --git a/.htaccess b/.htaccess
index 39c4ce5..0c8b288 100644
--- a/.htaccess
+++ b/.htaccess
@@ -11,4 +11,5 @@ RedirectMatch ^/shiro-spring(.*) /static/current/shiro-spring/$1
RedirectMatch ^/shiro-guice(.*) /static/current/shiro-guice/$1
RedirectMatch ^/shiro-web(.*) /static/current/shiro-web/$1
RedirectMatch ^/spring.html /spring-framework.html
-RedirectMatch ^/features-overview.html /features.html
\ No newline at end of file
+RedirectMatch ^/features-overview.html /features.html
+RedirectMatch ^/contribute.html /how-to-contribute.html
diff --git a/contribute.md b/contribute.md
deleted file mode 100644
index 3e8ea4f..0000000
--- a/contribute.md
+++ /dev/null
@@ -1,18 +0,0 @@
-<a name="Contribute-ContributingtoApacheShiro"></a>
-#Contributing to Apache Shiro
-
-Apache Shiro is a non-profit project and relies on your help and contributions in order to evolve and improve.
-
-At the Shiro project we make it easy for anyone to join our great community and lend a hand. We welcome any help you can offer inlcuding help with documentation, identifying bugs, providing answers on the user mailing list, and providing helpful code improvements.
-
-Below are helpful links on how you can contribute to the Apache Shiro project.
-
-* [How to Contribute](how-to-contribute.html) - A starting point for contributing to the Shiro project
-
-* [Shiro Issue Tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SHIRO%20AND%20status%20%3D%20Open%20ORDER%20BY%20priority%20DESC) - Once you're ready to contribute, this is a good place to see what needs to get done
-
-* [Donate to ASF](http://www.apache.org/foundation/sponsorship.html) - Shiro is a project under the Apache Software Foundation, a non-profit that relies on donations and community support
-
-* [Developer Resources](developer-resources.html) - Helpful information for anyone providing project help as a committer or contributor
-
-<input type="hidden" id="ghEditPage" value="contribute.md"></input>
diff --git a/navigation.md b/navigation.md
index c7774e4..8defa9d 100644
--- a/navigation.md
+++ b/navigation.md
@@ -17,7 +17,7 @@
* [Articles](articles.html)
* [API](http://shiro.apache.org/static/current/apidocs)
-* [Contribute](contribute.html)
+* [Contribute](how-to-contribute.html)
* [How to Contribute](how-to-contribute.html)
* [Donate to ASF](http://www.apache.org/foundation/sponsorship.html)
diff --git a/sitemap.xml b/sitemap.xml
index f8b1bfb..b4a9c8f 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -73,9 +73,6 @@
<loc>https://shiro.apache.org/configuration.html</loc>
</url>
<url>
- <loc>https://shiro.apache.org/contribute.html</loc>
- </url>
- <url>
<loc>https://shiro.apache.org/core.html</loc>
</url>
<url>
[shiro-site] 01/06: [JBake][Content] convert spring pages.
Posted by bm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit 3e8f5ea057edd7d633c28cb111d231450cddf055
Author: Benjamin Marwell <bm...@apache.org>
AuthorDate: Wed Sep 8 23:07:33 2021 +0200
[JBake][Content] convert spring pages.
---
jbake/.gitignore | 3 +
jbake/content/spring-boot.adoc | 200 ++++++++++++++++++++
jbake/content/spring-framework.adoc | 270 +++++++++++++++++++++++++++
spring-xml.md => jbake/content/spring-xml.md | 46 ++---
jbake/jbake.properties | 3 +
jbake/templates/header.ftl | 1 +
jbake/templates/macros/dependencies.ftl | 101 ++++++++++
spring-boot.md.vtl | 171 -----------------
spring-framework.md.vtl | 215 ---------------------
templates/macros/dependencies.vtl | 24 ---
10 files changed, 598 insertions(+), 436 deletions(-)
diff --git a/jbake/.gitignore b/jbake/.gitignore
index 9adf614..6ef6ecf 100644
--- a/jbake/.gitignore
+++ b/jbake/.gitignore
@@ -1,2 +1,5 @@
output
/target/
+.project
+.settings
+cache
\ No newline at end of file
diff --git a/jbake/content/spring-boot.adoc b/jbake/content/spring-boot.adoc
new file mode 100644
index 0000000..590fdb8
--- /dev/null
+++ b/jbake/content/spring-boot.adoc
@@ -0,0 +1,200 @@
+= Integrating Apache Shiro into Spring-Boot Applications
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, manual, spring
+: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.
+
+== 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).
+
+++++
+<@dependencies anchorId="web" deps=[{"g":"org.apache.shiro", "a":"shiro-spring-boot-web-starter", "v":"${latestRelease}"}] />
+++++
+
+Provide a Realm implementation:
+[source,java]
+----
+@Bean
+public Realm realm() {
+ ...
+}
+----
+
+And finally a `ShiroFilterChainDefinition` which will map any application specific paths to a given filter, in order to allow different paths different levels of access.
+
+[source,java]
+----
+@Bean
+public ShiroFilterChainDefinition shiroFilterChainDefinition() {
+ DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
+
+ // logged in users with the 'admin' role
+ chainDefinition.addPathDefinition("/admin/**", "authc, roles[admin]");
+
+ // logged in users with the 'document:read' permission
+ chainDefinition.addPathDefinition("/docs/**", "authc, perms[document:read]");
+
+ // all other paths require a logged in user
+ chainDefinition.addPathDefinition("/**", "authc");
+ return chainDefinition;
+}
+----
+
+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].
+
+=== Enabling Shiro Annotations
+
+In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, `@RequiresRoles`, `@RequiresPermissions`, etc.) These annotations are enabled automatically in both starters listed above.
+
+Simply annotate your methods in order to use them:
+
+[source,java]
+----
+@RequiresPermissions("document:read")
+public void readDocument() {
+ ...
+}
+----
+
+=== Annotations and Web Applications
+
+Shiro annotations are fully supported for use in `@Controller` classes, for example:
+
+[source,java]
+----
+@Controller
+public class AccountInfoController {
+
+ @RequiresRoles("admin")
+ @RequestMapping("/admin/config")
+ public String adminConfig(Model model) {
+ return "view";
+ }
+}
+----
+
+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]`.
+
+[source,java]
+----
+@Bean
+public ShiroFilterChainDefinition shiroFilterChainDefinition() {
+ DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
+ chainDefinition.addPathDefinition("/**", "anon"); // all paths are managed via annotations
+
+ // or allow basic authentication, but NOT require it.
+ // chainDefinition.addPathDefinition("/**", "authcBasic[permissive]");
+ return chainDefinition;
+}
+----
+
+=== Caching
+
+Enabling caching is as simple as providing a link:caching.html[CacheManager] bean:
+
+[source,java]
+----
+@Bean
+protected CacheManager cacheManager() {
+ return new MemoryConstrainedCacheManager();
+}
+----
+
+=== Configuration Properties
+
+[width="100%",cols="36%,24%,40%",options="header",]
+|===
+|Key |Default Value |Description
+
+|shiro.enabled
+|`true`
+|Enables Shiro’s Spring module
+
+|shiro.web.enabled
+|`true`
+|Enables Shiro’s Spring web module
+
+|shiro.annotations.enabled |`true` |Enables Spring support for Shiro’s annotations
+
+|shiro.sessionManager.deleteInvalidSessions |`true` |Remove invalid session from session storage
+
+|shiro.sessionManager.sessionIdCookieEnabled |`true` |Enable session ID to cookie, for session tracking
+
+|shiro.sessionManager.sessionIdUrlRewritingEnabled |`true` |Enable session URL rewriting support
+
+|shiro.userNativeSessionManager |`false` |If enabled Shiro will manage the HTTP sessions instead of the container
+
+|shiro.sessionManager.cookie.name |`JSESSIONID` |Session cookie name
+
+|shiro.sessionManager.cookie.maxAge |`-1` |Session cookie max age
+
+|shiro.sessionManager.cookie.domain |null |Session cookie domain
+
+|shiro.sessionManager.cookie.path |null |Session cookie path
+
+|shiro.sessionManager.cookie.secure |`false` |Session cookie secure flag
+
+|shiro.rememberMeManager.cookie.name |`rememberMe` |RememberMe cookie name
+
+|shiro.rememberMeManager.cookie.maxAge |one year |RememberMe cookie max age
+
+|shiro.rememberMeManager.cookie.domain |null |RememberMe cookie domain
+
+|shiro.rememberMeManager.cookie.path |null |RememberMe cookie path
+
+|shiro.rememberMeManager.cookie.secure |`false` |RememberMe cookie secure flag
+
+|shiro.loginUrl |`/login.jsp` |Login URL used when unauthenticated users are redirected to login page
+
+|shiro.successUrl |`/` |Default landing page after a user logs in (if alternative cannot be found in the current session)
+
+|shiro.unauthorizedUrl |null |Page to redirect user to if they are unauthorized (403 page)
+|===
+
+== 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).
+
+++++
+<@dependencies anchorId="cli" deps=[{"g":"org.apache.shiro", "a":"shiro-spring-boot-starter", "v":"${latestRelease}"}] />
+++++
+
+The only thing that is left is to configure a link:realm.html[realm]:
+
+[source,java]
+----
+@Bean
+public Realm realm() {
+ ...
+}
+----
+
+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:#Spring-WebApplications[Web Applications] section below instead.
+
+[source,java]
+----
+@Autowired
+private SecurityManager securityManager;
+
+ @PostConstruct
+ private void initStaticSecurityManager() {
+ SecurityUtils.setSecurityManager(securityManager);
+ }
+----
+
+That is it, now you can get the current `Subject` using:
+
+[source,java]
+----
+SecurityUtils.getSubject();
+----
+
+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/jbake/content/spring-framework.adoc b/jbake/content/spring-framework.adoc
new file mode 100644
index 0000000..ea3001a
--- /dev/null
+++ b/jbake/content/spring-framework.adoc
@@ -0,0 +1,270 @@
+= Integrating Apache Shiro into Spring-based Applications
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, manual, spring
+:idprefix:
+:toc:
+
+This page covers the ways to integrate Shiro into link:http://spring.io[Spring]-based applications.
+
+== 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).
+
+++++
+<@dependencies anchorId="cli" deps=[{'g':'org.apache.shiro', 'a':'shiro-spring', "v":"${latestRelease}"},{"g":'org.springframework', "a":'spring-context', "v":'${r"${spring.version}"}'}] />
+++++
+
+Import the Shiro Spring configurations:
+
+[source,java]
+----
+@Configuration
+@Import({ShiroBeanConfiguration.class,
+ ShiroConfiguration.class,
+ ShiroAnnotationProcessorConfiguration.class})
+public class CliAppConfig {
+ ...
+}
+----
+
+The above configurations do the following:
+
+[width="100%",cols="55%,45%",options="header",]
+|===
+|Configuration Class |Description
+
+|org.apache.shiro.spring.config.ShiroBeanConfiguration
+|Configures Shiro’s lifecycle and events
+
+|org.apache.shiro.spring.config.ShiroConfiguration
+|Configures Shiro Beans (SecurityManager, SessionManager, etc)
+
+|org.apache.shiro.spring.config.ShiroAnnotationProcessorConfiguration
+|Enables Shiro’s annotation processing
+|===
+
+The only thing that is left is to configure a link:realm.html[realm]:
+
+[source,java]
+----
+@Bean
+public Realm realm() {
+ ...
+}
+----
+
+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.
+
+[source,java]
+----
+@Autowired
+private SecurityManager securityManager;
+
+ @PostConstruct
+ private void initStaticSecurityManager() {
+ SecurityUtils.setSecurityManager(securityManager);
+ }
+----
+
+That is it, now you can get the current `Subject` using:
+[source,java]
+----
+SecurityUtils.getSubject();
+----
+
+You can see a full example in our link:https://github.com/apache/shiro/tree/main/samples/spring[samples on Github].
+
+== 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).
+
+++++
+<@dependencies anchorId="web" deps=[{"g":'org.apache.shiro', "a":'shiro-spring', "v":"${latestRelease}"}, {"g":'org.apache.shiro', "a":'shiro-web', "v":"${latestRelease}"},{"g":'org.springframework', "a":'spring-webmvc', "v":'${r"${spring.version}"}'}] />
+++++
+
+Import the Shiro Spring configurations:
+
+[source,java]
+----
+@Configuration
+@Import({ShiroBeanConfiguration.class,
+ ShiroAnnotationProcessorConfiguration.class,
+ ShiroWebConfiguration.class,
+ ShiroWebFilterConfiguration.class,
+ ShiroRequestMappingConfig.class})
+public class ApplicationConfig {
+ ...
+}
+----
+
+The above configurations do the following:
+
+[width="100%",cols="55%,45%",options="header",]
+|===
+|Configuration Class |Description
+
+|org.apache.shiro.spring.config.ShiroBeanConfiguration
+|Configures Shiro’s lifecycle and events
+
+|org.apache.shiro.spring.config.ShiroAnnotationProcessorConfiguration
+|Enables Shiro’s annotation processing
+
+|org.apache.shiro.spring.web.config.ShiroWebConfiguration
+|Configures Shiro Beans for web usage (SecurityManager, SessionManager, etc)
+
+|org.apache.shiro.spring.web.config.ShiroWebFilterConfiguration
+|Configures Shiro’s web filter
+
+|org.apache.shiro.spring.web.config.ShiroRequestMappingConfig
+|Configures Spring with Shiro’s `UrlPathHelper` implementation to ensure URLs are processed the same both frameworks
+|===
+
+Provide a Realm implementation:
+[source,java]
+----
+@Bean
+public Realm realm() {
+ ...
+}
+----
+
+And finally a `ShiroFilterChainDefinition` which will map any application specific paths to a given filter, in order to allow different paths different levels of access.
+
+[source,java]
+----
+@Bean
+public ShiroFilterChainDefinition shiroFilterChainDefinition() {
+ DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
+
+ // logged in users with the 'admin' role
+ chainDefinition.addPathDefinition("/admin/**", "authc, roles[admin]");
+
+ // logged in users with the 'document:read' permission
+ chainDefinition.addPathDefinition("/docs/**", "authc, perms[document:read]");
+
+ // all other paths require a logged in user
+ chainDefinition.addPathDefinition("/**", "authc");
+ return chainDefinition;
+}
+----
+
+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].
+
+== Enabling Shiro Annotations
+
+In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, `@RequiresRoles`, `@RequiresPermissions`, etc.) These annotations are enabled by importing the `ShiroAnnotationProcessorConfiguration` Spring configuration in both sections above.
+
+Simply annotate your methods in order to use them:
+
+[source,java]
+----
+@RequiresPermissions("document:read")
+public void readDocument() {
+ ...
+}
+----
+
+=== Annotations and Web Applications
+
+Shiro annotations are fully supported for use in `@Controller` classes, for example:
+
+[source,java]
+----
+@Controller
+public class AccountInfoController {
+
+ @RequiresRoles("admin")
+ @RequestMapping("/admin/config")
+ public String adminConfig(Model model) {
+ return "view";
+ }
+}
+----
+
+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]`.
+
+[source,java]
+----
+@Bean
+public ShiroFilterChainDefinition shiroFilterChainDefinition() {
+ DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
+ chainDefinition.addPathDefinition("/**", "anon"); // all paths are managed via annotations
+
+ // or allow basic authentication, but NOT require it.
+ // chainDefinition.addPathDefinition("/**", "authcBasic[permissive]");
+ return chainDefinition;
+}
+----
+
+== Caching
+
+Enabling caching is as simple as providing a link:http://shiro.apache.org/caching.html[CacheManager] bean:
+
+[source,java]
+----
+@Bean
+protected CacheManager cacheManager() {
+ return new MemoryConstrainedCacheManager();
+}
+----
+
+
+== Configuration Properties
+
+[width="100%",cols="36%,14%,40%",options="header",]
+|===
+|Key |Default Value |Description
+
+|shiro.sessionManager.deleteInvalidSessions |`true` |Remove invalid
+session from session storage
+
+|shiro.sessionManager.sessionIdCookieEnabled |`true` |Enable session ID
+to cookie, for session tracking
+
+|shiro.sessionManager.sessionIdUrlRewritingEnabled |`true` |Enable
+session URL rewriting support
+
+|shiro.userNativeSessionManager |`false` |If enabled Shiro will manage
+the HTTP sessions instead of the container
+
+|shiro.sessionManager.cookie.name |`JSESSIONID` |Session cookie name
+
+|shiro.sessionManager.cookie.maxAge |`-1` |Session cookie max age
+
+|shiro.sessionManager.cookie.domain |null |Session cookie domain
+
+|shiro.sessionManager.cookie.path |null |Session cookie path
+
+|shiro.sessionManager.cookie.secure |`false` |Session cookie secure flag
+
+|shiro.rememberMeManager.cookie.name |`rememberMe` |RememberMe cookie
+name
+
+|shiro.rememberMeManager.cookie.maxAge |one year |RememberMe cookie max
+age
+
+|shiro.rememberMeManager.cookie.domain |null |RememberMe cookie domain
+
+|shiro.rememberMeManager.cookie.path |null |RememberMe cookie path
+
+|shiro.rememberMeManager.cookie.secure |`false` |RememberMe cookie
+secure flag
+
+|shiro.loginUrl |`/login.jsp` |Login URL used when unauthenticated users
+are redirected to login page
+
+|shiro.successUrl |`/` |Default landing page after a user logs in (if
+alternative cannot be found in the current session)
+
+|shiro.unauthorizedUrl |null |Page to redirect user to if they are
+unauthorized (403 page)
+|===
+
+
+
diff --git a/spring-xml.md b/jbake/content/spring-xml.md
similarity index 92%
rename from spring-xml.md
rename to jbake/content/spring-xml.md
index a4c5eb3..81321c1 100644
--- a/spring-xml.md
+++ b/jbake/content/spring-xml.md
@@ -1,16 +1,19 @@
-<a name="SpringXml-IntegratingApacheShirointoSpringbasedApplications"></a>
-#Integrating Apache Shiro into Spring-based Applications
+title=Integrating Apache Shiro into Spring-based Applications
+type=page
+tags=documentation, manual
+status=published
+~~~~~~
This page covers the ways to integrate Shiro into [Spring](http://spring.io)-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.
-## <a name="SpringXml-StandaloneApplications"></a>Standalone Applications
+## Standalone Applications
Here is the simplest way to enable an application singleton `SecurityManager` in Spring applications:
-``` xml
+```xml
<!-- Define the realm you want to use to connect to your back-end security datasource: -->
<bean id="myRealm" class="...">
...
@@ -32,7 +35,6 @@ Here is the simplest way to enable an application singleton `SecurityManager` in
</bean>
```
-<a name="SpringXml-WebApplications"></a>
## Web Applications
Shiro has first-rate 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
@@ -45,12 +47,11 @@ Now in Shiro 1.0 and later, all Shiro configuration is done in Spring XML provid
Here is how to configure Shiro in a Spring-based web application:
-<a name="SpringXml-web.xml"></a>
### web.xml
In addition to your other Spring web.xml elements (`ContextLoaderListener`, `Log4jConfigListener`, etc), define the following filter and filter mapping:
-``` xml
+```xml
<!-- The filter-name matches name of a 'shiroFilter' bean inside applicationContext.xml -->
<filter>
<filter-name>shiroFilter</filter-name>
@@ -74,12 +75,11 @@ In addition to your other Spring web.xml elements (`ContextLoaderListener`, `Log
You can see a full example in our [samples on Github](https://github.com/apache/shiro/tree/main/samples/spring-xml).
-<a name="SpringXml-applicationContext.xml"></a>
-###applicationContext.xml
+### applicationContext.xml
In your applicationContext.xml file, define the web-enabled `SecurityManager` and the 'shiroFilter' bean that will be referenced from `web.xml`.
-``` xml
+```xml
<bean id="shiroFilter" class="org.apache.shiro.spring.web.ShiroFilterFactoryBean">
<property name="securityManager" ref="securityManager"/>
<!-- override these for application-specific URLs if you like:
@@ -129,14 +129,13 @@ In your applicationContext.xml file, define the web-enabled `SecurityManager` an
</bean>
```
-<a name="SpringXml-EnablingShiroAnnotations"></a>
-##Enabling Shiro Annotations
+## Enabling Shiro Annotations
In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, `@RequiresRoles`, `@RequiresPermissions`, etc. This requires Shiro's Spring AOP integration to scan for the appropriate annotated classes and perform security logic as necessary.
Here is how to enable these annotations. Just add these two bean definitions to `applicationContext.xml`:
-``` xml
+```xml
<!-- Enable Shiro Annotations for Spring-configured beans. Only run after -->
<!-- the lifecycleBeanProcessor has run: -->
<bean class="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator" depends-on="lifecycleBeanPostProcessor"/>
@@ -145,17 +144,15 @@ Here is how to enable these annotations. Just add these two bean definitions to
</bean>
```
-<a name="SpringXml-SecureSpringRemoting"></a>
-##Secure Spring Remoting
+## Secure Spring Remoting
There are two parts to Shiro's Spring remoting support: Configuration for the client making the remoting call and configuration for the server receiving and processing the remoting call.
-<a name="SpringXml-ServersideConfiguration"></a>
-###Server-side Configuration
+### Server-side Configuration
When a remote method invocation comes in to a Shiro-enabled server, the [Subject](subject.html "Subject") associated with that RPC call must be bound to the receiving thread for access during the thread's execution. This is done by defining Shiro's `SecureRemoteInvocationExecutor` bean in `applicationContext.xml`:
-``` xml
+```xml
<!-- Secure Spring remoting: Ensure any Spring Remoting method invocations -->
<!-- can be associated with a Subject for security checks. -->
<bean id="secureRemoteInvocationExecutor" class="org.apache.shiro.spring.remoting.SecureRemoteInvocationExecutor">
@@ -167,7 +164,7 @@ Once you have defined this bean, you must plug it in to whatever remoting `Expor
For example, if using HTTP-based remoting (notice the property reference to the `secureRemoteInvocationExecutor` bean):
-``` xml
+```xml
<bean name="/someService" class="org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter">
<property name="service" ref="someService"/>
<property name="serviceInterface" value="com.pkg.service.SomeService"/>
@@ -175,12 +172,11 @@ For example, if using HTTP-based remoting (notice the property reference to the
</bean>
```
-<a name="SpringXml-ClientsideConfiguration"></a>
-###Client-side Configuration
+### Client-side Configuration
When a remote call is being executed, the `Subject` identifying information must be attached to the remoting payload to let the server know who is making the call. If the client is a Spring-based client, that association is done via Shiro's `SecureRemoteInvocationFactory`:
-``` xml
+```xml
<bean id="secureRemoteInvocationFactory" class="org.apache.shiro.spring.remoting.SecureRemoteInvocationFactory"/>
```
@@ -188,7 +184,7 @@ Then after you've defined this bean, you need to plug it in to the protocol-spec
For example, if you were using HTTP-based remoting (notice the property reference to the `secureRemoteInvocationFactory` bean defined above):
-``` xml
+```xml
<bean id="someService" class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
<property name="serviceUrl" value="http://host:port/remoting/someService"/>
<property name="serviceInterface" value="com.pkg.service.SomeService"/>
@@ -196,10 +192,8 @@ For example, if you were using HTTP-based remoting (notice the property referenc
</bean>
```
-<a name="SpringXml-Lendahandwithdocumentation"></a>
-##Lend a hand with documentation
+## Lend a hand with documentation
While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider correcting, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro.
The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists").
-<input type="hidden" id="ghEditPage" value="spring-xml.md"></input>
diff --git a/jbake/jbake.properties b/jbake/jbake.properties
index 3ab2072..60e0431 100644
--- a/jbake/jbake.properties
+++ b/jbake/jbake.properties
@@ -8,3 +8,6 @@ render.archive=true
template.download.file=download.ftl
template.lend_a_hand.file=lend_a_hand.ftl
+
+db.store=plocal
+db.path=cache
\ No newline at end of file
diff --git a/jbake/templates/header.ftl b/jbake/templates/header.ftl
index 81fde94..e60c075 100644
--- a/jbake/templates/header.ftl
+++ b/jbake/templates/header.ftl
@@ -16,6 +16,7 @@
limitations under the License.
-->
<#include "macros/versions.ftl">
+<#include "macros/dependencies.ftl">
<html lang="en">
<head>
<meta charset="utf-8"/>
diff --git a/jbake/templates/macros/dependencies.ftl b/jbake/templates/macros/dependencies.ftl
new file mode 100644
index 0000000..ab2850a
--- /dev/null
+++ b/jbake/templates/macros/dependencies.ftl
@@ -0,0 +1,101 @@
+<#macro dependencies anchorId deps=[] >
+<ul class="nav nav-tabs" id="dependency-${anchorId}-tab" role="tablist">
+ <#-- maven -->
+ <li class="nav-item" role="presentation">
+ <button
+ class="nav-link active"
+ id="maven-${anchorId}-tab"
+ data-bs-toggle="tab"
+ data-bs-target="#maven-${anchorId}"
+ type="button"
+ role="tab"
+ aria-controls="maven-${anchorId}"
+ aria-selected="true"
+ >Maven</button>
+ </li>
+ <#-- gradle -->
+ <li class="nav-item" role="presentation">
+ <button
+ class="nav-link"
+ id="gradle-${anchorId}-tab"
+ data-bs-toggle="tab"
+ data-bs-target="#gradle-${anchorId}"
+ type="button"
+ role="tab"
+ aria-controls="gradle-${anchorId}"
+ aria-selected="false"
+ >Gradle</button>
+ </li>
+ <#-- ivy -->
+ <li class="nav-item" role="presentation">
+ <button
+ class="nav-link"
+ id="ivy-${anchorId}-tab"
+ data-bs-toggle="tab"
+ data-bs-target="#ivy-${anchorId}"
+ type="button"
+ role="tab"
+ aria-controls="ivy-${anchorId}"
+ aria-selected="false"
+ >Ivy</button>
+ </li>
+ <#-- Leiningen -->
+ <li class="nav-item" role="presentation">
+ <button
+ class="nav-link"
+ id="leiningen-${anchorId}-tab"
+ data-bs-toggle="tab"
+ data-bs-target="#leiningen-${anchorId}"
+ type="button"
+ role="tab"
+ aria-controls="leiningen-${anchorId}"
+ aria-selected="false"
+ >Leiningen</button>
+ </li>
+</ul>
+<div class="tab-content" id="dependency-${anchorId}-tab-content">
+ <div
+ class="tab-pane fade show active"
+ id="maven-${anchorId}"
+ role="tabpanel"
+ aria-labelledby="maven-${anchorId}-tab"
+ >
+ <pre><code class='xml language-xml'><#list deps as dep><dependency>
+ <groupId>${dep.g}</groupId>
+ <artifactId>${dep.a}</artifactId>
+ <version>${dep.v}</version>
+</dependency>
+</#list></code></pre>
+ </div>
+ <#-- gradle -->
+ <div
+ class="tab-pane fade"
+ id="gradle-${anchorId}"
+ role="tabpanel"
+ aria-labelledby="gradle-${anchorId}-tab"
+ >
+ <pre><code class='groovy language-groovy'><#list deps as dep>compile '${dep.g}:${dep.a}:${dep.v}'
+</#list></code></pre>
+ </div>
+ <#-- ivy -->
+ <div
+ class="tab-pane fade"
+ id="ivy-${anchorId}"
+ role="tabpanel"
+ aria-labelledby="ivy-${anchorId}-tab"
+ >
+ <pre><code class='xml language-xml'><#list deps as dep><dependency org="${dep.g}" name="${dep.a}" rev="${dep.v}"/>
+</#list></code></pre>
+ </div>
+ <#-- Leiningen -->
+ <div
+ class="tab-pane fade"
+ id="leiningen-${anchorId}"
+ role="tabpanel"
+ aria-labelledby="leiningen-${anchorId}-tab"
+ >
+ <pre><code class='clojure language-clojure'><#list deps as dep>[${dep.g}/${dep.a} "${dep.v}"]
+</#list></code></pre>
+ </div>
+</div>
+</#macro>
diff --git a/spring-boot.md.vtl b/spring-boot.md.vtl
deleted file mode 100644
index 64a124d..0000000
--- a/spring-boot.md.vtl
+++ /dev/null
@@ -1,171 +0,0 @@
-#parse("templates/includes.vtl")
-
-<a name="Spring-IntegratingApacheShirointoSpringbasedApplications"></a>
-#Integrating Apache Shiro into Spring-Boot Applications
-
-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 [annotation](spring-framework.html) or [XML](spring-xml.html) guides.
-
-<a name="Spring-WebApplications"></a>
-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).
-
-#dependencies('web', [['org.apache.shiro', 'shiro-spring-boot-web-starter', "${latestRelease}"]])
-
-Provide a Realm implementation:
-``` java
-@Bean
-public Realm realm() {
- ...
-}
-```
-
-And finally a `ShiroFilterChainDefinition` which will map any application specific paths to a given filter, in order to allow different paths different levels of access.
-
-``` java
-@Bean
-public ShiroFilterChainDefinition shiroFilterChainDefinition() {
- DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
-
- // logged in users with the 'admin' role
- chainDefinition.addPathDefinition("/admin/**", "authc, roles[admin]");
-
- // logged in users with the 'document:read' permission
- chainDefinition.addPathDefinition("/docs/**", "authc, perms[document:read]");
-
- // all other paths require a logged in user
- chainDefinition.addPathDefinition("/**", "authc");
- return chainDefinition;
-}
-```
-
-If you are using Shiro's annotations see the [annotation](#Spring-annotations-web) section below.
-
-You can see a full example in our [samples on Github](https://github.com/apache/shiro/tree/main/samples/spring-boot-web).
-
-<a name="Spring-annotations"></a>
-Enabling Shiro Annotations
----
-
-In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, `@RequiresRoles`, `@RequiresPermissions`, etc.) These annotations are enabled automatically in both starters listed above.
-
-Simply annotate your methods in order to use them:
-
-``` java
-@RequiresPermissions("document:read")
-public void readDocument() {
- ...
-}
-```
-
-<a name="Spring-annotations-web"></a>
-#[[###]]# Annotations and Web Applications
-
-Shiro annotations are fully supported for use in `@Controller` classes, for example:
-
-``` java
-@Controller
-public class AccountInfoController {
-
- @RequiresRoles("admin")
- @RequestMapping("/admin/config")
- public String adminConfig(Model model) {
- return "view";
- }
-}
-```
-
-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]`.
-
-``` java
-@Bean
-public ShiroFilterChainDefinition shiroFilterChainDefinition() {
- DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
- chainDefinition.addPathDefinition("/**", "anon"); // all paths are managed via annotations
-
- // or allow basic authentication, but NOT require it.
- // chainDefinition.addPathDefinition("/**", "authcBasic[permissive]");
- return chainDefinition;
-}
-```
-
-<a name="Spring-caching"></a>
-# Caching
-
-Enabling caching is as simple as providing a [CacheManager](http://shiro.apache.org/caching.html) bean:
-
-``` java
-@Bean
-protected CacheManager cacheManager() {
- return new MemoryConstrainedCacheManager();
-}
-```
-
-<!-- Work around for table styling until, all pages are updated. -->
-#mdStyle()
-
-# Configuration Properties
-
-| Key | Default Value | Description |
-| --- | ------------- | ----------- |
-| shiro.enabled | `true` | Enables Shiro's Spring module |
-| shiro.web.enabled | `true` | Enables Shiro's Spring web module |
-| shiro.annotations.enabled | `true` | Enables Spring support for Shiro's annotations |
-| shiro.sessionManager.deleteInvalidSessions | `true` | Remove invalid session from session storage |
-| shiro.sessionManager.sessionIdCookieEnabled | `true` | Enable session ID to cookie, for session tracking |
-| shiro.sessionManager.sessionIdUrlRewritingEnabled | `true` | Enable session URL rewriting support |
-| shiro.userNativeSessionManager | `false` | If enabled Shiro will manage the HTTP sessions instead of the container |
-| shiro.sessionManager.cookie.name | `JSESSIONID` | Session cookie name |
-| shiro.sessionManager.cookie.maxAge | `-1` | Session cookie max age |
-| shiro.sessionManager.cookie.domain | null | Session cookie domain |
-| shiro.sessionManager.cookie.path | null | Session cookie path |
-| shiro.sessionManager.cookie.secure | `false` | Session cookie secure flag |
-| shiro.rememberMeManager.cookie.name | `rememberMe` | RememberMe cookie name |
-| shiro.rememberMeManager.cookie.maxAge | one year | RememberMe cookie max age |
-| shiro.rememberMeManager.cookie.domain | null | RememberMe cookie domain|
-| shiro.rememberMeManager.cookie.path | null | RememberMe cookie path|
-| shiro.rememberMeManager.cookie.secure | `false` | RememberMe cookie secure flag|
-| shiro.loginUrl | `/login.jsp` | Login URL used when unauthenticated users are redirected to login page |
-| shiro.successUrl | `/` | Default landing page after a user logs in (if alternative cannot be found in the current session) |
-| shiro.unauthorizedUrl | null | Page to redirect user to if they are unauthorized (403 page) |
-
-<a name="Spring-StandaloneApplications"></a>
-# 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).
-
-#dependencies('cli', [['org.apache.shiro', 'shiro-spring-boot-starter', "${latestRelease}"]])
-
-The only thing that is left is to configure a [realm](realm.html):
-
-``` java
-@Bean
-public Realm realm() {
- ...
-}
-```
-
-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 [Web Applications](#Spring-WebApplications) section below instead.
-
-``` java
-@Autowired
-private SecurityManager securityManager;
-
- @PostConstruct
- private void initStaticSecurityManager() {
- SecurityUtils.setSecurityManager(securityManager);
- }
-```
-
-That is it, now you can get the current `Subject` using:
-
-``` java
-SecurityUtils.getSubject();
-```
-
-You can see a full example in our [samples on Github](https://github.com/apache/shiro/tree/main/samples/spring-boot).
-
-<input type="hidden" id="ghEditPage" value="spring-boot.md.vtl"></input>
diff --git a/spring-framework.md.vtl b/spring-framework.md.vtl
deleted file mode 100644
index 23ea725..0000000
--- a/spring-framework.md.vtl
+++ /dev/null
@@ -1,215 +0,0 @@
-#parse("templates/includes.vtl")
-
-<a name="SpringFramework-IntegratingApacheShirointoSpringbasedApplications"></a>
-Integrating Apache Shiro into Spring-based Applications
-===
-
-This page covers the ways to integrate Shiro into [Spring](http://spring.io)-based applications.
-
-<a name="SpringFramework-StandaloneApplications"></a>
-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).
-
-#dependencies('cli', [['org.apache.shiro', 'shiro-spring', "${latestRelease}"],['org.springframework', 'spring-context', '${spring.version}']])
-
-Import the Shiro Spring configurations:
-
-``` java
-@Configuration
-@Import({ShiroBeanConfiguration.class,
- ShiroConfiguration.class,
- ShiroAnnotationProcessorConfiguration.class})
-public class CliAppConfig {
- ...
-}
-```
-
-The above configurations do the following:
-
-| Configuration Class | Description |
-| ------------------- | ----------- |
-| org.apache.shiro.spring.config.ShiroBeanConfiguration | Configures Shiro's lifecycle and events |
-| org.apache.shiro.spring.config.ShiroConfiguration | Configures Shiro Beans (SecurityManager, SessionManager, etc) |
-| org.apache.shiro.spring.config.ShiroAnnotationProcessorConfiguration | Enables Shiro's annotation processing |
-
-The only thing that is left is to configure a [realm](realm.html):
-
-``` java
-@Bean
-public Realm realm() {
- ...
-}
-```
-
-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 [Web Applications](#Spring-WebApplications) section below instead.
-
-``` java
-@Autowired
-private SecurityManager securityManager;
-
- @PostConstruct
- private void initStaticSecurityManager() {
- SecurityUtils.setSecurityManager(securityManager);
- }
-```
-
-That is it, now you can get the current `Subject` using:
-``` java
-SecurityUtils.getSubject();
-```
-
-You can see a full example in our [samples on Github](https://github.com/apache/shiro/tree/main/samples/spring).
-
-<a name="SpringFramework-WebApplications"></a>
-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).
-
-#dependencies('web', [['org.apache.shiro', 'shiro-spring', "${latestRelease}"], ['org.apache.shiro', 'shiro-web', "${latestRelease}"],['org.springframework', 'spring-webmvc', '${spring.version}']])
-
-<a name="SpringFramework-WebConfig"></a>
-
-Import the Shiro Spring configurations:
-
-``` java
-@Configuration
-@Import({ShiroBeanConfiguration.class,
- ShiroAnnotationProcessorConfiguration.class,
- ShiroWebConfiguration.class,
- ShiroWebFilterConfiguration.class,
- ShiroRequestMappingConfig.class})
-public class ApplicationConfig {
- ...
-}
-```
-
-The above configurations do the following:
-
-| Configuration Class | Description |
-| ------------------- | ----------- |
-| org.apache.shiro.spring.config.ShiroBeanConfiguration | Configures Shiro's lifecycle and events |
-| org.apache.shiro.spring.config.ShiroAnnotationProcessorConfiguration | Enables Shiro's annotation processing |
-| org.apache.shiro.spring.web.config.ShiroWebConfiguration | Configures Shiro Beans for web usage (SecurityManager, SessionManager, etc) |
-| org.apache.shiro.spring.web.config.ShiroWebFilterConfiguration | Configures Shiro's web filter |
-| org.apache.shiro.spring.web.config.ShiroRequestMappingConfig | Configures Spring with Shiro's `UrlPathHelper` implementation to ensure URLs are processed the same both frameworks |
-
-Provide a Realm implementation:
-``` java
-@Bean
-public Realm realm() {
- ...
-}
-```
-
-And finally a `ShiroFilterChainDefinition` which will map any application specific paths to a given filter, in order to allow different paths different levels of access.
-
-``` java
-@Bean
-public ShiroFilterChainDefinition shiroFilterChainDefinition() {
- DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
-
- // logged in users with the 'admin' role
- chainDefinition.addPathDefinition("/admin/**", "authc, roles[admin]");
-
- // logged in users with the 'document:read' permission
- chainDefinition.addPathDefinition("/docs/**", "authc, perms[document:read]");
-
- // all other paths require a logged in user
- chainDefinition.addPathDefinition("/**", "authc");
- return chainDefinition;
-}
-```
-
-If you are using Shiro's annotations see the [annotation](#Spring-annotations-web) section below.
-
-You can see a full example in our [samples on Github](https://github.com/apache/shiro/tree/main/samples/spring-mvc).
-
-<a name="Spring-annotations"></a>
-Enabling Shiro Annotations
----
-
-In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, `@RequiresRoles`, `@RequiresPermissions`, etc.) These annotations are enabled by importing the `ShiroAnnotationProcessorConfiguration` Spring configuration in both sections above.
-
-Simply annotate your methods in order to use them:
-
-``` java
-@RequiresPermissions("document:read")
-public void readDocument() {
- ...
-}
-```
-
-<a name="Spring-annotations-web"></a>
-#[[###]]# Annotations and Web Applications
-
-Shiro annotations are fully supported for use in `@Controller` classes, for example:
-
-``` java
-@Controller
-public class AccountInfoController {
-
- @RequiresRoles("admin")
- @RequestMapping("/admin/config")
- public String adminConfig(Model model) {
- return "view";
- }
-}
-```
-
-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]`.
-
-``` java
-@Bean
-public ShiroFilterChainDefinition shiroFilterChainDefinition() {
- DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
- chainDefinition.addPathDefinition("/**", "anon"); // all paths are managed via annotations
-
- // or allow basic authentication, but NOT require it.
- // chainDefinition.addPathDefinition("/**", "authcBasic[permissive]");
- return chainDefinition;
-}
-```
-
-<a name="Spring-caching"></a>
-# Caching
-
-Enabling caching is as simple as providing a [CacheManager](http://shiro.apache.org/caching.html) bean:
-
-``` java
-@Bean
-protected CacheManager cacheManager() {
- return new MemoryConstrainedCacheManager();
-}
-```
-
-<!-- Work around for table styling until, all pages are updated. -->
-#mdStyle()
-
-# Configuration Properties
-
-| Key | Default Value | Description |
-| --- | ------------- | ----------- |
-| shiro.sessionManager.deleteInvalidSessions | `true` | Remove invalid session from session storage |
-| shiro.sessionManager.sessionIdCookieEnabled | `true` | Enable session ID to cookie, for session tracking |
-| shiro.sessionManager.sessionIdUrlRewritingEnabled | `true` | Enable session URL rewriting support |
-| shiro.userNativeSessionManager | `false` | If enabled Shiro will manage the HTTP sessions instead of the container |
-| shiro.sessionManager.cookie.name | `JSESSIONID` | Session cookie name |
-| shiro.sessionManager.cookie.maxAge | `-1` | Session cookie max age |
-| shiro.sessionManager.cookie.domain | null | Session cookie domain |
-| shiro.sessionManager.cookie.path | null | Session cookie path |
-| shiro.sessionManager.cookie.secure | `false` | Session cookie secure flag |
-| shiro.rememberMeManager.cookie.name | `rememberMe` | RememberMe cookie name |
-| shiro.rememberMeManager.cookie.maxAge | one year | RememberMe cookie max age |
-| shiro.rememberMeManager.cookie.domain | null | RememberMe cookie domain|
-| shiro.rememberMeManager.cookie.path | null | RememberMe cookie path|
-| shiro.rememberMeManager.cookie.secure | `false` | RememberMe cookie secure flag|
-| shiro.loginUrl | `/login.jsp` | Login URL used when unauthenticated users are redirected to login page |
-| shiro.successUrl | `/` | Default landing page after a user logs in (if alternative cannot be found in the current session) |
-| shiro.unauthorizedUrl | null | Page to redirect user to if they are unauthorized (403 page) |
-
-<input type="hidden" id="ghEditPage" value="spring-framework.md.vtl"></input>
diff --git a/templates/macros/dependencies.vtl b/templates/macros/dependencies.vtl
deleted file mode 100644
index 5e6f71d..0000000
--- a/templates/macros/dependencies.vtl
+++ /dev/null
@@ -1,24 +0,0 @@
-#macro(dependencies, $anchorId, $deps)
-
-<ul class="nav nav-tabs">
- <li class="active"><a data-toggle="tab" href="#maven-$anchorId">Apache Maven</a></li>
- <li><a data-toggle="tab" href="#gradle-$anchorId">Gradle</a></li>
-</ul>
-
-<div class="tab-content">
- <div id="maven-$anchorId" class="tab-pane fade in active">
- <pre><code class='xml'>#foreach($item in $deps)<dependency>
- <groupId>$item[0]</groupId>
- <artifactId>$item[1]</artifactId>
- <version>$item[2]</version>
-</dependency>
-#end
-</code></pre>
- </div>
- <div id="gradle-$anchorId" class="tab-pane fade">
- <pre><code class='groovy'>#foreach($item in $deps)
-compile '$item[0]:$item[1]:$item[2]'
-#end</code></pre>
- </div>
-</div>
-#end
\ No newline at end of file
[shiro-site] 06/06: [JBake] convert features.md and
how-to-contribute.md.
Posted by bm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit 3478318443daaf65decd6f6461551d2433e3fdf3
Author: Benjamin Marwell <bm...@apache.org>
AuthorDate: Fri Sep 10 22:24:25 2021 +0200
[JBake] convert features.md and how-to-contribute.md.
---
features.md | 34 -----
jbake/content/features.adoc | 36 +++++
.../content/how-to-contribute.adoc | 148 ++++++++++-----------
3 files changed, 105 insertions(+), 113 deletions(-)
diff --git a/features.md b/features.md
deleted file mode 100644
index f6e7e69..0000000
--- a/features.md
+++ /dev/null
@@ -1,34 +0,0 @@
-title: Features-ApacheShiroFeaturesOverview
-
-#Apache Shiro Features Overview
-
-Apache Shiro aims to be the most comprehensive, but also the easiest to use Java security framework available. Here are some of the frameworks finer points:
-
-* The easiest to understand Java Security API anywhere. Class and Interface names are intuitive and _make sense_. Anything is pluggable but good defaults exist for everything.
-
-* Support [authentication](authentication-features.html) ('logins') across one or more pluggable data sources (LDAP, JDBC, ActiveDirectory, etc).
-
-* Perform [authorization](authorization-features.html) ('access control') based on roles or fine-grained [permissions](permissions.html), also using pluggable data sources.
-
-* First-class [caching](caching.html) support for enhanced application performance.
-
-* Built-in POJO-based Enterprise [Session Management](session-management-features.html). Use in both web and non-web environments or in any environment where Single Sign On (SSO) or clustered or distributed sessions are desired.
-
-* _Heterogeneous_ client session access. You are no longer forced to use only the <tt>httpSession</tt> or Stateful Session Beans, which often unnecessarily tie applications to specific environments. Flash applets, C# applications, Java Web Start, and Web Applications, etc. can now all share session state regardless of deployment environment.
-
-* Simple Single Sign-On (SSO) support piggybacking the above Enterprise Session Management. If sessions are federated across multiple applications, the user's authentication state can be shared too. Log in once to any application and the others all recognize that log-in.
-
-* Secure data with the easiest possible [Cryptography](cryptography-features.html) APIs available, giving you power and simplicity beyond what Java provides by default for ciphers and hashes.
-
-* An incredibly robust yet _low-configuration_ web framework that can secure any url or resource, automatically handle logins and logouts, perform Remember Me services, and more.
-
-* Extremely low number of required dependencies. Standalone configuration requires only <tt>slf4j-api.jar</tt> and one of slf4j's binding .jars. Web configuration additionally requires <tt>commons-beanutils-core.jar</tt>. Feature-based dependencies (Ehcache caching, Quartz-based Session validation, Spring dependency injection, etc.) can be added when needed.
-
-##Want more information on what Shiro can do?
-
-Check out the specific features for each of Shiro's major components: [Authentication](authentication-features.html "Authentication Features"), [Authorization](authorization-features.html "Authorization Features"), [Session Management](session-management-features.html "Session Management Features"), and [Cryptography](cryptography-features.html "Cryptography Features").
-
-##Get Started in 10 Minutes with Shiro
-
-Try out Shiro for yourself with our [10 Minute Tutorial](10-minute-tutorial.html "10 Minute Tutorial"). And if you have any questions about Shiro, please check out our [community forum](forums.html "Forums") or [user mailing list](mailing-lists.html "Mailing Lists") for answers from the community.
-<input type="hidden" id="ghEditPage" value="features.md"></input>
diff --git a/jbake/content/features.adoc b/jbake/content/features.adoc
new file mode 100644
index 0000000..2b145a2
--- /dev/null
+++ b/jbake/content/features.adoc
@@ -0,0 +1,36 @@
+= Apache Shiro Features Overview
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, overview, features
+:idprefix:
+:icons: font
+
+Apache Shiro aims to be the most comprehensive, but also the easiest to use Java security framework available. Here are some of the frameworks finer points:
+
+* The easiest to understand Java Security API anywhere. Class and Interface names are intuitive and _make sense_. Anything is pluggable but good defaults exist for everything.
+
+* Support link:authentication-features.html[authentication] ('logins') across one or more pluggable data sources (LDAP, JDBC, ActiveDirectory, etc).
+
+* Perform link:authorization-features.html[authorization] ('access control') based on roles or fine-grained link:permissions.html[permissions], also using pluggable data sources.
+
+* First-class link:caching.html[caching] support for enhanced application performance.
+
+* Built-in POJO-based Enterprise link:session-management-features.html[Session Management]. Use in both web and non-web environments or in any environment where Single Sign On (SSO) or clustered or distributed sessions are desired.
+
+* _Heterogeneous_ client session access. You are no longer forced to use only the <tt>httpSession</tt> or Stateful Session Beans, which often unnecessarily tie applications to specific environments. Flash applets, C# applications, Java Web Start, and Web Applications, etc. can now all share session state regardless of deployment environment.
+
+* Simple Single Sign-On (SSO) support piggybacking the above Enterprise Session Management. If sessions are federated across multiple applications, the user's authentication state can be shared too. Log in once to any application and the others all recognize that log-in.
+
+* Secure data with the easiest possible link:cryptography-features.html[Cryptography] APIs available, giving you power and simplicity beyond what Java provides by default for ciphers and hashes.
+
+* An incredibly robust yet _low-configuration_ web framework that can secure any url or resource, automatically handle logins and logouts, perform Remember Me services, and more.
+
+* Extremely low number of required dependencies. Standalone configuration requires only <tt>slf4j-api.jar</tt> and one of slf4j's binding .jars. Web configuration additionally requires <tt>commons-beanutils-core.jar</tt>. Feature-based dependencies (Ehcache caching, Quartz-based Session validation, Spring dependency injection, etc.) can be added when needed.
+
+== Want more information on what Shiro can do?
+
+Check out the specific features for each of Shiro's major components: link:authentication-features.html[Authentication], link:authorization-features.html[Authorization], link:session-management-features.html[Session Management], and link:cryptography-features.html[Cryptography].
+
+== 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.
diff --git a/how-to-contribute.md b/jbake/content/how-to-contribute.adoc
similarity index 54%
rename from how-to-contribute.md
rename to jbake/content/how-to-contribute.adoc
index 7562425..29aa566 100644
--- a/how-to-contribute.md
+++ b/jbake/content/how-to-contribute.adoc
@@ -1,19 +1,14 @@
-<a name="HowtoContribute-ContributingtoApacheShiro"></a>
-# Contributing to Apache Shiro
+= Contributing to Apache Shiro
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, overview, features
+:idprefix:
+:icons: font
+:toc:
-* [Introduction](#HowtoContribute-introduction)
-* [Help Wanted Here](#HowtoContribute-help)
-* [Procedure for Raising Development Issues](#HowtoContribute-issues)
-* [Procedure for Reporting Bugs and Issues and Enhancement uggestions](#HowtoContribute-procedure)
-* [Git Usage](#HowtoContribute-git)
-* [Git Committers](#HowtoContribute-committer)
-* [Contribution Notes and Tips](#HowtoContribute-tips)
+== Introduction
-<a name="HowtoContribute-introductions"></a>
-<a name="HowtoContribute-Introduction"></a>
-## Introduction
-
-Apache Shiro is an [Open Source](https://opensource.org/) software security framework that performs authentication, authorization, cryptography and session management. The Shiro Project is an volunteer project released under a [liberal license](license.html "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 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!
There are many ways how to contribute to this project, you can participate directly by:
* coding
@@ -29,163 +24,159 @@ Or you can participate with resource donations:
* conference presentations
* publicity
* software
-* general hardware/money [donations](http://www.apache.org/foundation/thanks.html) via the [Apache Software Foundation](http://www.apache.org)
+* general hardware/money http://www.apache.org/foundation/thanks.html[donations] via the http://www.apache.org[Apache Software Foundation]
-You can get your local working copy of the [latest and greatest code](download.html "Download") by following the directions in [Download](download.html "Download") page. Review the To Do list in the [issue tracker](https://issues.apache.org/jira/browse/SHIRO) and then choose a task that interests you.
+You can get your local working copy of the link:download.html[latest and greatest code] by following the directions in link:download.html[Download] page. Review the To Do list in the https://issues.apache.org/jira/browse/SHIRO[issue tracker] and then choose a task that interests you.
-Perhaps you have noticed something that needs patching or have a new feature to contribute. Make the changes, do the testing, generate a patch, and discuss on the [dev mailing list](https://shiro.apache.org/mailing-lists.html "Mailing Lists"). The process is easy and explained below. Subscribe to the mailing list!
+Perhaps you have noticed something that needs patching or have a new feature to contribute. Make the changes, do the testing, generate a patch, and discuss on the https://shiro.apache.org/mailing-lists.html[dev mailing list]. The process is easy and explained below. Subscribe to the mailing list!
-<a name="HowtoContribute-help"></a>
-<a name="HowtoContribute-HelpWantedHere"></a>
-## Help Wanted
+== Help Wanted
You can be a huge help by providing extra assistance in any of the following areas:
* Assisting to improve documentation and the website.
* Testing Shiro on various configurations and reporting back, especially Shiro's less-frequently-used features.
* New samples for the 'shiro-sample' to concisely describe and demonstrate features. Such samples can also enable automated testing.
-* Debugging - producing reproducible test cases and/or finding causes of bugs. Most bugs are [recorded as issues](#HowtoContribute-procedure)).
+* Debugging - producing reproducible test cases and/or finding causes of bugs. Most bugs are link:#procedure_for_raising_development_issues[recorded as issues].
* Providing new use-cases and requirements.
** If you think that Shiro does not quite meet your needs then tell us about it on the mailing list.
* Specifying, analyzing or designing new features - and beyond.
-** If you wish to get further involved with this, please join the [`shiro-dev` mailing list](https://shiro.apache.org/mailing-lists.html "Mailing Lists"), install and try out Shiro and read some of the [mail archives](https://shiro.apache.org/mailing-lists.html "Mailing Lists").
-*** Don't just say "it should have XYZ" without reading anything first - because chances are, somebody has already thought of that feature.
+** If you wish to get further involved with this, please join the https://shiro.apache.org/mailing-lists.html[`shiro-dev` mailing list], install and try out Shiro and read some of the https://shiro.apache.org/mailing-lists.html[mail archives].
+*** Don't just say "it should have XYZ" without reading anything first - because chances are, somebody has already thought of that feature.
+
* Packaging easy-to-install packages (such as Red Hat Package Managers (RPM)) for the myriad of possible configurations out there.
** The project does not maintain anything but the basic .zip and .tar.gz packages, but anyone is welcome to build their own specific packages and announce those on the mailing list.
-* ... and one more thing - don't forget to tell everyone, how great Shiro is! The more people that know about and start to use Shiro, the larger the pool of potential contributors will be.
+* … and one more thing - don't forget to tell everyone, how great Shiro is! The more people that know about and start to use Shiro, the larger the pool of potential contributors will be.
-<a name="HowtoContribute-procedure"></a>
-<a name="HowtoContribute-Procedureforreportingbugsandissuesandenhancementsuggestions"></a>
-## Procedure for Reporting Bugs and Issues and Enhancement Suggestions
+== Procedure for Reporting Bugs and Issues and Enhancement Suggestions
-If you think that you have found a bug or you have a suggestion for improvement, then please discuss it on one of the [mailing lists](https://shiro.apache.org/mailing-lists.html "Mailing Lists"). However, please check our [issue tracker](https://issues.apache.org/jira/browse/SHIRO) first as it may be already reported.
+If you think that you have found a bug, or you have a suggestion for improvement, then please discuss it on one of the https://shiro.apache.org/mailing-lists.html[mailing lists]. However, please check our https://issues.apache.org/jira/browse/SHIRO[issue tracker] first as it may be already reported.
-The [Apache Shiro Issue Tracker](https://issues.apache.org/jira/browse/SHIRO) collates our known issues. Obviously not every issue is listed there. Some issues have been discussed on the mailing list but do not yet have an issue recorded.
+The https://issues.apache.org/jira/browse/SHIRO[Apache Shiro Issue Tracker] collates our known issues. Obviously not every issue is listed there. Some issues have been discussed on the mailing list but do not yet have an issue recorded.
The Roadmap is the best way to get an overview. The Unscheduled list also needs regular review, and committers will schedule some of those for the next release.
When creating a new issue, please provide a concise Summary Title and a short Description. Add further information as Comments and include links to the mail archives. The normal procedure is to discuss the issue on the mailing list and then add relevant notes to the issue tracker, otherwise it becomes cluttered.
-<a name="HowtoContribute-issues"></a>
-<a name="HowtoContribute-ProcedureforRaisingDevelopmentIssues"></a>
-## Procedure for Raising Development Issues
+== Procedure for Raising Development Issues
There are two methods for discussing development and submitting patches. So that everyone can be productive, it is important to know which method is appropriate for a certain situation and how to go about it without confusion.
-### Mailing List
+=== Mailing List
-Research your topic thoroughly before beginning to discuss a new development issue on the [mailing list](https://shiro.apache.org/mailing-lists.html "Mailing Lists"). Search and browse through the email archives - your issue may have been discussed before. Prepare your post clearly and concisely.
+Research your topic thoroughly before beginning to discuss a new development issue on the https://shiro.apache.org/mailing-lists.html[mailing list]. Search and browse through the email archives - your issue may have been discussed before. Prepare your post clearly and concisely.
Most issues will be discovered, resolved, and then patched quickly via the developer mailing list. Larger issues, and ones that are not yet fully understood or are hard to solve, are destined for the issue tracker.
-### Issue Tracker
+=== Issue Tracker
-Experienced developers use the [issue tracker](https://issues.apache.org/jira/browse/SHIRO) directly, as they are very sure when they have found a bug and when not. Less experienced users should first discuss it on the user or developer mailing list (as appropriate). Impatient people always enter everything into the issue tracker without caring if it is a bug of Shiro, or their own installation/configuration mistake - please do not do this.
+Experienced developers use the https://issues.apache.org/jira/browse/SHIRO[issue tracker] directly, as they are very sure when they have found a bug and when not. Less experienced users should first discuss it on the user or developer mailing list (as appropriate). Impatient people always enter everything into the issue tracker without caring if it is a bug of Shiro, or their own installation/configuration mistake - please do not do this.
Discuss an issue on the developers mailing list first to work out any details. After it is confirmed to be worthwhile, and you are clear about it, then submit the bug description or patch via Bug Tracking.
Perhaps you do not get any answer on your first reply, so just post it again until you get one. But please not every hour - allow a few days for the list to deal with it. Bear in mind that other countries will have holidays at different times to your country and that they are in different time zones. You might also consider rewriting your initial posting. It may have not been clear to the readers on the mailing list.
-<a name="HowtoContribute-submitThroughJira"></a>
-### Submitting a Patch Through Jira
+=== Submitting a Patch Through Jira
While we encourage you to submit your contribution through GitHub pull requests, you can also attach a patch in a Jira ticket. For the purpose of these instructions, we'll assume that you already have a system with Git and have found a bug to fix or have a feature that you'd like to submit, and you're willing to contribute that code or documentation under the Apache License 2.0.
Further, if you're fixing a bug, we'll assume that you've either filed a bug report (where you will attach your patch) or are submitting a fix for a known bug. If you find a bug and would like to fix it, that's awesome! Please be sure to file the bug too, though.
-If you want to add a feature, you should bring it up for discussion on the dev@shiro.apache.org mailing list before implementing it. This ensures that it meshes with the plans that other contributors have for Apache Shiro, and that you're not doing redundant work. Other developers may also have ideas for the feature or suggestions that will help you land the feature without having to re-do the work. More information about our mailing lists can be found here.
+If you want to add a feature, you should bring it up for discussion on the link:mailto:dev@shiro.apache.org[dev@shiro.apache.org] mailing list before implementing it. This ensures that it meshes with the plans that other contributors have for Apache Shiro, and that you're not doing redundant work. Other developers may also have ideas [...]
In short, communication is a vital part of making a contribution to an Apache project.
-<a name="HowtoContribute-git"></a>
-<a name="HowtoContribute-GitUsage"></a>
-## Git Usage
+== Git Usage
-An overview of how to use Git to participate in Shiro development. Beginners, don't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your [...]
+An overview of how to use Git to participate in Shiro development. Beginners, don't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The link:download.html[Download Shiro] page explains how to check out the code base and build your local copy.
-<a name="HowtoContribute-gettingStartedGit"></a>
-### Getting Started with Development
+=== Getting Started with Development
-Go to [Github](https://github.com/apache/shiro "Shiro") 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
+=== Getting Started with Git
Add your name and email to your `~/.gitconfig`:
-``` bash
+[source,bash]
+----
$ git config --global user.name "Your Name"
$ git config --global user.email you@domain.com
-```
+
+----
Obtain a copy of the Shiro source code:
-``` bash
+[source,bash]
+----
$ git clone https://gitbox.apache.org/repos/asf/shiro.git
-```
+
+----
Make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago.
-``` bash
+[source,bash]
+----
$ git checkout -b mybranch
-```
+
+----
This does two things:
* creates the branch mybranch
* changes your working branch to mybranch.
Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch.
-``` bash
+[source,bash]
+----
[user@localhost shiro]$ git branch
main
* mybranch
-```
+----
Use `git add` to stage the changes. Commit the changes to your working branch:
-``` bash
+[source,bash]
+----
git commit -m "Insert a meaningful summary of changes here."
-```
+----
Finally, you can create a patch and attach it to the Jira issue:
-``` bash
+[source,bash]
+----
git format-patch main --stdout > ~/patch-name.patch
-```
+----
* When sending a patch, you usually do not need to worry about which Git branch it should be applied to. The maintainers of the repository will decide.
* Every contribution is worthwhile! Even when the code isn't perfect, or documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve.
-<a name="HowtoContribute-review"></a>
-### Review
-After submitting pull request, you should receive a response within a few days. If you receive no response within a week, please send a message to the shiro-dev mailing list (dev@shiro.apache.org).
+=== Review
+
+After submitting pull request, you should receive a response within a few days. If you receive no response within a week, please send a message to the shiro-dev mailing list (link:mailto:dev@shiro.apache.org)[dev@shiro.apache.org)].
-<a name="HowtoContribute-committer"></a>
-<a name="HowtoContribute-GitCommitters"></a>
-## Git Committers
+== Git Committers
-After a developer has consistently provided contributions such as code, documentation and discussion, and demonstrated commitment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the [ASF developers resources](http://www.apache.org/dev/) and especially the [Source code repositories](http://www.apache.org/dev/version-control.html).
+After a developer has consistently provided contributions such as code, documentation and discussion, and demonstrated commitment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the http://www.apache.org/dev/[ASF developers resources] and especially the http://www.apache.org/dev/version-control.html[Source code repositories].
-<a name="HowtoContribute-patches"></a>
-<a name="HowtoContribute-Howtoprepareandcontributepatches"></a>
-## Contributing as a Non-Committer
+== Contributing as a Non-Committer
Non-committers have to submit patches for review. Apache Shiro accepts GitHub pull requests.
-Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. For detailed instructions see the [GitHub Contribution Guidelines](https://github.com/apache/shiro/blob/master/CONTRIBUTING.md).
+Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. For detailed instructions see the https://github.com/apache/shiro/blob/master/CONTRIBUTING.md[GitHub Contribution Guidelines].
-<a name="HowtoContribute-tips"></a>
-<a name="HowtoContribute-ContributionNotesandTips"></a>
-## Contribution Notes and Tips
+== Contribution Notes and Tips
This is a collection of tips for contributing to the project in a manner that is productive for all parties.
-### Links
-* [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html).
-* Old questions and answers in [archives](https://shiro.apache.org/mailing-lists.html "Mailing Lists").
+=== Links
+
+* http://www.apache.org/dev/contrib-email-tips.html[Tips for email contributors].
+* Old questions and answers in https://shiro.apache.org/mailing-lists.html[archives].
There are no dumb questions. But browse, search and learn from mailing list archives. Research your topic thoroughly before beginning to discuss a new development issue.
-### Emails
+=== Emails
+
* Start new threads with new Subject for new topics, rather than reusing the previous Subject line. Use a descriptive title!
** Clearly explain your issue and write a concise email message.
* Try to at least offer a partial solution and not just a problem statement.
@@ -194,5 +185,4 @@ There are no dumb questions. But browse, search and learn from mailing list arch
** [RT] (Random Thought which quickly blossom into research topics)
** [STATUS] (development status of a certain facility)
-Reduce clutter, don't send an e-mail which simply says "thanks". Keep all project-related discussion on the mailing list. It is better to utilize the wider audience, rather than to break off into private discussions. You never know who else will have the answer to your issues, and anyway other people are interested in the outcome.
-<input type="hidden" id="ghEditPage" value="how-to-contribute.md"></input>
+Reduce clutter, don't send an e-mail which simply says "thanks". Keep all project-related discussion on the mailing list. It is better to utilize the wider audience, rather than to break off into private discussions. You never know who else will have the answer to your issues, and anyway other people are interested in the outcome.