This is an automated email from the ASF dual-hosted git repository.
lprimak pushed a commit to branch asf-staging
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
The following commit(s) were added to refs/heads/asf-staging by this push:
new 93cfaab36 migration guide
93cfaab36 is described below
commit 93cfaab362b28ef351aee3f79587569d2c6361ab
Author: lprimak <[email protected]>
AuthorDate: Wed Jan 21 11:44:24 2026 -0600
migration guide
---
.well-known/security.txt | 2 +-
documentation.html | 3 +
feed.xml | 2 +-
guides.html | 3 +
migration-guide.html | 762 +++++++++++++++++++++++++++++++++++++++++++++++
sitemap.xml | 82 ++---
6 files changed, 813 insertions(+), 41 deletions(-)
diff --git a/.well-known/security.txt b/.well-known/security.txt
index c3e20a515..324797428 100644
--- a/.well-known/security.txt
+++ b/.well-known/security.txt
@@ -1,5 +1,5 @@
Contact: mailto:[email protected]
-Expires: 2027-01-21T17:30:39Z
+Expires: 2027-01-21T17:43:59Z
Preferred-Languages: en
Canonical: https://shiro.apache.org/.well-known/security.txt
Policy: https://shiro.apache.org/security-reports.html
\ No newline at end of file
diff --git a/documentation.html b/documentation.html
index 028191416..4e88d91e8 100644
--- a/documentation.html
+++ b/documentation.html
@@ -270,6 +270,9 @@
<p><a href="realm.html">Realm Guide</a></p>
</li>
<li>
+<p><a href="migration-guide.html">Migration Guide: Upgrading from Shiro 1.x to
2.x and 3.x</a></p>
+</li>
+<li>
<p>Community-contributed <a href="articles.html">Articles</a></p>
</li>
</ul>
diff --git a/feed.xml b/feed.xml
index 060fa38b8..06d0dea98 100644
--- a/feed.xml
+++ b/feed.xml
@@ -4,7 +4,7 @@
<subtitle>Simple. Java. Security.</subtitle>
<link href="https://shiro.apache.org/"/>
<link rel="self" href="https://shiro.apache.org/feed.xml"; />
- <updated>2026-01-21T17:30:39Z</updated>
+ <updated>2026-01-21T17:43:59Z</updated>
<author>
<name>Les Hazlewood</name>
diff --git a/guides.html b/guides.html
index 944eee923..adb432df1 100644
--- a/guides.html
+++ b/guides.html
@@ -230,6 +230,9 @@
<li>
<p><a href="java-authorization-guide.html">Authorization Guide</a></p>
</li>
+<li>
+<p><a href="migration-guide.html">Migration Guide: Upgrading Shiro 1.x → 2.x →
3.x</a></p>
+</li>
</ul>
</div>
<hr />
diff --git a/migration-guide.html b/migration-guide.html
new file mode 100644
index 000000000..e9c539798
--- /dev/null
+++ b/migration-guide.html
@@ -0,0 +1,762 @@
+<!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 Migration Guide | Apache Shiro</title>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <meta name="keywords" content='documentation,migration,upgrade'>
+ <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 Migration Guide | 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="2026-01-19T00:00:00Z"/>
+ <meta property="article:tag" content='documentation'/>
+ <meta property="article:tag" content='migration'/>
+ <meta property="article:tag" content='upgrade'/>
+ <meta property="og:locale" content="en_US" />
+ <meta property="og:url"
content='https://shiro.apache.org/migration-guide.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(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(['trackPageView']);
+ _paq.push(['enableLinkTracking']);
+ (function() {
+ var u="https://analytics.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><a class="dropdown-item"
href="dependency-chain.html">Jakarta EE with Dependency Chains</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-model.html">Security Model</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 Migration Guide</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 February 28, 2024, Shiro v1 was 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="#overview">Overview</a></li>
+<li><a href="#migrating-1x-to-2x">Migrating from Shiro 1.x to 2.x</a>
+<ul class="sectlevel2">
+<li><a href="#1x-java-version">Java Version Requirements</a></li>
+<li><a href="#1x-jakarta-ee">Jakarta EE Support</a></li>
+<li><a href="#1x-spring">Spring and Spring Boot Compatibility</a></li>
+<li><a href="#1x-breaking-changes">What Might Break</a></li>
+</ul>
+</li>
+<li><a href="#migrating-2x-to-3x">Migrating from Shiro 2.x to 3.x</a>
+<ul class="sectlevel2">
+<li><a href="#2x-java-version">Java Version Requirements</a></li>
+<li><a href="#2x-jakarta-ee">Jakarta EE Native Support</a></li>
+<li><a href="#2x-spring">Spring Boot 4 Support</a></li>
+</ul>
+</li>
+<li><a href="#security-behavior-changes">Security Behavior Changes in 3.x</a>
+<ul class="sectlevel2">
+<li><a href="#deny-by-default">Deny Access by Default</a></li>
+<li><a href="#case-insensitive-matching">Case-Insensitive URL Matching</a></li>
+<li><a href="#cors-preflight">CORS Preflight Enabled by Default</a></li>
+</ul>
+</li>
+<li><a href="#configuration-examples">Configuration Examples</a>
+<ul class="sectlevel2">
+<li><a href="#reverting-all-behaviors">Reverting All 3.x Behaviors to Legacy
Defaults</a></li>
+<li><a href="#recommended-3x-config">Recommended Secure Configuration</a></li>
+</ul>
+</li>
+<li><a href="#common-migration-pitfalls">Common Migration Pitfalls</a>
+<ul class="sectlevel2">
+<li><a href="#missing-filter-definitions">Missing Filter Definitions</a></li>
+<li><a href="#mixed-classifiers">Mixed Dependency Classifiers</a></li>
+<li><a href="#spring-version-mismatch">Spring Version Mismatch</a></li>
+<li><a href="#realm-api-changes">Realm API Changes</a></li>
+<li><a href="#session-configuration">Session Configuration Changes</a></li>
+<li><a href="#testing-after-migration">Insufficient Testing</a></li>
+</ul>
+</li>
+<li><a href="#further-reading">Further Reading</a></li>
+</ul>
+</div>
+<div id="preamble">
+<div class="sectionbody">
+<div class="paragraph">
+<p>This guide covers the significant changes between major Shiro releases and
provides practical guidance for upgrading your applications. Whether you are
moving from 1.x to 2.x or from 2.x to 3.x, this document explains what changed,
why it matters, and how to adapt your code and configuration.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="overview">Overview</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Apache Shiro has evolved considerably across its major versions. Each
release brings improvements in security defaults, compatibility with modern
Java and Jakarta EE specifications, and better integration with Spring
ecosystems. However, these improvements sometimes require changes to existing
applications.</p>
+</div>
+<div class="paragraph">
+<p>The migration path depends on your starting point:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>1.x to 2.x</strong>: Focuses on Java 11 adoption and optional
Jakarta EE namespace support via classifiers</p>
+</li>
+<li>
+<p><strong>2.x to 3.x</strong>: Brings Java 17 as the baseline, native Jakarta
EE 10+ support, and several security behavior changes that affect default
application behavior</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Before upgrading, review your current Shiro version and dependencies, then
follow the appropriate section below.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="migrating-1x-to-2x">Migrating from Shiro 1.x to 2.x</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Shiro 2.x represents a significant step forward in terms of Java platform
requirements and Jakarta EE support. If your application currently runs on
Shiro 1.x, this section covers everything you need to consider.</p>
+</div>
+<div class="sect2">
+<h3 id="1x-java-version">Java Version Requirements</h3>
+<div class="paragraph">
+<p>Shiro 1.x supported Java 8 as its minimum runtime. Starting with Shiro 2.x,
the minimum Java version is <strong>Java 11</strong>.</p>
+</div>
+<div class="paragraph">
+<p>This change reflects the broader ecosystem shift away from Java 8. If your
application still runs on Java 8, you will need to upgrade your runtime before
adopting Shiro 2.x. Most application servers and cloud platforms now support
Java 11 or later, so this should not present significant obstacles for most
deployments.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="1x-jakarta-ee">Jakarta EE Support</h3>
+<div class="paragraph">
+<p>One of the most notable changes in Shiro 2.x is support for Jakarta EE 8
through 11. However, there is an important distinction in how this support is
provided.</p>
+</div>
+<div class="paragraph">
+<p>For applications that require the <code>jakarta.*</code> namespace (Jakarta
EE 9 and later), Shiro 2.x artifacts are published with a <code>jakarta</code>
classifier. This means you need to explicitly request the Jakarta-namespaced
version of each dependency.</p>
+</div>
+<div class="paragraph">
+<p>Here is an example Maven configuration for Jakarta EE 9+ applications:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs"
data-lang="xml"><dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-core</artifactId>
+ <version>2.0.0</version>
+ <classifier>jakarta</classifier>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-web</artifactId>
+ <version>2.0.0</version>
+ <classifier>jakarta</classifier>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If your application still uses the <code>javax.*</code> namespace (Java EE
8 or Jakarta EE 8), you can use the standard artifacts without any
classifier:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs"
data-lang="xml"><dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-core</artifactId>
+ <version>2.0.0</version>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This dual-artifact approach allows Shiro 2.x to support both legacy and
modern Jakarta EE applications without forcing an immediate namespace
migration.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="1x-spring">Spring and Spring Boot Compatibility</h3>
+<div class="paragraph">
+<p>Shiro 2.x provides compatibility with both Spring Boot 2.x and Spring Boot
3.x. However, the dependency you choose depends on your Spring version and
namespace requirements.</p>
+</div>
+<div class="paragraph">
+<p>For Spring Boot 2.x applications (using <code>javax.*</code> namespace):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs"
data-lang="xml"><dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-spring-boot-web-starter</artifactId>
+ <version>2.0.0</version>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>For Spring Boot 3.x applications (using <code>jakarta.*</code>
namespace):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs"
data-lang="xml"><dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-spring-boot-web-starter</artifactId>
+ <version>2.0.0</version>
+ <classifier>jakarta</classifier>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Make sure all Shiro dependencies in your project use consistent
classifiers. Mixing classifier and non-classifier artifacts will result in
classpath conflicts.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="1x-breaking-changes">What Might Break</h3>
+<div class="paragraph">
+<p>Most applications migrating from 1.x to 2.x will not encounter breaking
changes in Shiro itself, assuming you meet the Java 11 requirement. The primary
areas to watch are:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>Third-party integrations</strong> that depend on specific Shiro
internal classes or behaviors</p>
+</li>
+<li>
+<p><strong>Custom Realm implementations</strong> that override deprecated
methods</p>
+</li>
+<li>
+<p><strong>Direct usage of servlet APIs</strong> where namespace changes
apply</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Review your custom Shiro code and test thoroughly after upgrading.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="migrating-2x-to-3x">Migrating from Shiro 2.x to 3.x</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Shiro 3.x introduces more substantial changes compared to the 2.x release.
Beyond the platform requirements, several default behaviors have changed to
improve security out of the box. Applications upgrading to 3.x should carefully
review each section below.</p>
+</div>
+<div class="sect2">
+<h3 id="2x-java-version">Java Version Requirements</h3>
+<div class="paragraph">
+<p>The minimum Java version for Shiro 3.x is <strong>Java 17</strong>. This
aligns with the long-term support releases favored by enterprise environments
and ensures compatibility with modern language features and performance
improvements.</p>
+</div>
+<div class="paragraph">
+<p>If your application runs on Java 11, you will need to upgrade to Java 17 or
later before adopting Shiro 3.x.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="2x-jakarta-ee">Jakarta EE Native Support</h3>
+<div class="paragraph">
+<p>Unlike Shiro 2.x, which required classifiers for Jakarta namespace support,
Shiro 3.x uses the Jakarta EE 10+ namespace natively. There are no classifiers
needed—the standard artifacts already use <code>jakarta.*</code> packages.</p>
+</div>
+<div class="paragraph">
+<p>This simplifies dependency management considerably:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs"
data-lang="xml"><dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-core</artifactId>
+ <version>3.0.0</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-web</artifactId>
+ <version>3.0.0</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-jakarta-ee</artifactId>
+ <version>3.0.0</version>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If your application still requires <code>javax.*</code> namespace support,
you must remain on Shiro 2.x or complete your Jakarta EE migration before
upgrading.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="2x-spring">Spring Boot 4 Support</h3>
+<div class="paragraph">
+<p>Shiro 3.x is designed to work with Spring Boot 4 and later versions. Spring
Boot 4 itself requires Jakarta EE 10+, which aligns naturally with Shiro
3.x’s native Jakarta support.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs"
data-lang="xml"><dependency>
+ <groupId>org.apache.shiro</groupId>
+ <artifactId>shiro-spring-boot-web-starter</artifactId>
+ <version>3.0.0</version>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Applications still on Spring Boot 2.x or 3.x should use Shiro 2.x with the
appropriate classifier configuration.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="security-behavior-changes">Security Behavior Changes in 3.x</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Shiro 3.x introduces several changes to default security behavior. These
changes reflect current security best practices, but they may affect existing
applications that relied on previous defaults.</p>
+</div>
+<div class="sect2">
+<h3 id="deny-by-default">Deny Access by Default</h3>
+<div class="paragraph">
+<p>In earlier Shiro versions, web applications would allow access to URLs by
default unless explicitly restricted. Starting with Shiro 3.x, the default
behavior is reversed: access is <strong>denied by default</strong>.</p>
+</div>
+<div class="paragraph">
+<p>This change prevents accidental exposure of endpoints that were not
explicitly configured in your filter chain. Any URL not matched by a filter
definition will be blocked.</p>
+</div>
+<div class="paragraph">
+<p>If you need to restore the previous allow-by-default behavior, you can
configure this explicitly.</p>
+</div>
+<div class="paragraph">
+<p><strong>shiro.ini configuration:</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-ini hljs"
data-lang="ini">[main]
+filterChainResolver.allowAccessByDefault = true</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><strong>Spring Boot (application.properties):</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-properties hljs"
data-lang="properties">shiro.allowAccessByDefault = true</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This setting should only be enabled if your application genuinely relies on
the previous behavior and you have verified that all sensitive endpoints are
explicitly protected.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="case-insensitive-matching">Case-Insensitive URL Matching</h3>
+<div class="paragraph">
+<p>Shiro 3.x enables case-insensitive URL matching by default. This means that
<code>/Admin</code>, <code>/admin</code>, and <code>/ADMIN</code> are all
treated as equivalent when matching filter chain definitions.</p>
+</div>
+<div class="paragraph">
+<p>Case-insensitive matching is a security improvement that prevents bypasses
on systems where URL handling might normalize case differently. However, if
your application relies on case-sensitive URL matching, you can disable this
behavior.</p>
+</div>
+<div class="paragraph">
+<p><strong>shiro.ini configuration:</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-ini hljs"
data-lang="ini">[main]
+filterChainResolver.caseInsensitive = false</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><strong>Spring Boot (application.properties):</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-properties hljs"
data-lang="properties">shiro.caseInsensitive = false</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="cors-preflight">CORS Preflight Enabled by Default</h3>
+<div class="paragraph">
+<p>Shiro 3.x enables CORS preflight request handling by default for
authentication filters. This allows browsers to send OPTIONS requests without
authentication, which is necessary for cross-origin API calls to work
correctly.</p>
+</div>
+<div class="paragraph">
+<p>In previous versions, preflight requests might be blocked by authentication
filters, causing CORS failures for legitimate API clients.</p>
+</div>
+<div class="paragraph">
+<p>If your application does not use CORS or you handle preflight requests
separately, you can disable this behavior.</p>
+</div>
+<div class="paragraph">
+<p><strong>shiro.ini configuration:</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-ini hljs"
data-lang="ini">[main]
+authcBasic.allowPreFlightRequests = false
+authcBearer.allowPreFlightRequests = false</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The setting applies per-filter, so configure it for each authentication
filter you use.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="configuration-examples">Configuration Examples</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>This section provides complete configuration examples for common
scenarios.</p>
+</div>
+<div class="sect2">
+<h3 id="reverting-all-behaviors">Reverting All 3.x Behaviors to Legacy
Defaults</h3>
+<div class="paragraph">
+<p>If you want to preserve the exact behavior from Shiro 2.x while running on
Shiro 3.x, use the following configuration:</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-ini hljs"
data-lang="ini">[main]
+# Allow access to unconfigured URLs (previous default)
+filterChainResolver.allowAccessByDefault = true
+
+# Use case-sensitive URL matching (previous default)
+filterChainResolver.caseInsensitive = false
+
+# Disable CORS preflight handling (previous default)
+authcBasic.allowPreFlightRequests = false
+authcBearer.allowPreFlightRequests = false</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><strong>Spring Boot (application.properties):</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-properties hljs"
data-lang="properties"># Allow access to unconfigured URLs (previous default)
+shiro.allowAccessByDefault = true
+
+# Use case-sensitive URL matching (previous default)
+shiro.caseInsensitive = false</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>For Spring Boot applications, CORS preflight settings must be configured
programmatically or via custom filter configuration.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="recommended-3x-config">Recommended Secure Configuration</h3>
+<div class="paragraph">
+<p>For new applications or those completing a full migration, the 3.x defaults
are recommended. You only need to configure your filter chains explicitly:</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-ini hljs"
data-lang="ini">[urls]
+/login = anon
+/logout = logout
+/static/** = anon
+/api/** = authcBearer
+/** = authc</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>With deny-by-default enabled, every path must have an explicit rule. The
configuration above ensures that:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Login and logout pages are accessible without authentication</p>
+</li>
+<li>
+<p>Static resources do not require authentication</p>
+</li>
+<li>
+<p>API endpoints require bearer token authentication</p>
+</li>
+<li>
+<p>All other paths require form-based authentication</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="common-migration-pitfalls">Common Migration Pitfalls</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Migrating to a new major version can surface unexpected issues. The
following are problems developers commonly encounter:</p>
+</div>
+<div class="sect2">
+<h3 id="missing-filter-definitions">Missing Filter Definitions</h3>
+<div class="paragraph">
+<p>With deny-by-default in 3.x, any URL without an explicit filter chain rule
will return a 403 error. If pages that previously worked now fail, check that
all necessary URL patterns are defined in your configuration.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="mixed-classifiers">Mixed Dependency Classifiers</h3>
+<div class="paragraph">
+<p>When using Shiro 2.x with Jakarta support, all Shiro dependencies must use
the <code>jakarta</code> classifier consistently. A single dependency without
the classifier can pull in <code>javax.*</code> classes and cause
NoClassDefFoundError or linkage errors at runtime.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="spring-version-mismatch">Spring Version Mismatch</h3>
+<div class="paragraph">
+<p>Shiro 3.x with Spring Boot 4 requires Jakarta EE. Attempting to use Shiro
3.x with Spring Boot 2.x will fail due to namespace conflicts. Match your Shiro
version to your Spring Boot version according to the compatibility information
provided in this guide.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="realm-api-changes">Realm API Changes</h3>
+<div class="paragraph">
+<p>Some deprecated methods in Realm implementations were removed in major
version transitions. If you have custom Realms, review them against the current
API and update any overridden methods that no longer exist in the parent
class.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="session-configuration">Session Configuration Changes</h3>
+<div class="paragraph">
+<p>Session management configuration options may have moved or been renamed
between versions. Review the session management documentation for your target
Shiro version to ensure your session timeout and cookie settings are applied
correctly.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="testing-after-migration">Insufficient Testing</h3>
+<div class="paragraph">
+<p>Security configurations can have subtle interactions. After migration, test
all authentication flows, authorization checks, and edge cases thoroughly.
Automated security tests are valuable for catching regressions that manual
testing might miss.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="further-reading">Further Reading</h2>
+<div class="sectionbody">
+<div class="ulist">
+<ul>
+<li>
+<p><a href="jakarta-ee.html">Jakarta EE Integration Guide</a></p>
+</li>
+<li>
+<p><a href="spring-boot.html">Spring Boot Integration Guide</a></p>
+</li>
+<li>
+<p><a href="web.html">Web Application Configuration</a></p>
+</li>
+<li>
+<p><a href="configuration.html">General Configuration Reference</a></p>
+</li>
+</ul>
+</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-2026 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/migration-guide.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>
diff --git a/sitemap.xml b/sitemap.xml
index d32e4768d..a1b6f55f1 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -1,5 +1,9 @@
<?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.apache.org/migration-guide.html</loc>
+ <lastmod>2026-01-19</lastmod>
+ </url>
<url>
<loc>https://shiro.apache.org/dependency-chain.html</loc>
<lastmod>2026-01-03</lastmod>
@@ -21,31 +25,31 @@
<lastmod>2016-10-23</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/what-is-shiro.html</loc>
+ <loc>https://shiro.apache.org/webapp-tutorial.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/spring-framework.html</loc>
+ <loc>https://shiro.apache.org/spring-boot.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/developers.html</loc>
+ <loc>https://shiro.apache.org/powered-by-shiro.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/cas.html</loc>
+ <loc>https://shiro.apache.org/developers.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/webapp-tutorial.html</loc>
+ <loc>https://shiro.apache.org/cas.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/spring-boot.html</loc>
+ <loc>https://shiro.apache.org/web.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/powered-by-shiro.html</loc>
+ <loc>https://shiro.apache.org/permissions.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -61,11 +65,7 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/web.html</loc>
- <lastmod>2010-03-18</lastmod>
- </url>
- <url>
- <loc>https://shiro.apache.org/permissions.html</loc>
+ <loc>https://shiro.apache.org/web-features.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -81,27 +81,31 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/web-features.html</loc>
+ <loc>https://shiro.apache.org/v2/command-line-hasher.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/integration.html</loc>
+ <loc>https://shiro.apache.org/session-management.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/authorization-features.html</loc>
+ <loc>https://shiro.apache.org/overview.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/v2/command-line-hasher.html</loc>
+ <loc>https://shiro.apache.org/integration.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/session-management.html</loc>
+ <loc>https://shiro.apache.org/authorization-features.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/overview.html</loc>
+ <loc>https://shiro.apache.org/tutorial.html</loc>
+ <lastmod>2010-03-18</lastmod>
+ </url>
+ <url>
+ <loc>https://shiro.apache.org/session-management-features.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -113,11 +117,11 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/tutorial.html</loc>
+ <loc>https://shiro.apache.org/tools.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/session-management-features.html</loc>
+ <loc>https://shiro.apache.org/securitymanager.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -137,11 +141,11 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/tools.html</loc>
+ <loc>https://shiro.apache.org/testing.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/securitymanager.html</loc>
+ <loc>https://shiro.apache.org/security-reports.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -153,11 +157,7 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/testing.html</loc>
- <lastmod>2010-03-18</lastmod>
- </url>
- <url>
- <loc>https://shiro.apache.org/security-reports.html</loc>
+ <loc>https://shiro.apache.org/terminology.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -177,7 +177,7 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/terminology.html</loc>
+ <loc>https://shiro.apache.org/roadmap.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -192,10 +192,6 @@
<loc>https://shiro.apache.org/articles.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
- <url>
- <loc>https://shiro.apache.org/roadmap.html</loc>
- <lastmod>2010-03-18</lastmod>
- </url>
<url>
<loc>https://shiro.apache.org/java-cryptography-guide.html</loc>
<lastmod>2010-03-18</lastmod>
@@ -208,6 +204,14 @@
<loc>https://shiro.apache.org/architecture.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
+ <url>
+ <loc>https://shiro.apache.org/support.html</loc>
+ <lastmod>2010-03-18</lastmod>
+ </url>
+ <url>
+ <loc>https://shiro.apache.org/reference.html</loc>
+ <lastmod>2010-03-18</lastmod>
+ </url>
<url>
<loc>https://shiro.apache.org/java-authorization-guide.html</loc>
<lastmod>2010-03-18</lastmod>
@@ -225,11 +229,11 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/support.html</loc>
+ <loc>https://shiro.apache.org/subject.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/reference.html</loc>
+ <loc>https://shiro.apache.org/realm.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
@@ -249,23 +253,23 @@
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/subject.html</loc>
+ <loc>https://shiro.apache.org/spring-xml.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/realm.html</loc>
+ <loc>https://shiro.apache.org/java-annotations.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/java-annotations.html</loc>
+ <loc>https://shiro.apache.org/command-line-hasher.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/command-line-hasher.html</loc>
+ <loc>https://shiro.apache.org/what-is-shiro.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
- <loc>https://shiro.apache.org/spring-xml.html</loc>
+ <loc>https://shiro.apache.org/spring-framework.html</loc>
<lastmod>2010-03-18</lastmod>
</url>
<url>
![https://www.apache.org/events/current-event-125x125.png"](https://www.apache.org/events/current-event-125x125.png"){kind=link}