Fork me on GitHub

Apache Shiro Logo Simple. Java. Security. Apache Software Foundation Event Banner

Apache Shiro Security Model

Handy Hint
Shiro v1 version notice

As of February 28, 2024, Shiro v1 was superseded by v2.
Table of Contents

This document describes Apache Shiro’s security model, including the assumptions and guarantees the framework makes with respect to security. It serves as a reference for operators deploying Shiro-secured applications and security researchers assessing potential vulnerabilities.

Overview

Apache Shiro is an application security framework that provides authentication, authorization, cryptography, and session management. Shiro is designed to be used as a library integrated into your application—it is not a standalone security service or server.

Shiro is a security framework, not a security solution. The security of your application depends on how you configure and integrate Shiro, your application’s architecture, and your operational environment.

Trust Boundaries

Application-Level Trust

Shiro operates within the trust boundary of your application’s JVM process. It assumes:

  • The application code invoking Shiro APIs is trusted.

  • Configuration files (INI, properties, Spring beans, etc.) are controlled by trusted administrators.

  • The JVM and underlying operating system are secure.

  • Any Realm implementations and their backing data sources are trustworthy.

Input Trust

Shiro does not assume that end-user input is trustworthy. Authentication credentials, session tokens, and other user-provided data are validated through configured security mechanisms.

However, Shiro relies on the application to:

  • Properly sanitize and validate any user input before passing it to Shiro APIs.

  • Protect sensitive configuration values from exposure.

  • Implement proper transport-layer security (TLS/SSL) for credential transmission.

Authentication Guarantees

What Shiro Provides

  • Credential Matching: Shiro verifies submitted credentials against stored credentials using configurable CredentialsMatcher implementations.

  • Realm Coordination: When multiple Realms are configured, the AuthenticationStrategy determines success/failure criteria.

  • Subject Identity: Upon successful authentication, Shiro establishes a Subject with verified principals.

  • Remember Me: Optional functionality to recognize returning users without full re-authentication (with weaker security guarantees than full authentication).

Operator Responsibilities

  • Credential Storage: Operators must ensure credentials are stored securely (hashed with appropriate algorithms like bcrypt or Argon2).

  • Brute-Force Protection: Shiro only includes built-in basic rate limiting for Jakarta EE only, but does not include account lockout. Operators should implement these controls at the application or infrastructure level.

  • Multi-Factor Authentication: MFA is not built into core Shiro; operators requiring MFA must implement custom Realm or AuthenticationStrategy extensions.

Username Enumeration

By default, Shiro may reveal whether a username exists through different error responses for "unknown account" vs "incorrect password" scenarios. If username enumeration is a concern for your deployment:

  • Configure your Realm to throw consistent exceptions regardless of failure reason.

  • Return generic authentication failure messages to end users.

Authorization Guarantees

What Shiro Provides

  • Permission Resolution: Shiro resolves whether a Subject has specific permissions through configured Realm instances and permission resolvers.

  • Role Checking: Both implicit role checks (hasRole) and explicit permission-based checks (isPermitted) are supported.

  • Wildcard Permissions: The WildcardPermission implementation provides flexible, hierarchical permission strings (e.g., printer:print:lp7200).

  • Annotation Support: Declarative security via @RequiresAuthentication, @RequiresPermissions, @RequiresRoles, and related annotations.

Operator Responsibilities

  • Permission Assignment: Operators must correctly configure permission-to-role and role-to-user mappings in their data model.

  • Least Privilege: Shiro enforces permissions as configured; designing an appropriate permission model is the operator’s responsibility.

  • Realm Security: Authorization data sources (LDAP, databases, etc.) must be secured appropriately.

Session Management

What Shiro Provides

  • Container-Independent Sessions: Shiro can manage sessions without a Servlet container or EJB.

  • Session Validation: Configurable session timeout and validation scheduling.

  • Session Persistence: Pluggable SessionDAO for persisting sessions to any data store.

  • Session Fixation Prevention: Shiro can regenerate session IDs upon authentication when properly configured.

Security Considerations

  • Session ID Exposure: Session identifiers should be treated as sensitive credentials. Transmit only over secure channels.

  • Session Storage: If using persistent sessions (e.g., database-backed SessionDAO), secure the backing store appropriately.

  • Clustering: In clustered deployments, ensure session serialization and shared storage are configured securely.

Cryptography

What Shiro Provides

  • Hashing: Simplified APIs for cryptographic hashing (SHA-256, SHA-512, MD5, etc.) with salt and iteration support.

  • Encryption/Decryption: CipherService implementations for symmetric encryption (AES, Blowfish, etc.).

  • Password Hashing: PasswordService for secure credential hashing with configurable algorithms (Argon2, BCrypt).

Important Notes

  • Shiro’s cryptographic utilities are wrappers around standard Java cryptography (JCA/JCE) and BouncyCastle libraries.

  • Algorithm Selection: Operators must choose appropriate algorithms. Avoid deprecated algorithms (MD5, SHA-1 for security purposes). Avoid weak algorithms for passwords (use Argon2 or BCrypt with appropriate work factors).

  • Key Management: Shiro does not provide key management infrastructure. Secure key storage and rotation is the operator’s responsibility.

Web Security

What Shiro Provides

  • Filter Chain: URL-based security through configurable filter chains.

  • CSRF Protection: Not built-in; operators should implement CSRF tokens in their applications.

  • Path Matching: Shiro matches request paths against configured patterns using Ant-style path matching by default.

Path Traversal Considerations

Shiro relies on the Servlet container’s path normalization. When integrating with certain frameworks or configurations:

  • Ensure consistent path interpretation between Shiro and your web framework.

  • Review Security Reports for historical path traversal issues and mitigations.

  • Keep Shiro updated to receive security fixes.

Version Discovery

Shiro does not actively prevent discovery of its version through error messages or HTTP headers. If version disclosure is a concern:

  • Configure custom error pages that do not reveal framework details.

  • Remove or modify any version-revealing response headers at the web server or proxy level.

Logging

Shiro logs security events (authentication attempts, authorization failures, etc.) using SLF4J. By default:

  • Credentials are not logged: Shiro does not log plaintext passwords or sensitive credentials.

  • Principals may be logged: Usernames and other identifying information may appear in logs.

  • Session IDs may be logged: Debug-level logging may include session identifiers.

Operators should:

  • Review logging configuration for appropriate verbosity in production.

  • Secure log files with appropriate access controls.

  • Consider log aggregation and monitoring for security event detection.

Deployment Recommendations

Minimum Security Baseline

  1. Use the latest stable Shiro release.

  2. Configure TLS for all credential transmission.

  3. Use strong password hashing (bcrypt or Argon2 with appropriate work factors).

  4. Implement session fixation prevention, if not using built-in session management.

  5. Review and restrict default configurations.

Defense in Depth

Shiro should be one layer in a defense-in-depth security strategy:

  • Implement network-level access controls.

  • Use Web Application Firewalls (WAF) for additional request filtering.

  • Employ rate limiting and brute-force protection at the infrastructure level.

  • Conduct regular security assessments and penetration testing.

Adversary Model

Shiro’s security model assumes the following adversary classes:

External Untrusted Adversary (in scope)

The primary adversary Shiro defends against is an unauthenticated or authenticated-but-low-privilege network user attempting to access an application that integrates Shiro. This adversary can:

  • Submit arbitrary authentication credentials, session identifiers, and request data.

  • Observe authentication error responses (including timing).

  • Attempt session fixation, privilege escalation, and authorization bypass.

This adversary cannot:

  • Run code in the application’s JVM process.

  • Read or modify application configuration files.

  • Tamper with Realm implementations or their backing data sources.

Authenticated User with Limited Privileges (in scope)

Shiro’s authorization model defends against privilege escalation by an authenticated user. A user authenticated under one principal must not gain access to resources they are not authorized for. Applications must not allow manipulation of permission strings or other inputs that could lead to unauthorized access. Shiro’s role and permission checks are only as secure as the application’s permission model and input handling.

Adversaries Out of Scope

The following adversary classes are explicitly not part of Shiro’s threat model — defending against them is the application’s or operator’s responsibility:

  • Application Code: As stated in Application-Level Trust, Shiro trusts the code that invokes its APIs. An attacker who can execute arbitrary code in the application’s JVM has already won at Shiro’s layer.

  • Administrators with Configuration Access: An attacker controlling INI files, Spring beans, or other configuration sources can disable security controls. Shiro relies on operators to secure these.

  • Local Shell Access / Co-Tenants: An attacker with shell access to the host can read process memory, log files, and the keystore. Shiro does not defend against this; isolate Shiro-secured applications appropriately.

  • Compromised Realms: An attacker controlling the LDAP server, database, or other Realm backing data can grant arbitrary access. Realm data sources are part of the trust boundary.

Known Non-Findings

The following recurring report categories are explicitly not security vulnerabilities under Shiro’s model. Reporters should consult this list before filing — a report matching one of these will be closed with a reference back to this section.

Username Enumeration via Differential Error Responses

By default, Shiro returns different exceptions for "unknown account" vs "incorrect password" (see Username Enumeration). This is the framework’s default behavior; applications that need to prevent enumeration must configure their Realm to return consistent exceptions, as documented above.

Username and Session ID Appearing in Logs

As stated in Logging, principals (usernames) may appear in Shiro’s SLF4J logs, and session identifiers may appear at DEBUG level. This is by design — log content is the operator’s responsibility to secure. Plaintext passwords are not logged; that’s the property Shiro maintains.

Shiro Version Disclosure

Per Version Discovery, Shiro does not actively prevent version disclosure through error messages or response headers. Operators who treat version disclosure as a finding must configure their web server, proxy, or custom error pages accordingly.

Deprecated Hash Algorithms Exposed in the Hashing API

Shiro’s Hash and HashService APIs expose MD5, SHA-1, and other algorithms that are no longer considered safe for new password hashing. These remain available for legacy interoperability and for non-security uses (e.g., content checksums). Reports that "Shiro supports MD5" are not findings; the framework’s default for password hashing is the secure PasswordService. Operators must select appropriate algorithms.

RememberMe with Weaker Authentication Guarantees

Per What Shiro Provides under Authentication Guarantees, the RememberMe mechanism explicitly provides weaker guarantees than full authentication. Reports that RememberMe-identified subjects bypass full authentication are not findings; the security tradeoff is documented and intentional.

Pluggable Cryptography Allowing Weak Configurations

Shiro’s CipherService, Hash, and related APIs are pluggable and accept any algorithm registered with the JCA. Configuring Shiro to use a weak cipher is an operator misconfiguration, not a framework vulnerability. Shiro’s role is to provide secure defaults and clear documentation, which it does.

CSRF, MFA, Account Lockout

Per Web Security, Operator Responsibilities under Authentication Guarantees, and elsewhere, CSRF protection, MFA, and account lockout are explicitly not built into Shiro. Operators must implement these at the application or infrastructure level. Reports that "Shiro is missing CSRF protection" are not framework vulnerabilities.

Triage Dispositions

The Shiro PMC classifies inbound vulnerability reports into one of the following dispositions. Each links to the section of this document that licenses the call.

Disposition Meaning Licensed by

VALID

The report describes a real violation of a property Shiro provides (authentication / authorization / session-handling / crypto / web-security guarantees), accessible to an in-scope adversary through an in-scope code path. Fixed via coordinated disclosure and CVE.

Authentication Guarantees, Authorization Guarantees, Session Management, Cryptography, Web Security, Adversary Model

VALID-HARDENING

No property in this model is violated, but the PMC elects to add defensive hardening (e.g., narrowing an API that’s easy to misuse). Triaged privately; fixed at PMC discretion; typically no CVE.

PMC discretion

OUT-OF-MODEL: trusted-input

The report requires the attacker to control a value or input Shiro treats as trusted (application code, configuration files, realm data).

Trust Boundaries

OUT-OF-MODEL: adversary-not-in-scope

The report requires attacker capabilities Shiro does not defend against (local shell access, JVM control, administrator privileges).

Adversaries Out of Scope

BY-DESIGN: property-disclaimed

The report concerns a property Shiro explicitly does not provide (CSRF, MFA, account lockout, key management, version concealment, etc.).

Web Security, Operator Responsibilities, Cryptography, Version Discovery

KNOWN-NON-FINDING

The report matches one of the documented categories in Known Non-Findings.

Known Non-Findings

MODEL-GAP

The report cannot be cleanly routed to any of the above. This indicates a gap in the security model itself; the PMC revises the model rather than ad-hoc-deciding the report.

triggers a model revision

Reporting Security Vulnerabilities

If you discover a security vulnerability in Apache Shiro, please report it privately to the security team:

Do not disclose security vulnerabilities publicly until a fix is available and an advisory has been published.

Additional Resources