Apache Shiro: Java Authentication, Authorization and Session Management

What Apache Shiro solves, and who it is for

Shiro targets a specific gap: a Java application that needs authentication, authorization, cryptography and session management without adopting a full stack framework to get them. The README describes it as a "Java security framework that performs authentication, authorization, cryptography, and session management", and the intended range is broad, from mobile applications to web and enterprise applications.

The practical audience is Java teams who already have an application and want to add a security layer to it, rather than teams starting from a framework that ships security as one of its modules. The repository layout reflects that. There is a core/ module, a web/ module, a crypto/ module, a cache/ module, a config/ module, an event/ module, a lang/ module and a support/ module, plus an integration-tests/ tree and a samples/ directory. Those module names map directly onto the four capabilities the README lists, which tells you the project is organized around separable concerns rather than one monolithic jar.

It is not a general purpose identity product. There is no mention of an admin console, a user directory, or a hosted service. Shiro is a library you embed, and the samples directory (samples/quickstart, samples/spring-boot, samples/spring-boot-web, samples/guice, samples/spring-mvc, samples/servlet-plugin) shows the range of hosts it expects to sit inside.

How Shiro's modules and samples are organized

The architecture visible in the repository is a set of Maven modules under one root pom.xml, with the samples kept in a separate samples/pom.xml. The core/ directory holds the framework itself, web/ holds the servlet-facing integration, crypto/ holds the cryptographic support the README names, and cache/, config/, event/, lang/ and support/ hold the supporting pieces.

That split matters when you pick dependencies. Pulling shiro-core gives you the framework, not a web filter chain. The web integration is a different artifact under web/, and the samples confirm this: samples/servlet-plugin exists separately from samples/quickstart, and samples/quickstart-guice sits alongside samples/quickstart. If you are wiring Shiro into a servlet container, the sample to read is not the quickstart.

The integration-tests/ directory is a separate top-level entry, which suggests cross-module behavior is exercised outside the individual module test trees. The tools/ directory and the test-coverage/ directory are also top-level, so build and coverage configuration is centralized rather than per-module. For an adopter, the useful signal is that the project ships a samples/pom.xml, meaning the examples are built as a unit and are expected to compile against the same release as the modules.

Installing Apache Shiro and running the quickstart sample

The README does not contain install instructions. It points to https://shiro.apache.org for documentation and examples, and lists two tutorials there: the 10 Minute Tutorial and the Web Application tutorial. The Maven Central badge in the README links to the org.apache.shiro:shiro-core artifact, so Maven coordinates are the documented distribution channel.

The dependency to add is org.apache.shiro:shiro-core, with a version taken from the release list such as 3.0.1, which corresponds to the shiro-root-3.0.1 release. The repository root contains mvnw and mvnw.cmd, so the Maven wrapper is the intended entry point for building from the tree itself, and samples/pom.xml is the aggregator for the example projects.

What the README does not document is what the quickstart prints or which command builds it. The 10 Minute Tutorial and the Web Application tutorial on the project site are the two places the README directs you to for that. For a web application, the closest starting point in the repository is samples/spring-boot-web or samples/servlet-plugin, not the quickstart.

Where Shiro is the wrong tool

The README is a pointer, not a manual. It is roughly a description, a link to the project site, two tutorial links, and a licence line. There is no configuration reference, no list of supported Java versions, and no upgrade guide in the README. Anyone who judges the project by its README alone will conclude it is undocumented, which is not accurate but is a real cost: every question routes through shiro.apache.org.

The release history is the second constraint. The repository shows shiro-root-3.0.0 in June 2026, shiro-root-3.0.1 in August 2026, and shiro-root-2.2.1 also in June 2026. That means two supported lines exist at once, and the README does not describe what changed between 2.x and 3.x or whether 2.2.1 is a maintenance branch. If you are on 2.x, the repository does not tell you what a 3.x move involves. Check RELEASE-NOTES before planning an upgrade; that file is at the top level of the repository.

Finally, this is a Java framework. The topics list java, library, shiro and web-framework, and every sample is a Java or JVM build. If your application is not on the JVM, Shiro is not a candidate regardless of how well its feature list matches your requirements.

Apache Shiro compared with Spring Security

The natural alternative for a Java team is Spring Security, and the difference is structural rather than a matter of feature checklists. Spring Security is built around the Spring container: its configuration, its filter chain and its dependency injection are the mechanism, so adopting it inside a Spring application is close to free, and adopting it outside Spring means bringing Spring along.

Shiro is the reverse. The README frames it as a standalone framework whose API is meant to be understood quickly and applied to "any application", and the samples directory bears that out: alongside samples/spring-boot and samples/spring-boot-web there are samples/guice, samples/spring, samples/spring-mvc, samples/spring-hibernate, samples/aspectj and samples/servlet-plugin. That spread is the point. Shiro is designed to attach to a Guice application or a plain servlet application as readily as to a Spring one.

The trade-off is integration depth. If your application is already Spring-based and you want security to participate in the same container, Spring Security is the shorter path. If your application predates Spring, uses Guice, or is a servlet application you do not want to restructure, Shiro's independence is the reason to choose it. Note that Shiro still ships Spring samples, so the two are not mutually exclusive in a codebase; the question is which one owns the configuration.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-22. The most recent release listed is shiro-root-3.0.1 from 2026-08-23, following shiro-root-3.0.0 on 2026-06-20. There is also a shiro-root-2.2.1 release from 2026-06-14, so the 2.x line received a release in the same period as 3.0.0. That pattern is worth reading carefully: it suggests 2.x is still being serviced, but the repository does not state a support policy or an end-of-life date for either line, so do not assume one.

The upgrade cost is the part you cannot estimate from this repository. There is a RELEASE-NOTES file at the top level and a SECURITY.md, but the README does not summarize either, and the repository gives no compatibility statement between 2.x and 3.x. If you are planning a major version move, RELEASE-NOTES is the first file to read, and it is the only source in the repository that can speak to it.

The licence is Apache License, Version 2.0, stated in the README and present as the LICENSE file. For most adopters that is the permissive case: no copyleft obligation on your own code. The NOTICE file at the top level is the one to carry forward if you redistribute, since Apache projects use it for attribution. This is a description of what the repository contains, not legal advice; your own counsel decides what your distribution requires.

Editorial conclusion

Adopt Apache Shiro if you have a Java application that needs authentication, authorization and session handling behind one API, and you are willing to read the project site rather than the README. Skip it if you need a framework whose migration path between major versions is spelled out in the repository, or if you are not on Java. Before committing, verify three things: which 3.x artifact you need (shiro-core alone is not a web integration), what the 2.x to 3.x upgrade requires, because the release notes for shiro-root-3.0.0 are the only place that can say, and whether the sample closest to your stack (samples/spring-boot-web or samples/quickstart) still matches the API you plan to call.

Frequently asked questions

Official sources

1. apache/shiro on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases