Package org.apache.shiro.realm

Interface Realm

  • All Known Implementing Classes:
    AbstractLdapRealm, ActiveDirectoryRealm, AuthenticatingRealm, AuthorizingRealm, CachingRealm, DefaultLdapRealm, IniRealm, JdbcRealm, JndiLdapRealm, PropertiesRealm, SimpleAccountRealm, TextConfigurationRealm
    public interface Realm
    A Realm is a security component that can access application-specific security entities such as users, roles, and permissions to determine authentication and authorization operations.

    Realms usually have a 1-to-1 correspondence with a datasource such as a relational database, file system, or other similar resource. As such, implementations of this interface use datasource-specific APIs to determine authorization data (roles, permissions, etc), such as JDBC, File IO, Hibernate or JPA, or any other Data Access API. They are essentially security-specific DAOs.

    Because most of these datasources usually contain Subject (a.k.a. User) information such as usernames and passwords, a Realm can act as a pluggable authentication module in a PAM configuration. This allows a Realm to perform both authentication and authorization duties for a single datasource, which caters to the large majority of applications. If for some reason you don't want your Realm implementation to perform authentication duties, you should override the supports(org.apache.shiro.authc.AuthenticationToken) method to always return false.

    Because every application is different, security data such as users and roles can be represented in any number of ways. Shiro tries to maintain a non-intrusive development philosophy whenever possible - it does not require you to implement or extend any User, Group or Role interfaces or classes.

    Instead, Shiro allows applications to implement this interface to access environment-specific datasources and data model objects. The implementation can then be plugged in to the application's Shiro configuration. This modular technique abstracts away any environment/modeling details and allows Shiro to be deployed in practically any application environment.

    Most users will not implement the Realm interface directly, but will extend one of the subclasses, AuthenticatingRealm or AuthorizingRealm, greatly reducing the effort requird to implement a Realm from scratch.

    Since:
    0.1
    See Also:
    CachingRealm, AuthenticatingRealm, AuthorizingRealm, ModularRealmAuthenticator

    • Method Detail

      • getName

        String getName()
        Returns the (application-unique) name assigned to this Realm. All realms configured for a single application must have a unique name.
        Returns:
        the (application-unique) name assigned to this Realm.

      • supports

        boolean supports(AuthenticationToken token)
        Returns true if this realm wishes to authenticate the Subject represented by the given AuthenticationToken instance, false otherwise.

        If this method returns false, it will not be called to authenticate the Subject represented by the token - more specifically, a false return value means this Realm instance's getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken) method will not be invoked for that token.

        Parameters:
        token - the AuthenticationToken submitted for the authentication attempt
        Returns:
        true if this realm can/will authenticate Subjects represented by specified token, false otherwise.

      • getAuthenticationInfo

        AuthenticationInfo getAuthenticationInfo(AuthenticationToken token)
                                  throws AuthenticationException
        Returns an account's authentication-specific information for the specified token, or null if no account could be found based on the token.

        This method effectively represents a login attempt for the corresponding user with the underlying EIS datasource. Most implementations merely just need to lookup and return the account data only (as the method name implies) and let Shiro do the rest, but implementations may of course perform eis specific login operations if so desired.

        Parameters:
        token - the application-specific representation of an account principal and credentials.
        Returns:
        the authentication information for the account associated with the specified token, or null if no account could be found.
        Throws:
        AuthenticationException - if there is an error obtaining or constructing an AuthenticationInfo object based on the specified token or implementation-specific login behavior fails.