Apache Shiro

https://shiro.apache.org/
Admin
Apache Shiro is a powerful and flexible Java security framework that performs authentication,...
Tokens:240,670
Snippets:2,029
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Enter the quickstart directory

Source: https://shiro.apache.org/10-minute-tutorial.html

Changes into the quickstart sample directory after unzipping.

```bash
$ cd shiro-root-3.0.1/samples/quickstart
```

--------------------------------

### Run the QuickStart with Maven

Source: https://shiro.apache.org/10-minute-tutorial.html

Compiles and runs the Quickstart sample. Prints log messages and exits.

```bash
$ mvn compile exec:java
```

--------------------------------

### Resource hashing examples

Source: https://shiro.apache.org/command-line-hasher.html

Examples of hashing various resource paths, including relative, absolute, and prefixed classpath/url resources.

```bash
<command> -r fileInCurrentDirectory.txt
<command> -r ../../relativePathFile.xml
<command> -r ~/documents/myfile.pdf
<command> -r ~/documents/myfile.pdf -a SHA-512
<command> -r /usr/local/logs/absolutePathFile.log
<command> -r url:http://foo.com/page.html <command> -r classpath:/WEB-INF/lib/something.jar
```

--------------------------------

### Example [roles] section with wildcard permissions

Source: https://shiro.apache.org/configuration.html

Shows how to define role-to-permission mappings in the [roles] section. The 'admin' role gets all permissions via the wildcard '*', 'schwartz' can do anything with lightsabers, and 'goodguy' is allowed to drive the winnebago with license plate 'eagle5'. Comments explain each mapping.

```ini
[roles]
# 'admin' role has all permissions, indicated by the wildcard '*'
admin = *
# The 'schwartz' role can do anything (*) with any lightsaber:
schwartz = lightsaber:*
# The 'goodguy' role is allowed to 'drive' (action) the winnebago (type) with
# license plate 'eagle5' (instance specific id)
goodguy = winnebago:drive:eagle5
```

--------------------------------

### Shiro INI configuration sections example

Source: https://shiro.apache.org/configuration.html

Shows the structure of a Shiro INI file with the [main], [users], [roles], and [urls] sections. Comments can start with # or ;. Each section holds key/value pairs for configuring the SecurityManager, users, roles, and URL-based security.

```ini
# =======================
# Shiro INI configuration
# =======================

[main]
# Objects and their properties are defined here,
# Such as the securityManager, Realms and anything
# else needed to build the SecurityManager

[users]
# The 'users' section is for simple deployments
# when you only need a small number of statically-defined
# set of User accounts.

[roles]
# The 'roles' section is for simple deployments
# when you only need a small number of statically-defined
# roles.

[urls]
# The 'urls' section is used for url-based security
# in web applications.  We'll discuss this section in the
# Web documentation
```

--------------------------------

### Create SecurityManager with Guice injector

Source: https://shiro.apache.org/guice.html

Creates a Guice injector with MyShiroModule, obtains a SecurityManager, and sets it via SecurityUtils. Equivalent to the first three lines of the Quickstart example.

```java
Injector injector = Guice.createInjector(new MyShiroModule());
SecurityManager securityManager = injector.getInstance(SecurityManager.class);
SecurityUtils.setSecurityManager(securityManager);
```

--------------------------------

### Example Shiro URL filter chain patterns

Source: https://shiro.apache.org/troubleshooting.html

