or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdauthorization.mdindex.mdrealms.mdsecurity-annotations.mdsecurity-manager.mdsession-management.mdsubject-operations.mdutilities.md
tile.json

tessl/maven-org-apache-shiro--shiro-core

A powerful and flexible open-source Java security framework providing authentication, authorization, session management, and cryptographic services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.shiro/shiro-core@2.0.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-shiro--shiro-core@2.0.0

index.mddocs/

Apache Shiro Core

Apache Shiro Core is the foundational module of the Apache Shiro security framework, providing essential security services for Java applications. It implements a comprehensive authentication and authorization system with support for multiple realms, role-based and permission-based access control, and pluggable authentication mechanisms.

Package Information

  • Package Name: org.apache.shiro:shiro-core
  • Package Type: maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>org.apache.shiro</groupId>
  <artifactId>shiro-core</artifactId>
  <version>2.0.5</version>
</dependency>

Core Imports

import org.apache.shiro.SecurityUtils;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.mgt.SecurityManager;

For authentication:

import org.apache.shiro.authc.UsernamePasswordToken;
import org.apache.shiro.authc.AuthenticationException;

For authorization:

import org.apache.shiro.authz.Permission;
import org.apache.shiro.authz.permission.WildcardPermission;

Basic Usage

import org.apache.shiro.SecurityUtils;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.authc.UsernamePasswordToken;
import org.apache.shiro.authc.AuthenticationException;

// Get the current user (Subject)
Subject currentUser = SecurityUtils.getSubject();

// Authenticate the user
if (!currentUser.isAuthenticated()) {
    UsernamePasswordToken token = new UsernamePasswordToken("username", "password");
    try {
        currentUser.login(token);
        System.out.println("User authenticated successfully");
    } catch (AuthenticationException e) {
        System.out.println("Authentication failed: " + e.getMessage());
    }
}

// Check authorization
if (currentUser.hasRole("admin")) {
    System.out.println("User has admin role");
}

if (currentUser.isPermitted("user:create")) {
    System.out.println("User can create users");
}

// Logout
currentUser.logout();

Architecture

Apache Shiro Core is built around several key components working together:

  • Subject: The current user/security context - primary interface for all security operations
  • SecurityManager: The central security coordinator managing authentication, authorization, and sessions
  • Realms: Data source abstractions that connect to your security data (databases, LDAP, files, etc.)
  • Authentication: Identity verification with support for multiple authentication mechanisms
  • Authorization: Permission and role-based access control with fine-grained permissions
  • Sessions: Security-aware session management independent of web containers
  • Cryptography: Password hashing, encryption, and secure random number generation

This design provides a clean separation of concerns while maintaining flexibility for different deployment scenarios, from standalone applications to enterprise web applications.

Capabilities

Core Subject Operations

Primary interface for interacting with the current user's security context. The Subject represents the security-specific user view and provides all essential security operations.

public interface Subject {
    // Authentication operations
    void login(AuthenticationToken token) throws AuthenticationException;
    boolean isAuthenticated();
    boolean isRemembered();
    void logout();
    
    // Principal access
    Object getPrincipal();
    PrincipalCollection getPrincipals();
    
    // Permission checking
    boolean isPermitted(String permission);
    boolean isPermitted(Permission permission);
    boolean[] isPermitted(String... permissions);
    boolean[] isPermitted(List<Permission> permissions);
    boolean isPermittedAll(String... permissions);
    boolean isPermittedAll(Collection<Permission> permissions);
    void checkPermission(String permission) throws AuthorizationException;
    void checkPermission(Permission permission) throws AuthorizationException;
    void checkPermissions(String... permissions) throws AuthorizationException;
    void checkPermissions(Collection<Permission> permissions) throws AuthorizationException;
    
    // Role checking
    boolean hasRole(String roleIdentifier);
    boolean[] hasRoles(List<String> roleIdentifiers);
    boolean hasAllRoles(Collection<String> roleIdentifiers);
    void checkRole(String roleIdentifier) throws AuthorizationException;
    void checkRoles(Collection<String> roleIdentifiers) throws AuthorizationException;
    void checkRoles(String... roleIdentifiers) throws AuthorizationException;
    
    // Session operations
    Session getSession();
    Session getSession(boolean create);
    
    // Execution context operations
    <V> V execute(Callable<V> callable) throws ExecutionException;
    void execute(Runnable runnable);
    <V> Callable<V> associateWith(Callable<V> callable);
    Runnable associateWith(Runnable runnable);
    
    // RunAs operations
    boolean isRunAs();
    PrincipalCollection getPreviousPrincipals();
    PrincipalCollection releaseRunAs();
}

Subject Operations

Types

public interface PrincipalCollection extends Iterable, Serializable {
    Object getPrimaryPrincipal();
    List asList();
    Set asSet();
    Collection fromRealm(String realmName);
    Set<String> getRealmNames();
    boolean isEmpty();
}

Security Manager

Central coordinator for all security operations, managing the interaction between subjects, realms, sessions, and caches. The SecurityManager is the heart of Shiro's architecture.

public interface SecurityManager extends Authenticator, Authorizer, SessionManager {
    Subject createSubject(SubjectContext context);
    Subject login(Subject subject, AuthenticationToken authenticationToken) throws AuthenticationException;
    void logout(Subject subject);
}

