Google Git
Sign in
apache / shiro-site / refs/heads/asf-site / . / authorization.html
blob: 348a2f19600b4d5293f5db92dcc15cf1965a1c33 [file] [log] [blame]
<!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 Authorization | Apache Shiro</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="keywords" content='documentation'>
<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 Authorization | 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="2010-03-18T00:00:00Z"/>
<meta property="article:tag" content='documentation'/>
<meta property="og:locale" content="en_US" />
<meta property="og:url" content='https://shiro.apache.org/authorization.html'/>
<meta property="og:image" content='images/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">
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="//matomo.privacy.apache.org/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '2']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Matomo Code -->
</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="images/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><a class="dropdown-item" href="jakarta-ee.html">Jakarta EE</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="privacy-policy.html">Privacy Policy</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="https://www.apache.org/">Apache Homepage</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/licenses/">License</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/security/">Security</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<div class="page-header">
<h1>Apache Shiro Authorization</h1>
</div>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon">
<div class="title">Handy Hint</div>
</td>
<td class="content">
<div class="title">Shiro v1 version notice</div>
<div class="paragraph">
<p>As of 2024-03-01, Shiro v1 will soon be superseded by v2.<p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="toc" class="toc">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#Authentication-ElementsOfAuthorization">Elements of Authorization</a>
<ul class="sectlevel2">
<li><a href="#Authentication-ElementsOfAuthorization-Permissions">Permissions</a></li>
<li><a href="#Authentication-ElementsOfAuthorization-Roles">Roles</a></li>
<li><a href="#Authentication-ElementsOfAuthorization-Users">Users</a></li>
</ul>
</li>
<li><a href="#Authentication-AuthorizingSubjects">Authorizing Subjects</a>
<ul class="sectlevel2">
<li><a href="#Authentication-AuthorizingSubjects-ProgrammaticAuthorization">Programmatic Authorization</a></li>
<li><a href="#Authentication-AuthorizingSubjects-NotationBasedAuthorization">Notation-based Authorization</a></li>
<li><a href="#Authentication-AuthorizingSubjects-JSPTagLibAuthorization">JSP TagLib Authorization</a></li>
</ul>
</li>
<li><a href="#Authentication-AuthorizingSequence">Authorization Sequence</a>
<ul class="sectlevel2">
<li><a href="#Authentication-AuthorizingSubjects-ModularRealmAuthorizer">Modular Realm Authorizer</a></li>
<li><a href="#Authentication-AuthorizingSubjects-ModularRealmAuthorizer-RealmAuthorizationOrder">Realm Authorization Order</a></li>
<li><a href="#Authentication-AuthorizingSubjects-CustomAuthorizer">Custom Authorizer</a></li>
</ul>
</li>
</ul>
</div>
<div id="preamble">
<div class="sectionbody">
<div class="imageblock text-center">
<div class="content">
<img src="/images/ShiroFeatures_Authorization.png" alt="Shiro features authorization graphic">
</div>
</div>
<div class="paragraph">
<p>Authorization, also known as <em>access control</em>, is the process of managing access to resources. In other words, controlling <em>who</em> has access to <em>what</em> in an application.</p>
</div>
<div class="paragraph">
<p>Examples of authorization checks are: Is the user allowed to look at this webpage, edit this data, view this button, or print to this printer? Those are all decisions determining what a user has access to.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Authentication-ElementsOfAuthorization">Elements of Authorization</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Authorization has three core elements that we reference quite a bit in Shiro: permissions, roles, and users.</p>
</div>
<div class="sect2">
<h3 id="Authentication-ElementsOfAuthorization-Permissions">Permissions</h3>
<div class="paragraph">
<p>Permissions in Apache Shiro represent the most atomic element of a security policy. They are fundamentally statements about behavior and represent explicitly what can be done in an application. A well-formed permission statement essentially describes resources and what actions are possible when a <code>Subject</code> interacts with those resources.</p>
</div>
<div class="paragraph">
<p>Some examples of permission statements:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Open a file</p>
</li>
<li>
<p>View the <code>/user/list</code> web page</p>
</li>
<li>
<p>Print documents</p>
</li>
<li>
<p>Delete the 'jsmith' user</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Most resources will support the typical CRUD (create, read, update, delete) actions, but any action that makes sense for a particular resource type is ok. The fundamental idea is that permission statements at a minimum are based on <em>Resources</em> and <em>Actions</em>.</p>
</div>
<div class="paragraph">
<p>When looking at permissions, probably the most important thing to realize is that permission statements have no representation of <em>who</em> can perform the represented behavior. They are only statements of <em>what</em> can be done in an application.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<div class="title">Permissions represent behavior only</div>
<p>Permission statements reflect behavior (actions associated with resource types) <code>only</code>. They do not reflect <code>who</code> is able to perform such behavior.')</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Defining <em>who</em> (users) is allowed to do <em>what</em> (permissions) is an exercise of assigning permissions to users in some way. This is always done by the application&#8217;s data model and can vary greatly across applications.</p>
</div>
<div class="paragraph">
<p>For example, permissions can be grouped in a Role and that Role could be associated with one or more User objects. Or some applications can have a Group of users and a Group can be assigned a Role, which by transitive association would mean that all the Users in that Group are implicitly granted the permissions in the Role.</p>
</div>
<div class="paragraph">
<p>There are many variations for how permissions could be granted to users - the application determines how to model this based on the application requirements.</p>
</div>
<div class="paragraph">
<p>We&#8217;ll cover how Shiro determines if a <code>Subject</code> is permitted to do something or not later.</p>
</div>
<div class="sect3">
<h4 id="Authentication-ElementsOfAuthorization-Permissions-PermissionGranularity">Permission Granularity</h4>
<div class="paragraph">
<p>The permission examples above all specify actions (open, read, delete, etc.) on a resource type (door, file, customer, etc). In some cases, they even specify very fine-grained <em>instance-level</em> behavior - for example, 'delete' (action) the 'user' (resource type) with username 'jsmith' (instance identifier). In Shiro, you have the ability to define exactly how granular those statements can be.</p>
</div>
<div class="paragraph">
<p>We cover permission granularity and 'levels' of permission statements in much more detail in Shiro&#8217;s <a href="permissions.html">Permissions Documentation</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Authentication-ElementsOfAuthorization-Roles">Roles</h3>
<div class="paragraph">
<p>A Role is a named entity that typically represents a set of behaviors or responsibilities. Those behaviors translate to things you can or can&#8217;t do with a software application. Roles are typically assigned to user accounts, so by association, users can <code>do</code> the things attributed to various roles.</p>
</div>
<div class="paragraph">
<p>There are effectively two types of Roles, and Shiro supports both concepts:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Implicit Roles</strong>: Most people use roles as an <em>implicit</em> construct: where your application <em>implies</em> a set of behaviors (i.e. permissions) based on a role name only. With implicit roles, there is nothing at the software level that says <code>role X is allowed to perform behavior A, B and C</code>. Behavior is implied by a name alone.</p>
</li>
</ul>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<div class="title">Potentially Brittle Security</div>
<p>While the simpler and most common approach, implicit roles potentially impose a lot of software maintenance and management problems.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>This is probably ok for very simple applications (e.g. maybe there is an <code>admin</code> role and <code>everyone else</code>). But for more complicated or configurable applications, this can be a major problem throughout the life of your application and drive a large maintenance cost for your software.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Explicit Roles</strong>: An explicit role however is essentially a named collection of actual permission statements. In this form, the application (and Shiro) knows <em>exactly</em> what it means to have a particular role or not. Because it is known the <em>exact</em> behavior that can be performed or not, there is no guessing or implying what a particular role can or can not do.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The Shiro team advocates using permissions and explicit roles instead of the older implicit approach. You will have much greater control over your application&#8217;s security experience.</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">
<div class="title">Resource-Based Access Control</div>
<p>Be sure to read Les Hazlewood 's article, <a href="https://stormpath.com/blog/new-rbac-resource-based-access-control">The New RBAC: Resource-Based Access Control</a>, which covers in-depth the benefits of using permissions and explicit roles (and their positive impact on source code) instead of the older implicit role approach.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="Authentication-ElementsOfAuthorization-Users">Users</h3>
<div class="paragraph">
<p>A user essentially is the 'who' of an application. As we&#8217;ve covered previously however, the <code>Subject</code> is really Shiro&#8217;s 'User' concept.</p>
</div>
<div class="paragraph">
<p>Users (Subjects) are allowed to perform certain actions in your application through their association with roles or direct permissions. Your application&#8217;s data model defines exactly how a <code>Subject</code> is allowed to do something or not.</p>
</div>
<div class="paragraph">
<p>For example, in your data model, perhaps you have an actual <code>User</code> class, and you assign permissions directly to <code>User</code> instances. Or maybe you assign permissions only to <code>Roles</code> directly, and then assign Roles to <code>Users</code>, so by association, <code>Users</code> transitively 'have' the permissions assigned to their roles. Or you could represent these things with a 'Group' concept. It is up to you - use what makes sense for your application.</p>
</div>
<div class="paragraph">
<p>Your data model defines exactly how authorization will function. Shiro relies on a <a href="realm.html">Realm</a> implementation to translate your data model association details into a format Shiro understands. We&#8217;ll cover how Realms do this a little later.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<div class="title">Note</div>
<p>Ultimately, your <a href="realm.html">Realm</a> implementation is what communicates with your data source (RDBMS, LDAP, etc).
So your realm is what will tell Shiro whether roles or permissions exist. You have full control over how your authorization model is structured and defined.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Authentication-AuthorizingSubjects">Authorizing Subjects</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Performing authorization in Shiro can be done in 3 ways:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Programmatically - You can perform authorization checks in your java code with structures like <code>if</code> and <code>else</code> blocks.</p>
</li>
<li>
<p>JDK annotations - You can attach an authorization annotation to your Java methods</p>
</li>
<li>
<p>JSP/GSP TagLibs - You can control JSP or GSP page output based on roles and permissions</p>
</li>
</ul>
</div>
<div class="sect2">
<h3 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization">Programmatic Authorization</h3>
<div class="paragraph">
<p>Probably the easiest and most common way to perform authorization is to programmatically interact with the current <code>Subject</code> instance directly.</p>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-RoleBasedAuthorization">Role-Based Authorization</h4>
<div class="paragraph">
<p>If you want to control access based on simpler/traditional implicit role names, you can execute role checks:</p>
</div>
<div class="sect4">
<h5 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-RoleBasedAuthorization-RoleChecks">Role Checks</h5>
<div class="paragraph">
<p>If you want to simply check to see if the current <code>Subject</code> has a role or not, you can call the variant <code>hasRole*</code> methods on the <code>Subject</code> instance.</p>
</div>
<div class="paragraph">
<p>For example, to see if a <code>Subject</code> has a particular (single) role, you can call the <code>subject.</code> <a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)"><code>hasRole(roleName)</code></a> method, and react accordingly:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Subject currentUser = SecurityUtils.getSubject();
if (currentUser.hasRole("administrator")) {
//show the admin button
} else {
//don't show the button? Grey it out?
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are few role-oriented <code>Subject</code> methods you can call, depending on your needs:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Subject Method</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)"><code>hasRole(String roleName)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>true</code> if the <code>Subject</code> is assigned the specified role, <code>false</code> otherwise.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRoles(java.util.List)"><code>hasRoles(List&lt;String&gt; roleNames)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of <code>hasRole</code> results corresponding to the indices in the method argument. Useful as a performance enhancement if many role checks need to be performed (e.g. when customizing a complex view)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#hasAllRoles(java.util.Collection)"><code>hasAllRoles(Collection&lt;String&gt; roleNames)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>true</code> if the <code>Subject</code> is assigned <em>all</em> the specified roles, <code>false</code> otherwise.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-RoleBasedAuthorization-Assertions">Role Assertions</h5>
<div class="paragraph">
<p>An alternative to checking a <code>boolean</code> to see if the <code>Subject</code> has a role or not, you can simply assert that they have an expected role before logic is executed. If the <code>Subject</code> does not have the expected role, an <a href="static/current/apidocs/org/apache/shiro/authz/AuthorizationException.html"><code>AuthorizationException</code></a> will be thrown. If they do have the expected role, the assertion will execute quietly and logic will continue as expected.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Subject currentUser = SecurityUtils.getSubject();
//guarantee that the current user is a bank teller and
//therefore allowed to open the account:
currentUser.checkRole("bankTeller");
openBankAccount();</code></pre>
</div>
</div>
<div class="paragraph">
<p>A benefit of this approach over the <code>hasRole*</code> methods is that code can be a bit cleaner in that you don&#8217;t have to construct your own <code>AuthorizationExceptions</code> if the current <code>Subject</code> does not meet expected conditions (if you don&#8217;t want to).</p>
</div>
<div class="paragraph">
<p>There are few role-oriented <code>Subject</code> assertion methods you can call, depending on your needs:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Subject Method</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRole(java.lang.String)"><code>checkRole(String roleName)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns quietly if the <code>Subject</code> is assigned the specified role or throws an <code>AuthorizationException</code> if not.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRoles(java.util.Collection)"><code>checkRoles(Collection&lt;String&gt; roleNames)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns quietly if the <code>Subject</code> is assigned <em>all</em> the specified role or throws an <code>AuthorizationException</code> if not.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRoles(java.lang.String...)"><code>checkRoles(String&#8230;&#8203; roleIdentifiers)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Same effect as the <code>checkRoles</code> method above, but allows Java 5 var-args style arguments.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-PermissionBasedAuthorization">Permission-Based Authorization</h4>
<div class="paragraph">
<p>As stated above in our overview of Roles, often a better way of performing access control is through permission-based authorization. Permission-based authorization, because it is strongly associated with your application&#8217;s raw functionality (and the behavior on an application&#8217;s core resources), permission-based authorization source code changes when your functionality changes, not when there is a security policy change. This means code is impacted much-less frequently than similar role-based authorization code.</p>
</div>
<div class="sect4">
<h5 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-PermissionBasedAuthorization-PermissionChecks">Permission Checks</h5>
<div class="paragraph">
<p>If you want to check to see if a <code>Subject</code> is permitted to do something or not, you can call any of the various <code>isPermitted*</code> method variants. There are two primary means of checking permissions - with object-based <code>Permission</code> instances or with Strings that represent <code>Permissions</code></p>
</div>
</div>
<div class="sect4">
<h5 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-PermissionBasedAuthorization-ObjectBasedPermissionChecks">Object-based Permission Checks</h5>
<div class="paragraph">
<p>One possible way of performing permission checks is to instantiate an instance of Shiro&#8217;s <a href="static/current/apidocs/org/apache/shiro/authz/Permission.html"><code>org.apache.shiro.authz.Permission</code></a> interface and pass it to the <code>*isPermitted</code> methods that accept permission instances.</p>
</div>
<div class="paragraph">
<p>For example, consider the following scenario: There is a <code>Printer</code> in an office with a unique identifier <code>laserjet4400n</code>. Our software needs to check to see if the current user is allowed print documents on that printer before we allow them to press a 'print' button. The permission check to see if this possible could be formulated like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Permission printPermission = new PrinterPermission("laserjet4400n", "print");
Subject currentUser = SecurityUtils.getSubject();
if (currentUser.isPermitted(printPermission)) {
//show the Print button
} else {
//don't show the button? Grey it out?
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In this example, we also see an example of a very powerful <em>instance-level</em> access control check - the ability to restrict behavior based on <em>individual data instances</em>.</p>
</div>
<div class="paragraph">
<p>Object-based <code>Permissions</code> are useful if:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>You want compile-time type-safety</p>
</li>
<li>
<p>You want to guarantee permissions are represented and used correctly</p>
</li>
<li>
<p>You want explicit control of how permission resolution logic (called permission implication logic, based on the Permission interface&#8217;s <a href="static/current/apidocs/org/apache/shiro/authz/Permission.html#implies(org.apache.shiro.authz.Permission)"><code>implies</code></a> method) executes.</p>
</li>
<li>
<p>You want to guarantee Permissions reflect application resources accurately (for example, maybe Permission classes can be auto-generated during a project&#8217;s build based on a project&#8217;s domain model).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>There are few Object permission-oriented <code>Subject</code> methods you can call, depending on your needs:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Subject Method</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(org.apache.shiro.authz.Permission)"><code>isPermitted(Permission p)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>true</code> if the <code>Subject</code> is permitted to perform an action or access a resource summarized by the specified <code>Permission</code> instance, <code>false</code> otherwise.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(java.util.List)"><code>isPermitted(List&lt;Permission&gt; perms)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of <code>isPermitted</code> results corresponding to the indices in the method argument. Useful as a performance enhancement if many permission checks need to be performed (e.g. when customizing a complex view)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermittedAll(java.util.Collection)"><code>isPermittedAll(Collection&lt;Permission&gt; perms)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>true</code> if the <code>Subject</code> is permitted <em>all</em> the specified permissions, <code>false</code> otherwise.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-PermissionBasedAuthorization-StringBasedPermissionChecks">String-based permission checks</h5>
<div class="paragraph">
<p>While Object-based permissions can be useful (compile-time type-safety, guaranteed behavior, customized implication logic, etc.), they can sometimes feel a bit 'heavy-handed' for many applications. An alternative is to use normal <code>Strings</code> to represent a permission instance.</p>
</div>
<div class="paragraph">
<p>For example, based on the print permission example above, we can re-formulate that same check as a <code>String</code>-based permission check:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Subject currentUser = SecurityUtils.getSubject();
if (currentUser.isPermitted("printer:print:laserjet4400n")) {
//show the Print button
} else {
//don't show the button? Grey it out?
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This example still shows the same instance-level permission check, but important parts of the permission - <code>printer</code> (resource type), <code>print</code> (action), and <code>laserjet4400n</code> (instance id) - were all represented in a String.</p>
</div>
<div class="paragraph">
<p>This particular example shows a special colon-delimited format defined by Shiro&#8217;s default <a href="static/current/apidocs/org/apache/shiro/authz/permission/WildcardPermission.html"><code>org.apache.shiro.authz.permission.WildcardPermission</code></a> implementation, which most people will find suitable.</p>
</div>
<div class="paragraph">
<p>That is, the above code block is (mostly) a shortcut for the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Subject currentUser = SecurityUtils.getSubject();
Permission p = new WildcardPermission("printer:print:laserjet4400n");
if (currentUser.isPermitted(p) {
//show the Print button
} else {
//don't show the button? Grey it out?
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>WildcardPermission</code> token format and formation options are covered in-depth in Shiro&#8217;s <a href="permissions.html">Permission documentation</a>.</p>
</div>
<div class="paragraph">
<p>And while the above String defaults to the <code>WildcardPermission</code> format, you can actually invent your own String format and use that if you prefer. We&#8217;ll cover how to do this as part of the Realm Authorization section below.</p>
</div>
<div class="paragraph">
<p>String-based permissions are beneficial in that you are not forced to implement an interface and simple strings are often easy to read. The downside is that you don&#8217;t have type safety and if you needed more complicated behavior that are outside the scope of what the Strings represent, you&#8217;re going to want to implement your own permission objects based on the permission interface. In practice, most Shiro end-users choose the String-based approach for their simplicity, but ultimately your application&#8217;s requirements will dictate which is better.</p>
</div>
<div class="paragraph">
<p>Like the Object-based permission check methods, there are String variants to support String-based permission checks:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Subject Method</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(java.lang.String)"><code>isPermitted(String perm)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>true</code> if the <code>Subject</code> is permitted to perform an action or access a resource summarized by the specified <code>String</code> permission, <code>false</code> otherwise.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(java.util.List)"><code>isPermitted(List perms)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of <code>isPermitted</code> results corresponding to the indices in the method argument. Useful as a performance enhancement if many <code>String</code> permission checks need to be performed (e.g. when customizing a complex view)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermittedAll(java.lang.String...)"><code>isPermittedAll(String&#8230;&#8203; perms)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>true</code> if the <code>Subject</code> is permitted <em>all</em> the specified <code>String</code> permissions, <code>false</code> otherwise.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="Authentication-AuthorizingSubjects-ProgrammaticAuthorization-PermissionBasedAuthorization-PermissionAssertions">Permission Assertions</h5>
<div class="paragraph">
<p>As an alternative to checking a <code>boolean</code> to see if the <code>Subject</code> is permitted to do something or not, you can simply assert that they have an expected permission before logic is executed. If the <code>Subject</code> is not permitted, an <a href="static/current/apidocs/org/apache/shiro/authz/AuthorizationException.html"><code>AuthorizationException</code></a> will be thrown. If they are permitted as expected, the assertion will execute quietly and logic will continue as expected.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Subject currentUser = SecurityUtils.getSubject();
//guarantee that the current user is permitted
//to open a bank account:
Permission p = new AccountPermission("open");
currentUser.checkPermission(p);
openBankAccount();</code></pre>
</div>
</div>
<div class="paragraph">
<p>or, the same check, using a String permission:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Subject currentUser = SecurityUtils.getSubject();
//guarantee that the current user is permitted
//to open a bank account:
currentUser.checkPermission("account:open");
openBankAccount();</code></pre>
</div>
</div>
<div class="paragraph">
<p>A benefit of this approach over the <code>isPermitted*</code> methods is that code can be a bit cleaner in that you don&#8217;t have to construct your own <code>AuthorizationExceptions</code> if the current <code>Subject</code> does not meet expected conditions (if you don&#8217;t want to).</p>
</div>
<div class="paragraph">
<p>There are few permission-oriented <code>Subject</code> assertion methods you can call, depending on your needs:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Subject Method</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#checkPermission(org.apache.shiro.authz.Permission)"><code>checkPermission(Permission p)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns quietly if the <code>Subject</code> is permitted to perform an action or access a resource summarized by the specified <code>Permission</code> instance, or throws an <code>AuthorizationException</code> if not.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#checkPermission(java.lang.String)"><code>checkPermission(String perm)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns quietly if the <code>Subject</code> is is permitted to perform an action or access a resource summarized by the specified <code>String</code> permission, or throws an <code>AuthorizationException</code> if not.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#checkPermissions(java.util.Collection)"><code>checkPermissions(Collection&lt;Permission&gt; perms)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns quietly if the <code>Subject</code> is permitted <em>all</em> the specified permissions, or throws an <code>AuthorizationException</code> if not.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="static/current/apidocs/org/apache/shiro/subject/Subject.html#checkPermissions(java.lang.String...)"><code>checkPermissions(String&#8230;&#8203; perms)</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Same effect as the <code>checkPermissions</code> method above, but using <code>String</code>-based permissions.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Authentication-AuthorizingSubjects-NotationBasedAuthorization">Notation-based Authorization</h3>
<div class="paragraph">
<p>In addition to the <code>Subject</code> API calls, Shiro provides a collection of Java 5+ annotations if you prefer meta-based authorization control.</p>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-NotationBasedAuthorization-Configuration">Configuration</h4>
<div class="paragraph">
<p>Before you can use Java annotations, you&#8217;ll need to enable AOP support in your application. There are a number of different AOP frameworks so, unfortunately, there is no standard way to enable AOP in an application.</p>
</div>
<div class="paragraph">
<p>For AspectJ, you can review our <a href="https://github.com/apache/shiro/tree/main/samples/aspectj">AspectJ sample application</a>.</p>
</div>
<div class="paragraph">
<p>For Spring applications, you can look into our <a href="spring-framework.html">Spring Integration</a> documentation.</p>
</div>
<div class="paragraph">
<p>For Guice applications, you can look into our <a href="guice.html">Guice Integration</a> documentation.</p>
</div>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-NotationBasedAuthorization-TheRequiresAuthenticationAnnotation">The <code>RequiresAuthentication</code> annotation</h4>
<div class="paragraph">
<p>The <a href="static/current/apidocs/org/apache/shiro/authz/annotation/RequiresAuthentication.html">RequiresAuthentication</a> annotation requires the current <code>Subject</code> to have been authenticated during their current session for the annotated class/instance/method to be accessed or invoked.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RequiresAuthentication
public void updateAccount(Account userAccount) {
//this method will only be invoked by a
//Subject that is guaranteed authenticated
...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is mostly equivalent to the following Subject-based logic:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public void updateAccount(Account userAccount) {
if (!SecurityUtils.getSubject().isAuthenticated()) {
throw new AuthorizationException(...);
}
//Subject is guaranteed authenticated here
...
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-NotationBasedAuthorization-TheRequiresGuestAnnotation">The <code>RequiresGuest</code> annotation</h4>
<div class="paragraph">
<p>The <a href="static/current/apidocs/org/apache/shiro/authz/annotation/RequiresGuest.html">RequiresGuest</a> annotation requires the current Subject to be a "guest", that is, they are not authenticated or remembered from a previous session for the annotated class/instance/method to be accessed or invoked.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RequiresGuest
public void signUp(User newUser) {
//this method will only be invoked by a
//Subject that is unknown/anonymous
...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is mostly equivalent to the following Subject-based logic:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public void signUp(User newUser) {
Subject currentUser = SecurityUtils.getSubject();
PrincipalCollection principals = currentUser.getPrincipals();
if (principals != null &amp;&amp; !principals.isEmpty()) {
//known identity - not a guest:
throw new AuthorizationException(...);
}
//Subject is guaranteed to be a 'guest' here
...
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-NotationBasedAuthorization-TheRequiresPermissionsAnnotation">The <code>RequiresPermissions</code> annotation</h4>
<div class="paragraph">
<p>The <a href="static/current/apidocs/org/apache/shiro/authz/annotation/RequiresPermissions.html">RequiresPermissions</a> annotation requires the current Subject be permitted one or more permissions in order to execute the annotated method.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RequiresPermissions("account:create")
public void createAccount(Account account) {
//this method will only be invoked by a Subject
//that is permitted to create an account
...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is mostly equivalent to the following Subject-based logic:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public void createAccount(Account account) {
Subject currentUser = SecurityUtils.getSubject();
if (!subject.isPermitted("account:create")) {
throw new AuthorizationException(...);
}
//Subject is guaranteed to be permitted here
...
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-NotationBasedAuthorization-TheRequiresRolesPermission">The <code>RequiresRoles</code> permission</h4>
<div class="paragraph">
<p>The <a href="static/current/apidocs/org/apache/shiro/authz/annotation/RequiresRoles.html">RequiresRoles</a> annotation requires the current Subject to have all of the specified roles. If they do not have the role(s), the method will not be executed and an AuthorizationException is thrown.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RequiresRoles("administrator")
public void deleteUser(User user) {
//this method will only be invoked by an administrator
...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is mostly equivalent to the following Subject-based logic:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public void deleteUser(User user) {
Subject currentUser = SecurityUtils.getSubject();
if (!subject.hasRole("administrator")) {
throw new AuthorizationException(...);
}
//Subject is guaranteed to be an 'administrator' here
...
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-NotationBasedAuthorization-TheRequiresUserAnnotation">The <code>RequiresUser</code> annotation</h4>
<div class="paragraph">
<p>The <a href="static/current/apidocs/org/apache/shiro/authz/annotation/RequiresUser.html">RequiresUser</a>* annotation requires the current Subject to be an application user for the annotated class/instance/method to be accessed or invoked. An 'application user' is defined as a <code>Subject</code> that has a known identity, either known due to being authenticated during the current session or remembered from 'RememberMe' services from a previous session.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RequiresUser
public void updateAccount(Account account) {
//this method will only be invoked by a 'user'
//i.e. a Subject with a known identity
...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is mostly equivalent to the following Subject-based logic:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public void updateAccount(Account account) {
Subject currentUser = SecurityUtils.getSubject();
PrincipalCollection principals = currentUser.getPrincipals();
if (principals == null || principals.isEmpty()) {
//no identity - they're anonymous, not allowed:
throw new AuthorizationException(...);
}
//Subject is guaranteed to have a known identity here
...
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Authentication-AuthorizingSubjects-JSPTagLibAuthorization">JSP TagLib Authorization</h3>
<div class="paragraph">
<p>Shiro offers a Tag Library for controlling JSP/GSP page output based on <code>Subject</code> state. This is covered in the <a href="web.html">Web</a> chapter&#8217;s <a href="web.html#tag_library">JSP/GSP Tag Library</a> section.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Authentication-AuthorizingSequence">Authorization Sequence</h2>
<div class="sectionbody">
<div class="imageblock text-center">
<div class="content">
<img src="/images/ShiroAuthorizationSequence.png" alt="Shiro authorization sequence graphic">
</div>
</div>
<div class="paragraph">
<p>Now that we&#8217;ve seen how to perform authorization based on the current <code>Subject</code>, let&#8217;s take a look at what happens inside Shiro whenever an authorization call is made.</p>
</div>
<div class="paragraph">
<p>We&#8217;ve taken our previous architecture diagram from the <a href="architecture.html">Architecture</a> chapter, and left only the components relevant to authorization highlighted. Each number represents a step during an authorization operation:</p>
</div>
<div class="paragraph">
<p><strong>Step 1</strong>: Application or framework code invokes any of the <code>Subject</code> <code>hasRole*</code>, <code>checkRole*</code>, <code>isPermitted*</code>, or <code>checkPermission*</code> method variants, passing in whatever permission or role representation is required.</p>
</div>
<div class="paragraph">
<p><strong>Step 2</strong>: The <code>Subject</code> instance, typically a <a href="static/current/apidocs/org/apache/shiro/subject/support/DelegatingSubject.html"><code>DelegatingSubject</code></a> (or a subclass) delegates to the application&#8217;s <code>SecurityManager</code> by calling the <code>securityManager&#8217;s nearly identical respective `hasRole*</code>, <code>checkRole*</code>, <code>isPermitted*</code>, or <code>checkPermission*</code> method variants (the <code>securityManager</code> implements the <a href="static/current/apidocs/org/apache/shiro/authz/Authorizer.html"><code>org.apache.shiro.authz.Authorizer</code></a> interface, which defines all Subject-specific authorization methods).</p>
</div>
<div class="paragraph">
<p><strong>Step 3</strong>: The <code>SecurityManager</code>, being a basic 'umbrella' component, relays/delegates to its internal <a href="static/current/apidocs/org/apache/shiro/authz/Authorizer.html"><code>org.apache.shiro.authz.Authorizer</code></a> instance by calling the <code>authorizer</code> 's respective <code>hasRole*</code>, <code>checkRole*</code>, <code>isPermitted*</code>, or <code>checkPermission*</code> method. The <code>authorizer</code> instance is by default a <a href="static/current/apidocs/org/apache/shiro/authz/ModularRealmAuthorizer.html"><code>ModularRealmAuthorizer</code></a> instance, which supports coordinating one or more <code>Realm</code> instances during any authorization operation.</p>
</div>
<div class="paragraph">
<p><strong>Step 4</strong>: Each configured <code>Realm</code> is checked to see if it implements the same <a href="static/current/apidocs/org/apache/shiro/authz/Authorizer.html"><code>Authorizer</code></a> interface. If so, the Realm&#8217;s own respective <code>hasRole*</code>, <code>checkRole*</code>, <code>isPermitted*</code>, or <code>checkPermission*</code> method is called.</p>
</div>
<div class="sect2">
<h3 id="Authentication-AuthorizingSubjects-ModularRealmAuthorizer">Modular Realm Authorizer</h3>
<div class="paragraph">
<p>As mentioned earlier, the Shiro <code>SecurityManager</code> implementations default to using a <a href="static/current/apidocs/org/apache/shiro/authz/ModularRealmAuthorizer.html"><code>ModularRealmAuthorizer</code></a> instance. The <code>ModularRealmAuthorizer</code> equally supports applications with single Realm as well as those with multiple realms.</p>
</div>
<div class="paragraph">
<p>For any authorization operation, the <code>ModularRealmAuthorizer</code> will iterate over its internal collection of <code>Realms</code> and interact with each one in iteration order. Each <code>Realm</code> interaction functions as follows:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If the <code>Realm</code> itself implements the <a href="static/current/apidocs/org/apache/shiro/authz/Authorizer.html"><code>Authorizer</code></a> interface, its respective <code>Authorizer</code> method (<code>hasRole*</code>, <code>checkRole*</code>, <code>isPermitted*</code>, or <code>checkPermission*</code>) is called.</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>If the Realm&#8217;s method results in an exception, the exception is propagated as an <a href="static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html"><code>AuthorizationException</code></a> to the <code>Subject</code> caller. This short-circuits the authorization process and any remaining Realms will not be consulted for that authorization operation.</p>
</li>
<li>
<p>If the Realm&#8217;s method is a <code>hasRole*</code> or <code>isPermitted*</code> variant that returns a boolean and that return value is <code>true</code>, the <code>true</code> value is returned immediately and any remaining Realms are short-circuited. This behavior exists as a performance enhancement, as typically if permitted by one Realm, it is implied that the Subject is permitted. This favors security policies where everything is prohibited by default and things are explicitly allowed, the most secure type of security policy.</p>
</li>
</ol>
</div>
</li>
<li>
<p>If the Realm does not implement the <code>Authorizer</code> interface, it is ignored.</p>
</li>
</ol>
</div>
</div>
<div class="sect2">
<h3 id="Authentication-AuthorizingSubjects-ModularRealmAuthorizer-RealmAuthorizationOrder">Realm Authorization Order</h3>
<div class="paragraph">
<p>It is important to point out that, exactly like authentication, the <code>ModularRealmAuthorizer</code> will interact with Realm instances in <em>iteration</em> order.</p>
</div>
<div class="paragraph">
<p>The <code>ModularRealmAuthorizer</code> has access to the <code>Realm</code> instances configured on the <code>SecurityManager</code>. When executing an authorization operation, it will iterate over that collection, and for each <code>Realm</code> that implements the <code>Authorizer</code> interface itself, invoke the Realm&#8217;s respective <code>Authorizer</code> method (e.g. <code>hasRole*</code>, <code>checkRole*</code>, <code>isPermitted*</code>, or <code>checkPermission*</code>).</p>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-ModularRealmAuthorizer-ConfiguringGlobalPermissionResolver">Configuring a global <code>PermissionResolver</code></h4>
<div class="paragraph">
<p>When performing a <code>String</code>-based permission check, most of Shiro&#8217;s default <code>Realm</code> implementations convert this String into an actual <a href="static/current/apidocs/org/apache/shiro/authz/Permission.html"><code>Permission</code></a> instance first before performing permission <em>implication</em> logic.</p>
</div>
<div class="paragraph">
<p>This is because Permissions are evaluated based on implication logic and not a direct equality check (see the <a href="permissions.html">Permission</a> documentation for more about implication vs. equality). Implication logic is better represented in code than via String comparisons. Therefore, most Realms need to convert, or <em>resolve</em> a submitted permission string into a corresponding representative <code>Permission</code> instance.</p>
</div>
<div class="paragraph">
<p>To aid in this conversion, Shiro supports the notion of a <a href="static/current/apidocs/org/apache/shiro/authz/permission/PermissionResolver.html"><code>PermissionResolver</code></a>. Most <code>Shiro</code> Realm implementations use a <code>PermissionResolver</code> to support their implementation of the <code>Authorizer</code> interface&#8217;s <code>String</code>-based permission methods: when one of these methods is invoked on the Realm, it will use the <code>PermissionResolver</code> to convert the string into a Permission instance, and perform the check that way.</p>
</div>
<div class="paragraph">
<p>All Shiro <code>Realm</code> implementations default to an internal <a href="static/current/apidocs/org/apache/shiro/authz/permission/WildcardPermissionResolver.html"><code>WildcardPermissionResolver</code></a> which assumes Shiro&#8217;s <a href="static/current/apidocs/org/apache/shiro/authz/permission/WildcardPermission.html"><code>WildcardPermission</code></a> String format.</p>
</div>
<div class="paragraph">
<p>If you want to create your own <code>PermissionResolver</code> implementation, perhaps to support your own Permission string syntax, and you want all configured <code>Realm</code> instances to support that syntax, you can set your <code>PermissionResolver</code> globally for all <code>Realms</code> that can be configured with one.</p>
</div>
<div class="paragraph">
<p>For example, in <code>shiro.ini</code>:</p>
</div>
<div class="paragraph">
<p><strong>shiro.ini</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">globalPermissionResolver = com.foo.bar.authz.MyPermissionResolver
...
securityManager.authorizer.permissionResolver = $globalPermissionResolver
...</code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<div class="title">PermissionResolverAware</div>
<p>If you want to configure a global <code>PermissionResolver</code>, each <code>Realm</code> that is to receive the configured <code>PermissionResolver</code> <strong>must</strong> implement the <a href="static/current/apidocs/src-html/org/apache/shiro/authz/permission/PermissionResolverAware.html"><code>PermissionResolverAware</code></a> interface.
This guarantees that the configured instance can be relayed to each <code>Realm</code> that supports such configuration.
If you don&#8217;t want to use a global <code>PermissionResolver</code> or you don&#8217;t want to be bothered with the <code>PermissionResolverAware</code> interface, you can always configure a realm with a <code>PermissionResolver</code> instance explicitly (assuming there is a JavaBeans-compatible setPermissionResolver method).</p>
</div>
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">permissionResolver = com.foo.bar.authz.MyPermissionResolver
realm = com.foo.bar.realm.MyCustomRealm
realm.permissionResolver = $permissionResolver
...</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Authentication-AuthorizingSubjects-ModularRealmAuthorizer-ConfiguringGlobalRolePermissionResolver">Configuring a global <code>RolePermissionResolver</code></h4>
<div class="paragraph">
<p>Similar in concept to a <code>PermissionResolver</code>, a <a href="static/current/apidocs/org/apache/shiro/authz/permission/RolePermissionResolver.html"><code>RolePermissionResolver</code></a> has the ability to represent <code>Permission</code> instances needed by a <code>Realm</code> to perform permission checks.</p>
</div>
<div class="paragraph">
<p>The key difference with a <code>RolePermissionResolver</code> however is that the input <code>String</code> is a <em>role name</em>, and <em>not</em> a permission string.</p>
</div>
<div class="paragraph">
<p>A <code>RolePermissionResolver</code> can be used by a <code>Realm</code> internally when needing to translate a role name into a concrete set of <code>Permission</code> instances.</p>
</div>
<div class="paragraph">
<p>This is a particularly useful feature for supporting legacy or inflexible data sources that may have no notion of permissions.</p>
</div>
<div class="paragraph">
<p>For example, many LDAP directories store role names (or group names) but do not support association of role names to concrete permissions because they have no 'permission' concept. A Shiro-based application can use the role names stored in LDAP, but implement a <code>RolePermissionResolver</code> to convert the LDAP name into a set of explicit permissions to perform preferred explicit access control. The permission associations would be stored in another data store, probably a local database.</p>
</div>
<div class="paragraph">
<p>Because this notion of converting role names to permissions is very application specific, Shiro&#8217;s default <code>Realm</code> implementations do not use them.</p>
</div>
<div class="paragraph">
<p>However, if you want to create your own <code>RolePermissionResolver</code> and have more than one <code>Realm</code> implementation that you want to configure with it, you can set your <code>RolePermissionResolver</code> globally for all <code>Realms</code> that can be configured with one.</p>
</div>
<div class="paragraph">
<p><strong>shiro.ini</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">globalRolePermissionResolver = com.foo.bar.authz.MyPermissionResolver
...
securityManager.authorizer.rolePermissionResolver = $globalRolePermissionResolver
...</code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<div class="title">RolePermissionResolverAware</div>
<p>If you want to configure a global <code>RolePermissionResolver</code>, each <code>Realm</code> that is to receive the configured <code>RolePermissionResolver</code> <strong>must</strong> implement the
<a href="static/current/apidocs/org/apache/shiro/authz/permission/RolePermissionResolverAware.html"><code>RolePermissionResolverAware</code></a> interface.
This guarantees that the configured global <code>RolePermissionResolver</code> instance can be relayed to each <code>Realm</code> that supports such configuration.
If you don&#8217;t want to use a global <code>RolePermissionResolver</code> or you don&#8217;t want to be bothered with the <code>RolePermissionResolverAware</code> interface, you can always configure
a realm with a <code>RolePermissionResolver</code> instance explicitly (assuming there is a JavaBeans-compatible setRolePermissionResolver method).</p>
</div>
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-ini hljs" data-lang="ini">rolePermissionResolver = com.foo.bar.authz.MyRolePermissionResolver
realm = com.foo.bar.realm.MyCustomRealm
realm.rolePermissionResolver = $rolePermissionResolver
...</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Authentication-AuthorizingSubjects-CustomAuthorizer">Custom Authorizer</h3>
<div class="paragraph">
<p>If your application uses more than one realm to perform authorization and the <code>ModularRealmAuthorizer</code> is default simple
iteration-based, short-circuiting authorization behavior does not suit your needs, you will probably want to create a custom <code>Authorizer</code> and configure the <code>SecurityManager</code> accordingly.</p>
</div>
<div class="paragraph">
<p>For example, in <code>shiro.ini</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-ini hljs" data-lang="ini">[main]
...
authorizer = com.foo.bar.authz.CustomAuthorizer
securityManager.authorizer = $authorizer</code></pre>
</div>
</div>
</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>&nbsp;|&nbsp;
<a href="https://www.apache.org/licenses/LICENSE-2.0.html">License</a>&nbsp;
<p class="text-muted">Copyright &copy; 2008-2024 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/main/src/site/content/authorization.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>