Example [urls] section from shiro.ini showing Ant-style path patterns. More specific patterns must be placed before general ones; the /** catch-all should always be last.

```ini
[urls]
/login = anon
/logout = logout
/admin/** = authc, roles[admin]
/api/** = authc, rest
/** = authc
```

--------------------------------

### Shiro initialization log output

Source: https://shiro.apache.org/webapp-tutorial.html

Example log output from running the webapp, indicating Shiro and the Realm are configured properly.

```log
16:08:25.466 [main] INFO  o.a.shiro.web.env.EnvironmentLoader - Starting Shiro environment initialization.
16:08:26.201 [main] INFO  o.a.s.c.IniSecurityManagerFactory - Realms have been explicitly set on the SecurityManager instance - auto-setting of realms will not occur.
16:08:26.201 [main] INFO  o.a.shiro.web.env.EnvironmentLoader - Shiro environment initialized in 731 ms.
```

--------------------------------

### Run webapp with Maven Jetty

Source: https://shiro.apache.org/webapp-tutorial.html

Command to start the web application using the Jetty Maven plugin.

```bash
$ mvn jetty:run
```

--------------------------------

### Example hashed password output

Source: https://shiro.apache.org/command-line-hasher.html

Example output of the hasher command, showing a securely hashed password in the format $shiro1$SHA-256$500000$...

```text
$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=
```

--------------------------------

### Configure PasswordMatcher and PasswordService in Shiro INI

Source: https://shiro.apache.org/static/current/apidocs/org/apache/shiro/authc/credential/PasswordService.html

Example INI configuration for setting up a PasswordMatcher and a PasswordService (DefaultPasswordService) in Shiro's INI.

```ini
[main]
...
passwordService = org.apache.shiro.authc.credential.DefaultPasswordService
```

--------------------------------

### Verify Maven Installation with mvn --version

Source: https://shiro.apache.org/tutorial.html

Run this command to check that Maven 3.6.3 or later is installed. The output shows the Maven version, Java version, and OS details.

```bash
hazlewood:~/shiro-tutorial$ mvn --version
Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
Maven home: /home/bmarwell/.sdkman/candidates/maven/current
Java version: 1.8.0_312, vendor: International Business Machines Corporation, runtime: /home/bmarwell/.sdkman/candidates/java/8.0.312-sem/jre
Default locale: de_DE, platform encoding: UTF-8
OS name: "linux", version: "5.10.89-1-manjaro", arch: "amd64", family: "unix"
```

--------------------------------

### Create and switch to a new branch

Source: https://shiro.apache.org/how-to-contribute.html

Creates a new branch named 'mybranch' and switches to it. This is the recommended way to start development.

```bash
$ git checkout -b mybranch
```

--------------------------------

### [users] section example

Source: https://shiro.apache.org/configuration.html

Defines static user accounts with passwords and roles. The presence of this section triggers automatic creation of an IniRealm.

```ini
[users]
admin = secret
lonestarr = vespa, goodguy, schwartz
darkhelmet = ludicrousspeed, badguy, schwartz
```

--------------------------------

### Shiro initialization log output

Source: https://shiro.apache.org/webapp-tutorial.html

Expected log output when Shiro starts successfully, showing the environment initialization and completion time.

```log
16:04:19.807 [main] INFO  o.a.shiro.web.env.EnvironmentLoader - Starting Shiro environment initialization.
16:04:19.904 [main] INFO  o.a.shiro.web.env.EnvironmentLoader - Shiro environment initialized in 95 ms.
```

--------------------------------

### Set a VM singleton SecurityManager with DefaultSecurityManager

Source: https://shiro.apache.org/static/current/apidocs/org/apache/shiro/SecurityUtils.html

Shows how to set a SecurityManager for standalone environments (e.g., desktop apps or Applets) so that getSubject() works. The comment 'one or more Realms' is part of the original example.

```java
DefaultSecurityManager securityManager = new DefaultSecurityManager();
securityManager.setRealms( ... ); //one or more Realms
**SecurityUtils.setSecurityManager( securityManager );**
```

--------------------------------

### Example implementation of isSessionStorageEnabled using WebUtils

Source: https://shiro.apache.org/session-management.html

Shows how to inspect the Subject to decide if session storage is enabled, using WebUtils to get the HttpServletRequest for web subjects.

```java
...
    public boolean isSessionStorageEnabled(Subject subject) {
        boolean enabled = false;
        if (WebUtils.isWeb(Subject)) {
            HttpServletRequest request = WebUtils.getHttpRequest(subject);
            //set 'enabled' based on the current request.
        } else {
            //not a web request - maybe a RMI or daemon invocation?
            //set 'enabled' another way...
        }

        return enabled;
    }
```

--------------------------------

### Create Tutorial.java with main method

Source: https://shiro.apache.org/tutorial.html

Create the Tutorial.java file in src/main/java with the provided code. It imports Apache Shiro and SLF4J classes and defines a main method that logs 'My First Apache Shiro Application' and exits.

```java
import org.apache.shiro.SecurityUtils;
import org.apache.shiro.authc.*;
import org.apache.shiro.config.IniSecurityManagerFactory;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.session.Session;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.util.Factory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Tutorial {

    private static final transient Logger log = LoggerFactory.getLogger(Tutorial.class);

    public static void main(String[] args) {
        log.info("My First Apache Shiro Application");
        System.exit(0);
    }
}
```

--------------------------------

### Example [main] section configuration

Source: https://shiro.apache.org/configuration.html

A valid [main] section that configures a credentials matcher, a custom Realm with properties, and a global session timeout. Uses the $ prefix to reference the sha256Matcher object. This demonstrates Shiro's 'poor man's' dependency injection.

```ini
[main]
sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher

myRealm = com.company.security.shiro.DatabaseRealm
myRealm.connectionTimeout = 30000
myRealm.username = jsmith
myRealm.password = secret
myRealm.credentialsMatcher = $sha256Matcher

securityManager.sessionManager.globalSessionTimeout = 1800000
```

--------------------------------

### Run the application with Maven

Source: https://shiro.apache.org/tutorial.html

Execute this Maven command in the project root directory to compile and run the Tutorial application. The expected output includes the log message 'My First Apache Shiro Application'.

```bash
mvn compile exec:java
```

--------------------------------

### Final Tutorial.java class for Apache Shiro

Source: https://shiro.apache.org/tutorial.html

Complete example of the Tutorial class. It initializes Shiro with an INI file, retrieves the current user, stores and retrieves a session attribute, logs in with a username/password token, checks roles and permissions, and logs out. Includes exception handling for authentication failures.

```java
import org.apache.shiro.SecurityUtils;
import org.apache.shiro.authc.*;
import org.apache.shiro.config.IniSecurityManagerFactory;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.session.Session;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.util.Factory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Tutorial {

    private static final transient Logger log = LoggerFactory.getLogger(Tutorial.class);

    public static void main(String[] args) {
        log.info("My First Apache Shiro Application");

        Factory<SecurityManager> factory = new IniSecurityManagerFactory("classpath:shiro.ini");
        SecurityManager securityManager = factory.getInstance();
        SecurityUtils.setSecurityManager(securityManager);

        // get the currently executing user:
        Subject currentUser = SecurityUtils.getSubject();

        // Do some stuff with a Session (no need for a web or EJB container!!!)
        Session session = currentUser.getSession();
        session.setAttribute("someKey", "aValue");
        String value = (String) session.getAttribute("someKey");
        if (value.equals("aValue")) {
            log.info("Retrieved the correct value! [" + value + "]");
        }

        // let's login the current user so we can check against roles and permissions:
        if (!currentUser.isAuthenticated()) {
            UsernamePasswordToken token = new UsernamePasswordToken("lonestarr", "vespa");
            token.setRememberMe(true);
            try {
                currentUser.login(token);
            } catch (UnknownAccountException uae) {
                log.info("There is no user with username of " + token.getPrincipal());
            } catch (IncorrectCredentialsException ice) {
                log.info("Password for account " + token.getPrincipal() + " was incorrect!");
            } catch (LockedAccountException lae) {
                log.info("The account for username " + token.getPrincipal() + " is locked.  " +
                        "Please contact your administrator to unlock it.");
            }
            // ... catch more exceptions here (maybe custom ones specific to your application?
            catch (AuthenticationException ae) {
                //unexpected condition?  error?
            }
        }

        //say who they are:
        //print their identifying principal (in this case, a username):
        log.info("User [" + currentUser.getPrincipal() + "] logged in successfully.");

        //test a role:
        if (currentUser.hasRole("schwartz")) {
            log.info("May the Schwartz be with you!");
        } else {
            log.info("Hello, mere mortal.");
        }

        //test a typed permission (not instance-level)
        if (currentUser.isPermitted("lightsaber:wield")) {
            log.info("You may use a lightsaber ring.  Use it wisely.");
        } else {
            log.info("Sorry, lightsaber rings are for schwartz masters only.");
        }

        //a (very powerful) Instance Level permission:
        if (currentUser.isPermitted("winnebago:drive:eagle5")) {
            log.info("You are permitted to 'drive' the winnebago with license plate (id) 'eagle5'.  " +
                    "Here are the keys - have fun!");
        } else {
            log.info("Sorry, you aren't allowed to drive the 'eagle5' winnebago!");
        }

        //all done - log out!
        currentUser.logout();

        System.exit(0);
    }
}
```

--------------------------------

### Clone the tutorial repository

Source: https://shiro.apache.org/webapp-tutorial.html

Clones the forked Apache Shiro tutorial webapp repository to your local machine using SSH. Replace $YOUR_GITHUB_USERNAME with your GitHub username.

```bash
$ git clone git@github.com:$YOUR_GITHUB_USERNAME/apache-shiro-tutorial-webapp.git

```

--------------------------------

### RequiresRoles annotation example

Source: https://shiro.apache.org/authorization.html

Use @RequiresRoles to require the current Subject to have all specified roles. The example requires the 'administrator' role.

```java
@RequiresRoles("administrator")
public void deleteUser(User user) {
    //this method will only be invoked by an administrator
    ...
}
```

--------------------------------

### Run the webapp with Maven Jetty

Source: https://shiro.apache.org/webapp-tutorial.html

Starts the web application using the Maven Jetty plugin. After running, open localhost:8080 to see the home page with a 'Hello, World!' greeting. Press Ctrl-C to shut down the web app.

```bash
$ mvn jetty:run

```

--------------------------------

### RequiresPermissions annotation example

Source: https://shiro.apache.org/authorization.html

Use @RequiresPermissions to require the current Subject to have one or more permissions before executing the method. The example requires the 'account:create' permission.

```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
    ...
}
```

--------------------------------

### Checkout step5 branch

Source: https://shiro.apache.org/webapp-tutorial.html

Loads the step5 branch of the tutorial repository.

```bash
$ git checkout step5
```

--------------------------------

### Install ShiroAopModule with Guice

Source: https://shiro.apache.org/guice.html

Instantiates and installs ShiroAopModule alongside the application's ShiroModule and application module to enable Shiro's AOP annotations and interceptors.

```java
Injector injector = Guice.createInjector(new MyShiroModule(), new ShiroAopModule(), new MyApplicationModule());
```

--------------------------------

### init

Source: https://shiro.apache.org/static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html

Initializes the realm and sets up authentication caching based on configuration.

```APIDOC
## init

### Description
Initializes this realm and potentially enables an authentication cache, depending on configuration. Based on the availability of an authentication cache, this class functions as follows: 1. If the `cache` property has been set, it will be used to cache the AuthenticationInfo objects returned from `getAuthenticationInfo(AuthenticationToken)` method invocations. 2. If the `cache` property has **not** been set, the `cacheManager` property will be checked. If a `cacheManager` has been set, it will be used to eagerly acquire an authentication `cache`. 3. If neither the `authenticationCache` or `cacheManager` properties are set, caching will not be utilized and authentication look-ups will be delegated to subclass implementations. This method finishes by calling `onInit()` to allow subclasses to perform any init behavior desired.

### Method
init

### Signature
public final void init()

### Since
1.2
```

--------------------------------

### Checkout the step2 branch

Source: https://shiro.apache.org/webapp-tutorial.html

Use this git command to load the step2 branch of the tutorial project, which includes Shiro integrated and running within a webapp.

```bash
$ git checkout step2
```

--------------------------------

### getSessionKey

Source: https://shiro.apache.org/static/current/apidocs/org/apache/shiro/mgt/DefaultSecurityManager.html

Gets the session key from the given subject context.

```APIDOC
## getSessionKey

### Description
Gets the session key from the given subject context.

### Method
protected SessionKey getSessionKey(SubjectContext context)

### Parameters
- `context` (SubjectContext) - The subject context data.
```

--------------------------------

### onInit

Source: https://shiro.apache.org/static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html

Template method for subclasses to implement initialization logic.

```APIDOC
## onInit

### Description
Template method for subclasses to implement any initialization logic. Called from `init()`.

### Method
onInit

### Signature
protected void onInit()

### Since
1.2
```

--------------------------------

### Example [urls] filter chain definitions

Source: https://shiro.apache.org/web.html

Shows example URL-to-filter-chain mappings in the [urls] section. The `anon` filter allows anonymous access, `authc` requires authentication, `roles[administrator]` requires the administrator role, `rest` requires REST request handling, and `perms[

```ini
...
[urls]

/index.html = anon
/user/create = anon
/user/** = authc
/admin/** = authc, roles[administrator]
/rest/** = authc, rest
/remoting/rpc/** = authc, perms["remote:invoke"]

```

--------------------------------

### Maven pom.xml for Shiro Tutorial

Source: https://shiro.apache.org/tutorial.html

This Maven project file configures the Shiro tutorial application. It includes the shiro-core dependency (version 3.0.1) and SLF4J bindings for logging. The exec-maven-plugin is configured to run the Tutorial class.

```xml
<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.shiro.tutorials</groupId>
    <artifactId>shiro-tutorial</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <name>First Apache Shiro Application</name>
    <packaging>jar</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>

        <!-- This plugin is only to test run our little application.  It is not
             needed in most Shiro-enabled applications: -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>1.1</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>java</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <classpathScope>test</classpathScope>
                    <mainClass>Tutorial</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <dependency>
            <groupId>org.apache.shiro</groupId>
            <artifactId>shiro-core</artifactId>
            <version>3.0.1</version>
        </dependency>
        <!-- Shiro uses SLF4J for logging.  We'll use the 'simple' binding
             in this example app.  See https://www.slf4j.org for more info. -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>1.7.21</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>jcl-over-slf4j</artifactId>
            <version>1.7.21</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>
```

--------------------------------

### getRememberedIdentity

Source: https://shiro.apache.org/static/current/apidocs/org/apache/shiro/mgt/DefaultSecurityManager.html

Gets the remembered identity (PrincipalCollection) from the given subject context.

```APIDOC
## getRememberedIdentity

### Description
Gets the remembered identity (PrincipalCollection) from the given subject context.

### Method
protected PrincipalCollection getRememberedIdentity(SubjectContext subjectContext)

### Parameters
- `subjectContext` (SubjectContext) - The subject context data.
```

--------------------------------

### Get current Subject

Source: https://shiro.apache.org/spring-framework.html

Retrieve the current Shiro Subject using SecurityUtils.getSubject().

```java
SecurityUtils.getSubject();
```

--------------------------------

### Provide a CacheManager bean for caching

Source: https://shiro.apache.org/spring-framework.html

Enabling caching is as simple as providing a CacheManager bean. This example uses MemoryConstrainedCacheManager.

```java
@Bean
protected CacheManager cacheManager() {
    return new MemoryConstrainedCacheManager();
}
```

--------------------------------

### RequiresGuest annotation example

Source: https://shiro.apache.org/authorization.html

Use @RequiresGuest to ensure the current Subject is a guest (not authenticated or remembered) before invoking the method.

```java
@RequiresGuest
public void signUp(User newUser) {
    //this method will only be invoked by a
    //Subject that is unknown/anonymous
    ...
}
```

--------------------------------

### shiro.ini configuration file

Source: https://shiro.apache.org/tutorial.html

Defines static user accounts and roles for the tutorial application. The [users] section maps usernames to passwords and roles, while the [roles] section maps roles to permissions. This file is placed in src/main/resources.

```ini
# =============================================================================
# Tutorial INI configuration
#
# Usernames/passwords are based on the classic Mel Brooks' film "Spaceballs" :)
# =============================================================================

# -----------------------------------------------------------------------------
# Users and their (optional) assigned roles
# username = password, role1, role2, ..., roleN
# -----------------------------------------------------------------------------
[users]
root = secret, admin
guest = guest, guest
presidentskroob = 12345, president
darkhelmet = ludicrousspeed, darklord, schwartz
lonestarr = vespa, goodguy, schwartz

# -----------------------------------------------------------------------------
# Roles with assigned permissions
# roleName = perm1, perm2, ..., permN
# -----------------------------------------------------------------------------
[roles]
admin = *
schwartz = lightsaber:*
goodguy = winnebago:drive:eagle5
```

--------------------------------

### RequiresUser annotation example

Source: https://shiro.apache.org/authorization.html

Use @RequiresUser to require the current Subject to be an application user (authenticated or remembered) before invoking the method.

```java
@RequiresUser
public void updateAccount(Account account) {
    //this method will only be invoked by a 'user'
    //i.e. a Subject with a known identity
    ...
}
```

--------------------------------

### Using objects as map keys

Source: https://shiro.apache.org/configuration.html

Shows how to use object references as keys in a map property, using $objectKey and $objectValue references.

```ini
anObject.map = $objectKey1:$objectValue1, $objectKey2:$objectValue2
...
```

--------------------------------

### Equivalent INI configuration for filter chains

Source: https://shiro.apache.org/guice.html

Shows the equivalent shiro.ini [urls] configuration for the filter chains defined in the ShiroWebModule example.

```ini
[urls]
/public/** = anon
/stuff/allowed/** = authcBasic, perms["yes"]
/stuff/forbidden/** = authcBasic, perms["no"]
/** = authcBasic
```

--------------------------------

### Checkout step4 branch

Source: https://shiro.apache.org/webapp-tutorial.html

Command to load the step4 branch of the tutorial project.

```bash
$ git checkout step4
```

--------------------------------

### Clone Apache Shiro repository

Source: https://shiro.apache.org/developer-resources.html

Clones the Apache Shiro source code from GitHub. Use this to get the latest development code.

```bash
git clone https://github.com/apache/shiro.git
```

--------------------------------

### AllSuccessfulStrategy()

Source: https://shiro.apache.org/static/current/apidocs/org/apache/shiro/authc/pam/AllSuccessfulStrategy.html

Constructor for AllSuccessfulStrategy. Creates a new instance of the strategy.

```APIDOC
## AllSuccessfulStrategy()

### Description
Constructor for AllSuccessfulStrategy. Creates a new instance of the strategy.

### Method
Constructor

### Signature
`AllSuccessfulStrategy()`

### Parameters
None

### Returns
A new AllSuccessfulStrategy instance.

```
Tokens:
Raw