This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch asf-staging-jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
The following commit(s) were added to refs/heads/asf-staging-jbake by this push:
new 76158ff preview 2022-01-13
76158ff is described below
commit 76158ffdcd8482cb1084356f8a2740c07f341710
Author: Benjamin Marwell <[email protected]>
AuthorDate: Thu Jan 13 23:15:44 2022 +0100
preview 2022-01-13
---
feed.xml | 4 +-
sitemap.xml | 4 +
tutorial.html | 837 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 843 insertions(+), 2 deletions(-)
diff --git a/feed.xml b/feed.xml
index 34d1c74..7cf01f5 100644
--- a/feed.xml
+++ b/feed.xml
@@ -6,8 +6,8 @@
<atom:link href="https://shiro-jbake.staged.apache.org/feed.xml";
rel="self" type="application/rss+xml" />
<description>JBake Bootstrap Template</description>
<language>en-gb</language>
- <pubDate>Do., 13 Jan. 2022 22:48:16 +0100</pubDate>
- <lastBuildDate>Do., 13 Jan. 2022 22:48:16 +0100</lastBuildDate>
+ <pubDate>Do., 13 Jan. 2022 23:13:36 +0100</pubDate>
+ <lastBuildDate>Do., 13 Jan. 2022 23:13:36 +0100</lastBuildDate>
<item>
<title>Apache Shiro v1.8.0 released</title>
diff --git a/sitemap.xml b/sitemap.xml
index 1071c3b..2d2ae85 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -1,6 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9
http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd";>
<url>
+ <loc>https://shiro-jbake.staged.apache.org/tutorial.html</loc>
+ <lastmod>2022-01-13</lastmod>
+ </url>
+ <url>
<loc>https://shiro-jbake.staged.apache.org/session-management.html</loc>
<lastmod>2022-01-09</lastmod>
</url>
diff --git a/tutorial.html b/tutorial.html
new file mode 100644
index 0000000..d47ac5b
--- /dev/null
+++ b/tutorial.html
@@ -0,0 +1,837 @@
+<!DOCTYPE html>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html lang="en">
+ <head>
+ <meta charset="utf-8"/>
+ <title>Apache Shiro Tutorial | Apache Shiro</title>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <meta name="keywords" content='documentation,tutorial'>
+ <meta name="generator" content="JBake">
+ <meta name="google-site-verification"
content="QIax6uT5UX3enoU0G8Pz2pXbQ45KaQuHZ3nCh9V27mw">
+ <meta name="google-site-verification"
content="ecFap6dWJgS_GCCtxmJQJ_nFYQhM6EgSpBPZDU7xsCE">
+ <meta name="google-site-verification"
content="gBTYOG8lMfNb_jrWrH3kFbudpEs_WrAJ2lb2-zLRaso"/>
+ <meta name="msvalidate.01" content="0B57EB46CBFAD8FD45008D2DB6B6C68C">
+
+ <meta property="og:title" content="Apache Shiro Tutorial | Apache Shiro"/>
+ <meta property="og:type" content="article"/>
+ <meta name="twitter:card" content="summary" />
+ <meta name="twitter:site" content="@ApacheShiro" />
+ <meta property="article:modification_time" content="2022-01-13"/>
+ <meta property="article:tag" content='documentation'/>
+ <meta property="article:tag" content='tutorial'/>
+ <meta property="og:locale" content="en_US" />
+ <meta property="og:url"
content='https://shiro-jbake.staged.apache.org/tutorial.html'/>
+ <meta property="og:image" content='img/shiro-featured-image.png'/>
+ <meta property="og:image:width" content='1200'/>
+ <meta property="og:image:height" content='628'/>
+ <meta property="og:site_name" content="Apache Shiro"/>
+
+ <!-- Le styles -->
+ <link href="css/bootstrap.min.css" rel="stylesheet">
+ <link href="bootstrap-icons-1.5.0/bootstrap-icons.css" rel="stylesheet">
+ <link href="css/asciidoctor.css" rel="stylesheet">
+ <link href="css/base.css" rel="stylesheet">
+ <link href="highlight.js-11.2.0/styles/default.min.css" rel="stylesheet">
+ <link href="css/gh-pages/gh-fork-ribbon.css" rel="stylesheet"/>
+
+ <!-- Fav and touch icons -->
+ <!--<link rel="apple-touch-icon-precomposed" sizes="144x144"
href="../assets/ico/apple-touch-icon-144-precomposed.png">
+ <link rel="apple-touch-icon-precomposed" sizes="114x114"
href="../assets/ico/apple-touch-icon-114-precomposed.png">
+ <link rel="apple-touch-icon-precomposed" sizes="72x72"
href="../assets/ico/apple-touch-icon-72-precomposed.png">
+ <link rel="apple-touch-icon-precomposed"
href="../assets/ico/apple-touch-icon-57-precomposed.png">-->
+ <link rel="shortcut icon" href="favicon.ico">
+ </head>
+ <body>
+ <div id="top-bar"></div>
+ <a class="github-fork-ribbon right-top"
href="https://github.com/apache/shiro"; title="Fork me on GitHub">Fork me on
GitHub</a>
+
+ <div id="wrap">
+
+ <div class="masthead">
+ <p class="lead">
+ <a href="index.html"><img src="img/apache-shiro-logo.png"
style="height:100px; width:auto; vertical-align: bottom; margin-top: 20px;"
alt="Apache Shiro Logo"></a>
+ <span class="tagline">Simple. Java. Security.</span>
+ <a class="pull-right"
href="https://www.apache.org/events/current-event.html";>
+ <img style="padding-top: 8px"
src="https://www.apache.org/events/current-event-125x125.png"; alt="Apache
Software Foundation Event Banner"/>
+ </a>
+ </p>
+ </div>
+
+ <!-- Fixed navbar -->
+ <nav class="navbar navbar-expand-lg navbar-light bg-light shadow-sm mb-4">
+ <div class="container-fluid">
+ <button class="navbar-toggler" type="button" data-bs-toggle="collapse"
data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
+ <span class="navbar-toggler-icon"></span>
+ </button>
+
+ <div class="collapse navbar-collapse" id="navbarSupportedContent">
+ <ul class="navbar-nav me-auto mb-2 mb-lg-0">
+ <li class="nav-item">
+ <a class="nav-link" href="get-started.html">Get Started</a>
+ </li>
+ <li class="nav-item">
+ <a class="nav-link" href="documentation.html">Docs</a>
+ </li>
+
+ <li class="nav-item dropdown">
+ <a class="nav-link dropdown-toggle" href="#"
id="navbarDropdown-webapps" role="button" data-bs-toggle="dropdown"
aria-expanded="false">
+ Web Apps
+ </a>
+ <ul class="dropdown-menu"
aria-labelledby="navbarDropdown-webapps">
+ <li><a class="dropdown-item" href="web.html">General</a></li>
+ <li><a class="dropdown-item" href="jaxrs.html">JAX-RS</a></li>
+ <li><hr class="dropdown-divider"></li>
+ <li><a class="dropdown-item"
href="web-features.html">Features</a></li>
+ </ul>
+ </li>
+
+ <li><a class="nav-link" href="features.html">Features</a></li>
+
+ <!-- integrations -->
+ <li class="nav-item dropdown">
+ <a class="nav-link dropdown-toggle" href="#"
id="navbarDropdown-integrations" role="button" data-bs-toggle="dropdown"
aria-expanded="false">
+ Integrations
+ </a>
+ <ul class="dropdown-menu"
aria-labelledby="navbarDropdown-integrations">
+ <li><a class="dropdown-item"
href="spring-boot.html">Spring</a></li>
+ <li><a class="dropdown-item" href="guice.html">Guice</a></li>
+ <li><hr class="dropdown-divider"></li>
+ <li><a class="dropdown-item"
href="integration.html">Third-Party Integrations</a></li>
+ </ul>
+ </li>
+
+ <!-- Community -->
+ <li class="nav-item dropdown">
+ <a class="nav-link dropdown-toggle" href="#"
id="navbarDropdown-community" role="button" data-bs-toggle="dropdown"
aria-expanded="false">
+ Community
+ </a>
+ <ul class="dropdown-menu"
aria-labelledby="navbarDropdown-community">
+ <li><a class="dropdown-item" href="forums.html">Community
Forums</a></li>
+ <li><a class="dropdown-item" href="mailing-lists.html">Mailing
Lists</a></li>
+ <li><a class="dropdown-item"
href="articles.html">Articles</a></li>
+ <li><a class="dropdown-item" href="news.html">News</a></li>
+ <li><a class="dropdown-item" href="events.html">Events</a></li>
+ <li><hr class="dropdown-divider"></li>
+ <li><a class="dropdown-item"
href="community.html">More</a></li>
+ </ul>
+ </li>
+
+ <!-- About -->
+ <li class="nav-item dropdown">
+ <a class="nav-link dropdown-toggle" href="#"
id="navbarDropdown-about" role="button" data-bs-toggle="dropdown"
aria-expanded="false">
+ About
+ </a>
+ <ul class="dropdown-menu" aria-labelledby="navbarDropdown-about">
+ <li><a class="dropdown-item" href="about.html">About</a></li>
+ <li><a class="dropdown-item"
href="security-reports.html">Vulnerability Reports</a></li>
+ </ul>
+ </li>
+ </ul>
+
+ <ul class="d-flex justify-content-end navbar-nav mb-2 mb-lg-0">
+ <!-- The ASF -->
+ <li class="nav-item dropdown">
+ <a class="nav-link dropdown-toggle" href="#"
id="navbarDropdown-asf" role="button" data-bs-toggle="dropdown"
aria-expanded="false">
+ Apache Software Foundation
+ </a>
+ <ul class="dropdown-menu" aria-labelledby="navbarDropdown-asf">
+ <li><a class="dropdown-item"
href="http://www.apache.org/";>Apache Homepage</a></li>
+ <li><a class="dropdown-item"
href="http://www.apache.org/licenses/";>License</a></li>
+ <li><a class="dropdown-item"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li>
+ <li><a class="dropdown-item"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li>
+ <li><a class="dropdown-item"
href="http://www.apache.org/security/";>Security</a></li>
+ </ul>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </nav>
+
+ <div class="page-header">
+ <h1>Apache Shiro Tutorial</h1>
+ </div>
+
+
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel1">
+<li><a href="#your_first_apache_shiro_application">Your First Apache Shiro
Application</a></li>
+<li><a href="#setup">Setup</a></li>
+<li><a href="#the_tutorial_class">The Tutorial class</a></li>
+<li><a href="#test_run">Test Run</a></li>
+<li><a href="#enable_shiro">Enable Shiro</a></li>
+<li><a href="#configuration">Configuration</a>
+<ul class="sectlevel2">
+<li><a href="#shiro_ini"><code>shiro.ini</code></a></li>
+<li><a href="#referencing_the_configuration">Referencing the
Configuration</a></li>
+</ul>
+</li>
+<li><a href="#using_shiro">Using Shiro</a></li>
+<li><a href="#final_tutorial_class">Final Tutorial class</a></li>
+<li><a href="#summary">Summary</a></li>
+</ul>
+</div>
+<div class="sect1">
+<h2 id="your_first_apache_shiro_application">Your First Apache Shiro
Application</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>If you’re new to Apache Shiro, this short tutorial will show you how
to set up an initial and very simple application secured by Apache Shiro.
We’ll discuss Shiro’s core concepts along the way to help
familiarize you with Shiro’s design and API.</p>
+</div>
+<div class="paragraph">
+<p>If you don’t want to actually edit files as you follow this tutorial,
you can obtain a nearly identical sample application and reference it as you
go. Choose a location:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>In Apache Shiro’s Git repository: <a
href="https://github.com/apache/shiro/tree/main/samples/quickstart";
class="bare">https://github.com/apache/shiro/tree/main/samples/quickstart</a></p>
+</li>
+<li>
+<p>In Apache Shiro’s source distribution’s
<code>samples/quickstart</code> directory. The source distribution is available
from the <a href="download.html">Download</a> page.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="setup">Setup</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>In this simple example, we’ll create a very simple command-line
application that will run and quickly exit, just so you can get a feel for
Shiro’s API.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="title">Any Application</div>
+<div class="paragraph">
+<p>Apache Shiro was designed from day one to support <em>any</em> application
- from the smallest command-line applications to the largest clustered web
applications. Even though we’re creating a simple app for this tutorial,
know that the same usage patterns apply no matter how your application is
created or where it is deployed</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>This tutorial requires Java 8 or later. We’ll also be using Apache <a
href="http://maven.apache.org";>Maven</a> as our build tool, but of course this
is not required to use Apache Shiro. You may acquire Shiro’s .jars and
incorporate them in any way you like into your application, for example maybe
using Apache <a href="http://ant.apache.org";>Ant</a> and <a
href="http://ant.apache.org/ivy";>Ivy</a>.</p>
+</div>
+<div class="paragraph">
+<p>For this tutorial, please ensure that you are using Maven 3.6.3 or later.
You should be able to type <code>mvn --version</code> in a command prompt and
see something similar to the following:</p>
+</div>
+<div class="listingblock">
+<div class="title">Testing Maven Installation</div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-bash hljs"
data-lang="bash">hazlewood:~/shiro-tutorial$ mvn --version
+Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
+Maven home: /home/bmarwell/.sdkman/candidates/maven/current
+Java version: 1.8.0_312, vendor: International Business Machines Corporation,
runtime: /home/bmarwell/.sdkman/candidates/java/8.0.312-sem/jre
+Default locale: de_DE, platform encoding: UTF-8
+OS name: "linux", version: "5.10.89-1-manjaro", arch: "amd64", family:
"unix"</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>For now, create a new directory on your filesystem, for example,
<strong><code>shiro-tutorial</code></strong> and save the following Maven
<strong><code>pom.xml</code></strong> file in that directory:</p>
+</div>
+<div class="listingblock">
+<div class="title">pom.xml</div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs"
data-lang="xml"><?xml version="1.0" encoding="UTF-8"?>
+ <project xmlns="http://maven.apache.org/POM/4.0.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.shiro.tutorials</groupId>
+ <artifactId>shiro-tutorial</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <name>First Apache Shiro Application</name>
+ <packaging>jar</packaging>
+
+ <properties>
+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ </properties>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.8.0</version>
+ <configuration>
+ <source>1.8</source>
+ <target>1.8</target>
+ </configuration>
+ </plugin>
+
+ <!-- This plugin is only to test run our little application. It is
not
+ needed in most Shiro-enabled applications: -->
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>exec-maven-plugin</artifactId>
+ <version>1.1</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>java</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <classpathScope>test</classpathScope>
+ <mainClass>Tutorial</mainClass>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-core</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+ <!-- Shiro uses SLF4J for logging. We'll use the 'simple' binding
+ in this example app. See http://www.slf4j.org for more info.
-->
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-simple</artifactId>
+ <version>1.7.21</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>jcl-over-slf4j</artifactId>
+ <version>1.7.21</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+</project></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="the_tutorial_class">The Tutorial class</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>We’ll be running a simple command-line application, so we’ll
need to create a Java class with a <code>public static void main(String[]
args)</code> method.</p>
+</div>
+<div class="paragraph">
+<p>In the same directory containing your <code>pom.xml</code> file, create a
*<code>src/main/java</code> sub directory. In <code>src/main/java</code> create
a <code>Tutorial.java</code> file with the following contents:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/main/java/Tutorial.java</div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">import org.apache.shiro.SecurityUtils;
+import org.apache.shiro.authc.*;
+import org.apache.shiro.config.IniSecurityManagerFactory;
+import org.apache.shiro.mgt.SecurityManager;
+import org.apache.shiro.session.Session;
+import org.apache.shiro.subject.Subject;
+import org.apache.shiro.util.Factory;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class Tutorial {
+
+ private static final transient Logger log =
LoggerFactory.getLogger(Tutorial.class);
+
+ public static void main(String[] args) {
+ log.info("My First Apache Shiro Application");
+ System.exit(0);
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Don’t worry about the import statements for now - we’ll get to
them shortly. But for now, we’ve got a typical command line program
'shell'. All this program will do is print out the text "My First Apache Shiro
Application" and exit.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="test_run">Test Run</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>To try our Tutorial application, execute the following in a command prompt
in your tutorial project’s root dirctory (e.g.
<code>shiro-tutorial</code>), and type the following:</p>
+</div>
+<div class="paragraph">
+<p><code>mvn compile exec:java</code></p>
+</div>
+<div class="paragraph">
+<p>And you will see our little Tutorial 'application' run and exit. You should
see something similar to the following (notice the bold text, indicating our
output):</p>
+</div>
+<div class="paragraph">
+<p><strong>Run the Application</strong></p>
+</div>
+<div class="paragraph">
+<p>We’ve verified the application runs successfully - now let’s
enable Apache Shiro. As we continue with the tutorial, you can run <code>mvn
compile exec:java</code> after each time we add some more code to see the
results of our changes.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="enable_shiro">Enable Shiro</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The first thing to understand in enabling Shiro in an application is that
almost everything in Shiro is related to a central/core component called the
<code>SecurityManager</code>. For those familiar with Java security, this is
Shiro’s notion of a SecurityManager - it is <em>NOT</em> the same thing
as the <code>java.lang.SecurityManager</code>.</p>
+</div>
+<div class="paragraph">
+<p>While we will cover Shiro’s design in detail in the <a
href="architecture.html">Architecture</a> chapter, it is good enough for now to
know that the Shiro <code>SecurityManager</code> is the core of a Shiro
environment for an application and one <code>SecurityManager</code> must exist
per application. So, the first thing we must do in our Tutorial application is
set-up the <code>SecurityManager</code> instance.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="configuration">Configuration</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>While we could instantiate a <code>SecurityManager</code> class directly,
Shiro’s <code>SecurityManager</code> implementations have enough
configuration options and internal components that make this a pain to do in
Java source code - it would be much easier to configure the
<code>SecurityManager</code> with a flexible text-based configuration
format.</p>
+</div>
+<div class="paragraph">
+<p>To that end, Shiro provides a default ‘common denominator’ solution via
text-based <a href="https://en.wikipedia.org/wiki/INI_file";>INI</a>
configuration. People are pretty tired of using bulky XML files these days, and
INI is easy to read, simple to use, and requires very few dependencies. You’ll
also see later that with a simple understanding of object graph navigation, INI
can be used effectively to configure simple object graphs like the
SecurityManager.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="title">Many Configuration Options</div>
+<div class="paragraph">
+<p>Shiro’s <code>SecurityManager</code> implementations and all
supporting components are all JavaBeans compatible. This allows Shiro to be
configured with practically any configuration format such as XML (Spring,
JBoss, Guice, etc), <a href="http://www.yaml.org/";>YAML</a>, JSON, Groovy
Builder markup, and more. INI is just Shiro’s 'common denominator' format
that allows configuration in any environment in case other options are not
available.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect2">
+<h3 id="shiro_ini"><code>shiro.ini</code></h3>
+<div class="paragraph">
+<p>So we’ll use an INI file to configure the Shiro
<code>SecurityManager</code> for this simple application. First, create a
<strong><code>src/main/resources</code></strong> directory starting in the same
directory where the <code>pom.xml</code> is. Then create a
<code>shiro.ini</code> file in that new directory with the following
contents:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/main/resources/shiro.ini</div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-ini hljs"
data-lang="ini">#
=============================================================================
+# Tutorial INI configuration
+#
+# Usernames/passwords are based on the classic Mel Brooks' film "Spaceballs" :)
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Users and their (optional) assigned roles
+# username = password, role1, role2, ..., roleN
+# -----------------------------------------------------------------------------
+[users]
+root = secret, admin
+guest = guest, guest
+presidentskroob = 12345, president
+darkhelmet = ludicrousspeed, darklord, schwartz
+lonestarr = vespa, goodguy, schwartz
+
+# -----------------------------------------------------------------------------
+# Roles with assigned permissions
+# roleName = perm1, perm2, ..., permN
+# -----------------------------------------------------------------------------
+[roles]
+admin = *
+schwartz = lightsaber:*
+goodguy = winnebago:drive:eagle5</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As you see, this configuration basically sets up a small set of static user
accounts, good enough for our first application. In later chapters, you will
see how we can use more complex User data sources like relational databases,
LDAP and ActiveDirectory, and more.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="referencing_the_configuration">Referencing the Configuration</h3>
+<div class="paragraph">
+<p>Now that we have an INI file defined, we can create the
<code>SecurityManager</code> instance in our Tutorial application class. Change
the <code>main</code> method to reflect the following updates:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">public static void main(String[] args) {
+
+ log.info("My First Apache Shiro Application");
+
+ //1.
+ Factory<SecurityManager> factory = new
IniSecurityManagerFactory("classpath:shiro.ini");
+
+ //2.
+ SecurityManager securityManager = factory.getInstance();
+
+ //3.
+ SecurityUtils.setSecurityManager(securityManager);
+
+ System.exit(0);
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>And there we go - Shiro is enabled in our sample application after adding
only 3 lines of code! How easy was that?</p>
+</div>
+<div class="paragraph">
+<p>Feel free to run <code>mvn compile exec:java</code> and see that everything
still runs successfully (due to Shiro’s default logging of debug or
lower, you won’t see any Shiro log messages - if it starts and runs
without error, then you know everything is still ok).</p>
+</div>
+<div class="paragraph">
+<p>Here is what the above additions are doing:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>We use Shiro’s <code>IniSecurityManagerFactory</code> implementation
to ingest our <code>shiro.ini</code> file which is located at the root of the
classpath. This implementation reflects Shiro’s support of the <a
href="https://en.wikipedia.org/wiki/Factory_method_pattern";>Factory Method
Design Pattern</a>. The <code>classpath:</code> prefix is an resource indicator
that tells shiro where to load the ini file from (other prefixes, like
<code>url:</code> and <code>file:</cod [...]
+</li>
+<li>
+<p>The <code>factory.getInstance()</code> method is called, which parses the
INI file and returns a <code>SecurityManager</code> instance reflecting the
configuration.</p>
+</li>
+<li>
+<p>In this simple example, we set the <code>SecurityManager</code> to be a
<em>static</em> (memory) singleton, accessible across the JVM. Note however
that this is not desireable if you will ever have more than one Shiro-enabled
application in a single JVM. For this simple example, it is ok, but more
sophisticated application environments will usually place the
<code>SecurityManager</code> in application-specific memory (such as in a web
app’s <code>ServletContext</code> or a Sprin [...]
+</li>
+</ol>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="using_shiro">Using Shiro</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Now that our SecurityManager is set-up and ready-to go, now we can start
doing the things we really care about - performing security operations.</p>
+</div>
+<div class="paragraph">
+<p>When securing our applications, probably the most relevant questions we ask
ourselves are “Who is the current user?” or “Is the current user allowed to do
X”? It is common to ask these questions as we’re writing code or
designing user interfaces: applications are usually built based on user
stories, and you want functionality represented (and secured) based on a
per-user basis. So, the most natural way for us to think about security in our
application is based on the current use [...]
+</div>
+<div class="paragraph">
+<p>In almost all environments, you can obtain the currently executing user via
the following call:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">Subject currentUser = SecurityUtils.getSubject();</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Using <a
href="static/current/apidocs/org/apache/shiro/SecurityUtils.html"><code>SecurityUtils</code></a>.<a
href="static/current/apidocs/org/apache/shiro/SecurityUtils.html#getSubject--">getSubject()</a>,
we can obtain the currently executing <a
href="static/current/apidocs/org/apache/shiro/subject/Subject.html"><code>Subject</code></a>.
<em>Subject</em> is a security term that basically means "a security-specific
view of the currently executing user". It is not called a 'User' becau [...]
+</div>
+<div class="paragraph">
+<p>The <code>getSubject()</code> call in a standalone application might return
a <code>Subject</code> based on user data in an application-specific location,
and in a server environment (e.g. web app), it acquires the
<code>Subject</code> based on user data associated with current thread or
incoming request.</p>
+</div>
+<div class="paragraph">
+<p>Now that you have a <code>Subject</code>, what can you do with it?</p>
+</div>
+<div class="paragraph">
+<p>If you want to make things available to the user during their current
session with the application, you can get their session:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">Session session = currentUser.getSession();
+session.setAttribute( "someKey", "aValue" );</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The <code>Session</code> is a Shiro-specific instance that provides most of
what you’re used to with regular HttpSessions but with some extra goodies
and one <strong>big</strong> difference: it does not require an HTTP
environment!</p>
+</div>
+<div class="paragraph">
+<p>If deploying inside a web application, by default the <code>Session</code>
will be <code>HttpSession</code> based. But, in a non-web environment, like
this simple tutorial application, Shiro will automatically use its Enterprise
Session Management by default. This means you get to use the same API in your
applications, in any tier, regardless of deployment environment! This opens a
whole new world of applications since any application requiring sessions does
not need to be forced to u [...]
+</div>
+<div class="paragraph">
+<p>So now you can acquire a <code>Subject</code> and their
<code>Session</code>. What about the <em>really</em> useful stuff like checking
if they are allowed to do things, like checking against roles and
permissions?</p>
+</div>
+<div class="paragraph">
+<p>Well, we can only do those checks for a known user. Our
<code>Subject</code> instance above represents the current user, but
<em>who</em> is the current user? Well, they’re anonymous - that is,
until they log in at least once. So, let’s do that:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">if ( !currentUser.isAuthenticated() ) {
+ //collect user principals and credentials in a gui specific manner
+ //such as username/password html form, X509 certificate, OpenID, etc.
+ //We'll use the username/password example here since it is the most common.
+ UsernamePasswordToken token = new UsernamePasswordToken("lonestarr",
"vespa");
+
+ //this is all you have to do to support 'remember me' (no config - built
in!):
+ token.setRememberMe(true);
+
+ currentUser.login(token);
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>That’s it! It couldn’t be easier.</p>
+</div>
+<div class="paragraph">
+<p>But what if their login attempt fails? You can catch all sorts of specific
exceptions that tell you exactly what happened and allows you to handle and
react accordingly:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">try {
+ currentUser.login( token );
+ //if no exception, that's it, we're done!
+} catch ( UnknownAccountException uae ) {
+ //username wasn't in the system, show them an error message?
+} catch ( IncorrectCredentialsException ice ) {
+ //password didn't match, try again?
+} catch ( LockedAccountException lae ) {
+ //account for that username is locked - can't login. Show them a message?
+}
+ ... more types exceptions to check if you want ...
+} catch ( AuthenticationException ae ) {
+ //unexpected condition - error?
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>There are many different types of exceptions you can check, or throw your
own for custom conditions Shiro might not account for. See the <a
href="/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html">AuthenticationException
JavaDoc</a> for more.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Security best practice is to give generic login failure messages to users
because you do not want to aid an attacker trying to break into your system.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>Ok, so by now, we have a logged in user.
+What else can we do?</p>
+</div>
+<div class="paragraph">
+<p>Let’s say who they are:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">//print their identifying principal (in this case, a username):
+log.info( "User [" + currentUser.getPrincipal() + "] logged in successfully."
);</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>We can also test to see if they have specific role or not:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">if ( currentUser.hasRole( "schwartz" ) ) {
+ log.info("May the Schwartz be with you!" );
+} else {
+ log.info( "Hello, mere mortal." );
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>We can also see if they have a permission to act on a certain type of
entity:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">if ( currentUser.isPermitted( "lightsaber:wield" ) ) {
+ log.info("You may use a lightsaber ring. Use it wisely.");
+} else {
+ log.info("Sorry, lightsaber rings are for schwartz masters only.");
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Also, we can perform an extremely powerful <em>instance-level</em>
permission check - the ability to see if the user has the ability to access a
specific instance of a type:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">if ( currentUser.isPermitted( "winnebago:drive:eagle5" ) ) {
+ log.info("You are permitted to 'drive' the 'winnebago' with license plate
(id) 'eagle5'. " +
+ "Here are the keys - have fun!");
+} else {
+ log.info("Sorry, you aren't allowed to drive the 'eagle5' winnebago!");
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Piece of cake, right?</p>
+</div>
+<div class="paragraph">
+<p>Finally, when the user is done using the application, they can log out:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">//removes all identifying information and invalidates their
session too.
+currentUser.logout();</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="final_tutorial_class">Final Tutorial class</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>After adding in the above code examples, here is our final Tutorial class
file. Feel free to edit and play with it and change the security checks (and
the INI configuration) as you like:</p>
+</div>
+<div class="listingblock">
+<div class="title">Final src/main/java/Tutorial.java</div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">import org.apache.shiro.SecurityUtils;
+import org.apache.shiro.authc.*;
+import org.apache.shiro.config.IniSecurityManagerFactory;
+import org.apache.shiro.mgt.SecurityManager;
+import org.apache.shiro.session.Session;
+import org.apache.shiro.subject.Subject;
+import org.apache.shiro.util.Factory;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class Tutorial {
+
+ private static final transient Logger log =
LoggerFactory.getLogger(Tutorial.class);
+
+ public static void main(String[] args) {
+ log.info("My First Apache Shiro Application");
+
+ Factory<SecurityManager> factory = new
IniSecurityManagerFactory("classpath:shiro.ini");
+ SecurityManager securityManager = factory.getInstance();
+ SecurityUtils.setSecurityManager(securityManager);
+
+ // get the currently executing user:
+ Subject currentUser = SecurityUtils.getSubject();
+
+ // Do some stuff with a Session (no need for a web or EJB container!!!)
+ Session session = currentUser.getSession();
+ session.setAttribute("someKey", "aValue");
+ String value = (String) session.getAttribute("someKey");
+ if (value.equals("aValue")) {
+ log.info("Retrieved the correct value! [" + value + "]");
+ }
+
+ // let's login the current user so we can check against roles and
permissions:
+ if (!currentUser.isAuthenticated()) {
+ UsernamePasswordToken token = new
UsernamePasswordToken("lonestarr", "vespa");
+ token.setRememberMe(true);
+ try {
+ currentUser.login(token);
+ } catch (UnknownAccountException uae) {
+ log.info("There is no user with username of " +
token.getPrincipal());
+ } catch (IncorrectCredentialsException ice) {
+ log.info("Password for account " + token.getPrincipal() + "
was incorrect!");
+ } catch (LockedAccountException lae) {
+ log.info("The account for username " + token.getPrincipal() +
" is locked. " +
+ "Please contact your administrator to unlock it.");
+ }
+ // ... catch more exceptions here (maybe custom ones specific to
your application?
+ catch (AuthenticationException ae) {
+ //unexpected condition? error?
+ }
+ }
+
+ //say who they are:
+ //print their identifying principal (in this case, a username):
+ log.info("User [" + currentUser.getPrincipal() + "] logged in
successfully.");
+
+ //test a role:
+ if (currentUser.hasRole("schwartz")) {
+ log.info("May the Schwartz be with you!");
+ } else {
+ log.info("Hello, mere mortal.");
+ }
+
+ //test a typed permission (not instance-level)
+ if (currentUser.isPermitted("lightsaber:wield")) {
+ log.info("You may use a lightsaber ring. Use it wisely.");
+ } else {
+ log.info("Sorry, lightsaber rings are for schwartz masters only.");
+ }
+
+ //a (very powerful) Instance Level permission:
+ if (currentUser.isPermitted("winnebago:drive:eagle5")) {
+ log.info("You are permitted to 'drive' the winnebago with license
plate (id) 'eagle5'. " +
+ "Here are the keys - have fun!");
+ } else {
+ log.info("Sorry, you aren't allowed to drive the 'eagle5'
winnebago!");
+ }
+
+ //all done - log out!
+ currentUser.logout();
+
+ System.exit(0);
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="summary">Summary</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Hopefully this introduction tutorial helped you understand how to set-up
Shiro in a basic application as well Shiro’s primary design concepts, the
<code>Subject</code> and <code>SecurityManager</code>.</p>
+</div>
+<div class="paragraph">
+<p>But this was a fairly simple application. You might have asked yourself,
"What if I don’t want to use INI user accounts and instead want to
connect to a more complex user data source?"</p>
+</div>
+<div class="paragraph">
+<p>To answer that question requires a little deeper understanding of
Shiro’s architecture and supporting configuration mechanisms. We’ll
cover Shiro’s <a href="architecture.html">Architecture</a> next.</p>
+</div>
+</div>
+</div>
+ <hr />
+
+</div>
+
+ <div class="footer-padding"></div>
+
+ <div class="container-fluid pt-2 border-top" id="custom-footer">
+ <footer class="row justify-content-between align-items-center">
+ <div class=" col-md-5">
+ <div class="copyright-footer justify-content-start">
+ <a
href="https://www.apache.org/foundation/contributing.html";>Donate to the
ASF</a> |
+ <a
href="https://www.apache.org/licenses/LICENSE-2.0.html";>License</a>
+ <p class="text-muted">Copyright © 2008-2022 The Apache
Software Foundation</p>
+ </div>
+ </div>
+
+ <div class="d-flex justify-content-center col-md-1">
+ <a class="btn btn-social"><span class="social-icon
social-twitter"><i class="bi bi-twitter"></i></span></a>
+ <a class="btn btn-social"><span class="social-icon
social-facebook"><i class="bi bi-facebook"></i></span></a>
+ <a class="btn btn-social"><span class="social-icon
social-linkedin"><i class="bi bi-linkedin"></i></span></a>
+ </div>
+
+ <div class="d-flex justify-content-end col-md-4" id="editThisPage">
+ <input type="hidden" id="ghEditPage"
value="https://github.com/apache/shiro-site/edit/jbake/jbake/content/tutorial.adoc"/>
+ </div>
+
+ <div class="d-flex col-md-2 justify-content-end" style="position:
relative">
+ <div class="footer-shield"></div>
+ </div>
+ </footer>
+ </div>
+
+
+ <!-- Le javascript
+ ================================================== -->
+ <!-- Placed at the end of the document so the pages load faster -->
+ <script src="js/bootstrap.min.js"></script>
+ <script src="highlight.js-11.2.0/highlight.min.js"></script>
+ <script src="js/shiro.js"></script>
+
+ <script>
+ docReady(
+ addPageEditLink()
+ );
+ </script>
+ <script>hljs.highlightAll();</script>
+
+ </body>
+</html>
![https://www.apache.org/events/current-event-125x125.png"](https://www.apache.org/events/current-event-125x125.png"){kind=link}