public class DefaultSecurityManager implements SecurityManager {
    public DefaultSecurityManager();
    public DefaultSecurityManager(Realm singleRealm);
    public DefaultSecurityManager(Collection<Realm> realms);
    public void setRealms(Collection<Realm> realms);
    public void setAuthenticator(Authenticator authenticator);
    public void setAuthorizer(Authorizer authorizer);
}

Security Manager

Authentication Framework

Comprehensive authentication system supporting multiple authentication mechanisms, credential matching, and multi-realm authentication strategies.

public interface AuthenticationToken {
    Object getPrincipal();
    Object getCredentials();
}

public interface RememberMeAuthenticationToken extends AuthenticationToken {
    boolean isRememberMe();
}

public interface HostAuthenticationToken extends AuthenticationToken {
    String getHost();
}

public class UsernamePasswordToken implements AuthenticationToken, 
        RememberMeAuthenticationToken, HostAuthenticationToken {
    public UsernamePasswordToken();
    public UsernamePasswordToken(String username, char[] password);
    public UsernamePasswordToken(String username, String password);
    public UsernamePasswordToken(String username, char[] password, String host);
    public UsernamePasswordToken(String username, String password, String host);
    public UsernamePasswordToken(String username, char[] password, boolean rememberMe);
    public UsernamePasswordToken(String username, String password, boolean rememberMe);
    public UsernamePasswordToken(String username, char[] password, boolean rememberMe, String host);
    public UsernamePasswordToken(String username, String password, boolean rememberMe, String host);
    
    public String getUsername();
    public char[] getPassword();
    public String getHost();
    public boolean isRememberMe();
    public void setRememberMe(boolean rememberMe);
    public void clear();
}

public interface Authenticator {
    AuthenticationInfo authenticate(AuthenticationToken authenticationToken) 
        throws AuthenticationException;
}

Authentication

Authorization Framework

Role-based and permission-based access control with support for wildcard permissions, annotation-driven security, and flexible authorization policies.

public interface Authorizer {
    boolean isPermitted(PrincipalCollection principals, String permission);
    boolean hasRole(PrincipalCollection principals, String roleIdentifier);
    void checkPermission(PrincipalCollection principals, String permission) 
        throws AuthorizationException;
}

public class WildcardPermission implements Permission, Serializable {
    public WildcardPermission(String wildcardString);
    public WildcardPermission(String wildcardString, boolean caseSensitive);
    public boolean implies(Permission p);
    public String toString();
    public boolean equals(Object o);
    public int hashCode();
}

Authorization

Realm Framework

Data source abstractions that connect Shiro to your security data sources like databases, LDAP directories, or configuration files. Realms handle both authentication and authorization data retrieval.

public interface Realm {
    boolean supports(AuthenticationToken token);
    AuthenticationInfo getAuthenticationInfo(AuthenticationToken token) 
        throws AuthenticationException;
}

public abstract class AuthorizingRealm extends AuthenticatingRealm {
    protected abstract AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals);
    protected abstract AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) 
        throws AuthenticationException;
}

Realms

Session Management

Security-aware session management that works independently of web containers, providing consistent session handling across different deployment environments.

public interface Session {
    Serializable getId();
    Date getStartTimestamp();
    Date getLastAccessTime();
    long getTimeout() throws InvalidSessionException;
    void setTimeout(long maxIdleTimeInMillis) throws InvalidSessionException;
    String getHost();
    void touch() throws InvalidSessionException;
    void stop() throws InvalidSessionException;
    Collection<Object> getAttributeKeys() throws InvalidSessionException;
    Object getAttribute(Object key) throws InvalidSessionException;
    void setAttribute(Object key, Object value) throws InvalidSessionException;
    Object removeAttribute(Object key) throws InvalidSessionException;
}

public interface SessionManager {
    Session start(SessionContext context);
    Session getSession(SessionKey key);
}

Session Management

Security Annotations

Method-level security annotations for declarative authorization and authentication requirements, enabling aspect-oriented security.

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiresAuthentication {
}

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiresRoles {
    String[] value();
    Logical logical() default Logical.AND;
}

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiresPermissions {
    String[] value();
    Logical logical() default Logical.AND;
}

Security Annotations

Utilities and Configuration

Essential utilities for initialization, configuration, thread context management, and integration with various environments and frameworks.

public abstract class SecurityUtils {
    public static Subject getSubject();
    public static SecurityManager getSecurityManager();
    public static void setSecurityManager(SecurityManager securityManager);
}

public abstract class ThreadContext {
    public static SecurityManager getSecurityManager();
    public static void bind(SecurityManager securityManager);
    public static SecurityManager unbindSecurityManager();
    public static Subject getSubject();
    public static void bind(Subject subject);
    public static Subject unbindSubject();
    public static void remove();
}

Utilities

Exception Hierarchy

public class ShiroException extends RuntimeException {
    public ShiroException(String message);
    public ShiroException(Throwable cause);
}

public class AuthenticationException extends ShiroException {
    public AuthenticationException(String message);
}

public class AuthorizationException extends ShiroException {
    public AuthorizationException(String message);
}

public class SessionException extends ShiroException {
    public SessionException(String message);
}