org.apache.shiro.realm
Interface Realm

All Known Implementing Classes:

AbstractLdapRealm, ActiveDirectoryRealm, AuthenticatingRealm, AuthorizingRealm, CachingRealm, 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 correspondance with a datasource such as a relational database, file sysetem, 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 Summary

AuthenticationInfo	getAuthenticationInfo(AuthenticationToken token) Returns an account's authentication-specific information for the specified token, or null if no account could be found based on the token.
String	getName() Returns the (application-unique) name assigned to this Realm.
boolean	supports(AuthenticationToken token) Returns true if this realm wishes to authenticate the Subject represented by the given AuthenticationToken instance, false otherwise.

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-specifc login behavior fails.