/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.shiro.realm;
import org.apache.shiro.authc.credential.CredentialsMatcher;
import org.apache.shiro.authz.AuthorizationException;
import org.apache.shiro.authz.AuthorizationInfo;
import org.apache.shiro.authz.Permission;
import org.apache.shiro.authz.UnauthorizedException;
import org.apache.shiro.authz.permission.*;
import org.apache.shiro.cache.Cache;
import org.apache.shiro.cache.CacheManager;
import org.apache.shiro.subject.PrincipalCollection;
import org.apache.shiro.util.CollectionUtils;
import org.apache.shiro.util.Initializable;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.*;
import java.util.concurrent.atomic.AtomicInteger;
/**
* An {@code AuthorizingRealm} extends the {@code AuthenticatingRealm}'s capabilities by adding Authorization
* (access control) support.
* <p/>
* This implementation will perform all role and permission checks automatically (and subclasses do not have to
* write this logic) as long as the
* {@link #getAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)} method returns an
* {@link AuthorizationInfo}. Please see that method's JavaDoc for an in-depth explanation.
* <p/>
* If you find that you do not want to utilize the {@link AuthorizationInfo AuthorizationInfo} construct,
* you are of course free to subclass the {@link AuthenticatingRealm AuthenticatingRealm} directly instead and
* implement the remaining Realm interface methods directly. You might do this if you want have better control
* over how the Role and Permission checks occur for your specific data source. However, using AuthorizationInfo
* (and its default implementation {@link org.apache.shiro.authz.SimpleAuthorizationInfo SimpleAuthorizationInfo}) is sufficient in the large
* majority of Realm cases.
*
* @author Les Hazlewood
* @author Jeremy Haile
* @see org.apache.shiro.authz.SimpleAuthorizationInfo
* @since 0.2
*/
public abstract class AuthorizingRealm extends AuthenticatingRealm
implements Initializable, PermissionResolverAware, RolePermissionResolverAware {
//TODO - complete JavaDoc
/*--------------------------------------------
| C O N S T A N T S |
============================================*/
private static final Logger log = LoggerFactory.getLogger(AuthorizingRealm.class);
/**
* The default suffix appended to the realm name for caching AuthorizationInfo instances.
*/
private static final String DEFAULT_AUTHORIZATION_CACHE_SUFFIX = ".authorizationCache";
private static final AtomicInteger INSTANCE_COUNT = new AtomicInteger();
/*--------------------------------------------
| I N S T A N C E V A R I A B L E S |
============================================*/
/**
* The cache used by this realm to store AuthorizationInfo instances associated with individual Subject principals.
*/
private boolean authorizationCachingEnabled;
private Cache<Object, AuthorizationInfo> authorizationCache;
private String authorizationCacheName;
private PermissionResolver permissionResolver;
private RolePermissionResolver permissionRoleResolver;
/*--------------------------------------------
| C O N S T R U C T O R S |
============================================*/
public AuthorizingRealm() {
this.authorizationCachingEnabled = true;
this.permissionResolver = new WildcardPermissionResolver();
int instanceNumber = INSTANCE_COUNT.getAndIncrement();
this.authorizationCacheName = getClass().getName() + DEFAULT_AUTHORIZATION_CACHE_SUFFIX;
if (instanceNumber > 0) {
this.authorizationCacheName = this.authorizationCacheName + "." + instanceNumber;
}
}
public AuthorizingRealm(CacheManager cacheManager) {
super(cacheManager);
}
public AuthorizingRealm(CredentialsMatcher matcher) {
super(matcher);
}
public AuthorizingRealm(CacheManager cacheManager, CredentialsMatcher matcher) {
super(cacheManager, matcher);
}
/*--------------------------------------------
| A C C E S S O R S / M O D I F I E R S |
============================================*/
public void setName(String name) {
super.setName(name);
String authzCacheName = this.authorizationCacheName;
if (authzCacheName != null && authzCacheName.startsWith(getClass().getName())) {
//get rid of the default class-name based cache name. Create a more meaningful one
//based on the application-unique Realm name:
this.authorizationCacheName = name + DEFAULT_AUTHORIZATION_CACHE_SUFFIX;
}
}
public void setAuthorizationCache(Cache<Object, AuthorizationInfo> authorizationCache) {
this.authorizationCache = authorizationCache;
}
public Cache<Object, AuthorizationInfo> getAuthorizationCache() {
return this.authorizationCache;
}
public String getAuthorizationCacheName() {
return authorizationCacheName;
}
@SuppressWarnings({"UnusedDeclaration"})
public void setAuthorizationCacheName(String authorizationCacheName) {
this.authorizationCacheName = authorizationCacheName;
}
/**
* Returns {@code true} if authorization caching should be utilized if a {@link CacheManager} has been
* {@link #setCacheManager(org.apache.shiro.cache.CacheManager) configured}, {@code false} otherwise.
* <p/>
* The default value is {@code true}.
*
* @return {@code true} if authorization caching should be utilized, {@code false} otherwise.
*/
public boolean isAuthorizationCachingEnabled() {
return isCachingEnabled() && authorizationCachingEnabled;
}
/**
* Sets whether or not authorization caching should be utilized if a {@link CacheManager} has been
* {@link #setCacheManager(org.apache.shiro.cache.CacheManager) configured}, {@code false} otherwise.
* <p/>
* The default value is {@code true}.
*
* @param authorizationCachingEnabled the value to set
*/
@SuppressWarnings({"UnusedDeclaration"})
public void setAuthorizationCachingEnabled(boolean authorizationCachingEnabled) {
this.authorizationCachingEnabled = authorizationCachingEnabled;
if (authorizationCachingEnabled) {
setCachingEnabled(true);
}
}
public PermissionResolver getPermissionResolver() {
return permissionResolver;
}
public void setPermissionResolver(PermissionResolver permissionResolver) {
this.permissionResolver = permissionResolver;
}
public RolePermissionResolver getRolePermissionResolver() {
return permissionRoleResolver;
}
public void setRolePermissionResolver(RolePermissionResolver permissionRoleResolver) {
this.permissionRoleResolver = permissionRoleResolver;
}
/*--------------------------------------------
| M E T H O D S |
============================================*/
/**
* Initializes this realm and potentially enables a cache, depending on configuration.
* <p/>
* When this method is called, the following logic is executed:
* <ol>
* <li>If the {@link #setAuthorizationCache cache} property has been set, it will be
* used to cache the AuthorizationInfo objects returned from {@link #getAuthorizationInfo}
* method invocations.
* All future calls to {@code getAuthorizationInfo} will attempt to use this cache first
* to alleviate any potentially unnecessary calls to an underlying data store.</li>
* <li>If the {@link #setAuthorizationCache cache} property has <b>not</b> been set,
* the {@link #setCacheManager cacheManager} property will be checked.
* If a {@code cacheManager} has been set, it will be used to create an authorization
* {@code cache}, and this newly created cache which will be used as specified in #1.</li>
* <li>If neither the {@link #setAuthorizationCache (org.apache.shiro.cache.Cache) cache}
* or {@link #setCacheManager(org.apache.shiro.cache.CacheManager) cacheManager}
* properties are set, caching will be disabled and authorization look-ups will be delegated to
* subclass implementations for each authorization check.</li>
* </ol>
*/
public final void init() {
//trigger obtaining the authorization cache if possible
getAvailableAuthorizationCache();
onInit();
}
protected void onInit() {
}
protected void afterCacheManagerSet() {
//trigger obtaining the authorization cache if possible
getAvailableAuthorizationCache();
}
private Cache<Object, AuthorizationInfo> getAuthorizationCacheLazy() {
if (this.authorizationCache == null) {
if (log.isDebugEnabled()) {
log.debug("No authorizationCache instance set. Checking for a cacheManager...");
}
CacheManager cacheManager = getCacheManager();
if (cacheManager != null) {
String cacheName = getAuthorizationCacheName();
if (log.isDebugEnabled()) {
log.debug("CacheManager [" + cacheManager + "] has been configured. Building " +
"authorization cache named [" + cacheName + "]");
}
this.authorizationCache = cacheManager.getCache(cacheName);
} else {
if (log.isInfoEnabled()) {
log.info("No cache or cacheManager properties have been set. Authorization cache cannot " +
"be obtained.");
}
}
}
return this.authorizationCache;
}
private Cache<Object, AuthorizationInfo> getAvailableAuthorizationCache() {
Cache<Object, AuthorizationInfo> cache = getAuthorizationCache();
if (cache == null && isAuthorizationCachingEnabled()) {
cache = getAuthorizationCacheLazy();
}
return cache;
}
/**
* Returns an account's authorization-specific information for the specified {@code principals},
* or {@code null} if no account could be found. The resulting {@code AuthorizationInfo} object is used
* by the other method implementations in this class to automatically perform access control checks for the
* corresponding {@code Subject}.
* <p/>
* This implementation obtains the actual {@code AuthorizationInfo} object from the subclass's
* implementation of
* {@link #doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) doGetAuthorizationInfo}, and then
* caches it for efficient reuse if caching is enabled (see below).
* <p/>
* Invocations of this method should be thought of as completely orthogonal to acquiring
* {@link #getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken) authenticationInfo}, since either could
* occur in any order.
* <p/>
* For example, in "Remember Me" scenarios, the user identity is remembered (and
* assumed) for their current session and an authentication attempt during that session might never occur.
* But because their identity would be remembered, that is sufficient enough information to call this method to
* execute any necessary authorization checks. For this reason, authentication and authorization should be
* loosely coupled and not depend on each other.
* <h3>Caching</h3>
* The {@code AuthorizationInfo} values returned from this method are cached for efficient reuse
* if caching is enabled. Caching is enabled automatically when an {@link #setAuthorizationCache authorizationCache}
* instance has been explicitly configured, or if a {@link #setCacheManager cacheManager} has been configured, which
* will be used to lazily create the {@code authorizationCache} as needed.
* <p/>
* If caching is enabled, the authorization cache will be checked first and if found, will return the cached
* {@code AuthorizationInfo} immediately. If caching is disabled, or there is a cache miss, the authorization
* info will be looked up from the underlying data store via the
* {@link #doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)} method, which must be implemented
* by subclasses.
* <h4>Changed Data</h4>
* If caching is enabled and if any authorization data for an account is changed at
* runtime, such as adding or removing roles and/or permissions, the subclass implementation should clear the
* cached AuthorizationInfo for that account via the
* {@link #clearCachedAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) clearCachedAuthorizationInfo}
* method. This ensures that the next call to {@code getAuthorizationInfo(PrincipalCollection)} will
* acquire the account's fresh authorization data, where it will then be cached for efficient reuse. This
* ensures that stale authorization data will not be reused.
*
* @param principals the corresponding Subject's identifying principals with which to look up the Subject's
* {@code AuthorizationInfo}.
* @return the authorization information for the account associated with the specified {@code principals},
* or {@code null} if no account could be found.
*/
protected AuthorizationInfo getAuthorizationInfo(PrincipalCollection principals) {
if (principals == null) {
return null;
}
AuthorizationInfo info = null;
if (log.isTraceEnabled()) {
log.trace("Retrieving AuthorizationInfo for principals [" + principals + "]");
}
Cache<Object, AuthorizationInfo> cache = getAvailableAuthorizationCache();
if (cache != null) {
if (log.isTraceEnabled()) {
log.trace("Attempting to retrieve the AuthorizationInfo from cache.");
}
Object key = getAuthorizationCacheKey(principals);
info = cache.get(key);
if (log.isTraceEnabled()) {
if (info == null) {
log.trace("No AuthorizationInfo found in cache for principals [" + principals + "]");
} else {
log.trace("AuthorizationInfo found in cache for principals [" + principals + "]");
}
}
}
if (info == null) {
// Call template method if the info was not found in a cache
info = doGetAuthorizationInfo(principals);
// If the info is not null and the cache has been created, then cache the authorization info.
if (info != null && cache != null) {
if (log.isTraceEnabled()) {
log.trace("Caching authorization info for principals: [" + principals + "].");
}
Object key = getAuthorizationCacheKey(principals);
cache.put(key, info);
}
}
return info;
}
protected Object getAuthorizationCacheKey(PrincipalCollection principals) {
return principals;
}
/**
* Clears out the AuthorizationInfo cache entry for the specified account.
* <p/>
* This method is provided as a convenience to subclasses so they can invalidate a cache entry when they
* change an account's authorization data (add/remove roles or permissions) during runtime. Because an account's
* AuthorizationInfo can be cached, there needs to be a way to invalidate the cache for only that account so that
* subsequent authorization operations don't used the (old) cached value if account data changes.
* <p/>
* After this method is called, the next authorization check for that same account will result in a call to
* {@link #getAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) getAuthorizationInfo}, and the
* resulting return value will be cached before being returned so it can be reused for later authorization checks.
*
* @param principals the principals of the account for which to clear the cached AuthorizationInfo.
*/
protected void clearCachedAuthorizationInfo(PrincipalCollection principals) {
if (principals == null) {
return;
}
Cache<Object, AuthorizationInfo> cache = getAvailableAuthorizationCache();
//cache instance will be non-null if caching is enabled:
if (cache != null) {
Object key = getAuthorizationCacheKey(principals);
cache.remove(key);
}
}
/**
* Retrieves the AuthorizationInfo for the given principals from the underlying data store. When returning
* an instance from this method, you might want to consider using an instance of
* {@link org.apache.shiro.authz.SimpleAuthorizationInfo SimpleAuthorizationInfo}, as it is suitable in most cases.
*
* @param principals the primary identifying principals of the AuthorizationInfo that should be retrieved.
* @return the AuthorizationInfo associated with this principals.
* @see org.apache.shiro.authz.SimpleAuthorizationInfo
*/
protected abstract AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals);
private Collection<Permission> getPermissions(AuthorizationInfo info) {
Set<Permission> permissions = new HashSet<Permission>();
if (info != null) {
Collection<Permission> perms = info.getObjectPermissions();
if (!CollectionUtils.isEmpty(perms)) {
permissions.addAll(perms);
}
perms = resolvePermissions(info.getStringPermissions());
if (!CollectionUtils.isEmpty(perms)) {
permissions.addAll(perms);
}
perms = resolveRolePermissions(info.getRoles());
if (!CollectionUtils.isEmpty(perms)) {
permissions.addAll(perms);
}
}
if (permissions.isEmpty()) {
return Collections.emptySet();
} else {
return Collections.unmodifiableSet(permissions);
}
}
private Collection<Permission> resolvePermissions(Collection<String> stringPerms) {
Collection<Permission> perms = Collections.emptySet();
PermissionResolver resolver = getPermissionResolver();
if (resolver != null && !CollectionUtils.isEmpty(stringPerms)) {
perms = new LinkedHashSet<Permission>(stringPerms.size());
for (String strPermission : stringPerms) {
Permission permission = getPermissionResolver().resolvePermission(strPermission);
perms.add(permission);
}
}
return perms;
}
private Collection<Permission> resolveRolePermissions(Collection<String> roleNames) {
Collection<Permission> perms = Collections.emptySet();
RolePermissionResolver resolver = getRolePermissionResolver();
if (resolver != null && !CollectionUtils.isEmpty(roleNames)) {
perms = new LinkedHashSet<Permission>(roleNames.size());
for (String roleName : roleNames) {
Collection<Permission> resolved = resolver.resolvePermissionsInRole(roleName);
if (!CollectionUtils.isEmpty(resolved)) {
perms.addAll(resolved);
}
}
}
return perms;
}
public boolean isPermitted(PrincipalCollection principals, String permission) {
Permission p = getPermissionResolver().resolvePermission(permission);
return isPermitted(principals, p);
}
public boolean isPermitted(PrincipalCollection principals, Permission permission) {
AuthorizationInfo info = getAuthorizationInfo(principals);
return isPermitted(permission, info);
}
private boolean isPermitted(Permission permission, AuthorizationInfo info) {
Collection<Permission> perms = getPermissions(info);
if (perms != null && !perms.isEmpty()) {
for (Permission perm : perms) {
if (perm.implies(permission)) {
return true;
}
}
}
return false;
}
public boolean[] isPermitted(PrincipalCollection subjectIdentifier, String... permissions) {
List<Permission> perms = new ArrayList<Permission>(permissions.length);
for (String permString : permissions) {
perms.add(getPermissionResolver().resolvePermission(permString));
}
return isPermitted(subjectIdentifier, perms);
}
public boolean[] isPermitted(PrincipalCollection principals, List<Permission> permissions) {
AuthorizationInfo info = getAuthorizationInfo(principals);
return isPermitted(permissions, info);
}
protected boolean[] isPermitted(List<Permission> permissions, AuthorizationInfo info) {
boolean[] result;
if (permissions != null && !permissions.isEmpty()) {
int size = permissions.size();
result = new boolean[size];
int i = 0;
for (Permission p : permissions) {
result[i++] = isPermitted(p, info);
}
} else {
result = new boolean[0];
}
return result;
}
public boolean isPermittedAll(PrincipalCollection subjectIdentifier, String... permissions) {
if (permissions != null && permissions.length > 0) {
Collection<Permission> perms = new ArrayList<Permission>(permissions.length);
for (String permString : permissions) {
perms.add(getPermissionResolver().resolvePermission(permString));
}
return isPermittedAll(subjectIdentifier, perms);
}
return false;
}
public boolean isPermittedAll(PrincipalCollection principal, Collection<Permission> permissions) {
AuthorizationInfo info = getAuthorizationInfo(principal);
return info != null && isPermittedAll(permissions, info);
}
protected boolean isPermittedAll(Collection<Permission> permissions, AuthorizationInfo info) {
if (permissions != null && !permissions.isEmpty()) {
for (Permission p : permissions) {
if (!isPermitted(p, info)) {
return false;
}
}
}
return true;
}
public void checkPermission(PrincipalCollection subjectIdentifier, String permission) throws AuthorizationException {
Permission p = getPermissionResolver().resolvePermission(permission);
checkPermission(subjectIdentifier, p);
}
public void checkPermission(PrincipalCollection principal, Permission permission) throws AuthorizationException {
AuthorizationInfo info = getAuthorizationInfo(principal);
checkPermission(permission, info);
}
protected void checkPermission(Permission permission, AuthorizationInfo info) {
if (!isPermitted(permission, info)) {
String msg = "User is not permitted [" + permission + "]";
throw new UnauthorizedException(msg);
}
}
public void checkPermissions(PrincipalCollection subjectIdentifier, String... permissions) throws AuthorizationException {
if (permissions != null) {
for (String permString : permissions) {
checkPermission(subjectIdentifier, permString);
}
}
}
public void checkPermissions(PrincipalCollection principal, Collection<Permission> permissions) throws AuthorizationException {
AuthorizationInfo info = getAuthorizationInfo(principal);
checkPermissions(permissions, info);
}
protected void checkPermissions(Collection<Permission> permissions, AuthorizationInfo info) {
if (permissions != null && !permissions.isEmpty()) {
for (Permission p : permissions) {
checkPermission(p, info);
}
}
}
public boolean hasRole(PrincipalCollection principal, String roleIdentifier) {
AuthorizationInfo info = getAuthorizationInfo(principal);
return hasRole(roleIdentifier, info);
}
protected boolean hasRole(String roleIdentifier, AuthorizationInfo info) {
return info != null && info.getRoles() != null && info.getRoles().contains(roleIdentifier);
}
public boolean[] hasRoles(PrincipalCollection principal, List<String> roleIdentifiers) {
AuthorizationInfo info = getAuthorizationInfo(principal);
boolean[] result = new boolean[roleIdentifiers != null ? roleIdentifiers.size() : 0];
if (info != null) {
result = hasRoles(roleIdentifiers, info);
}
return result;
}
protected boolean[] hasRoles(List<String> roleIdentifiers, AuthorizationInfo info) {
boolean[] result;
if (roleIdentifiers != null && !roleIdentifiers.isEmpty()) {
int size = roleIdentifiers.size();
result = new boolean[size];
int i = 0;
for (String roleName : roleIdentifiers) {
result[i++] = hasRole(roleName, info);
}
} else {
result = new boolean[0];
}
return result;
}
public boolean hasAllRoles(PrincipalCollection principal, Collection<String> roleIdentifiers) {
AuthorizationInfo info = getAuthorizationInfo(principal);
return info != null && hasAllRoles(roleIdentifiers, info);
}
private boolean hasAllRoles(Collection<String> roleIdentifiers, AuthorizationInfo info) {
if (roleIdentifiers != null && !roleIdentifiers.isEmpty()) {
for (String roleName : roleIdentifiers) {
if (!hasRole(roleName, info)) {
return false;
}
}
}
return true;
}
public void checkRole(PrincipalCollection principal, String role) throws AuthorizationException {
AuthorizationInfo info = getAuthorizationInfo(principal);
checkRole(role, info);
}
protected void checkRole(String role, AuthorizationInfo info) {
if (!hasRole(role, info)) {
String msg = "User does not have role [" + role + "]";
throw new UnauthorizedException(msg);
}
}
public void checkRoles(PrincipalCollection principal, Collection<String> roles) throws AuthorizationException {
AuthorizationInfo info = getAuthorizationInfo(principal);
checkRoles(roles, info);
}
protected void checkRoles(Collection<String> roles, AuthorizationInfo info) {
if (roles != null && !roles.isEmpty()) {
for (String roleName : roles) {
checkRole(roleName, info);
}
}
}
/**
* If authorization caching is enabled, this will remove the AuthorizationInfo from the cache.
* Subclasses are free to override for additional behavior, but be sure to call {@code super.onLogout}
* to ensure cache cleanup.
*
* @param principals the application-specific Subject/user identifier.
*/
public void onLogout(PrincipalCollection principals) {
clearCachedAuthorizationInfo(principals);
}
/**
* A utility method for subclasses that returns the first available principal of interest to this particular realm.
* The heuristic used to acquire the principal is as follows:
* <ul>
* <li>Attempt to get <em>this particular Realm's</em> 'primary' principal in the {@code PrincipalCollection} via a
* <code>principals.{@link PrincipalCollection#fromRealm(String) fromRealm}({@link #getName() getName()})</code>
* call.</li>
* <li>If the previous call does not result in any principals, attempt to get the overall 'primary' principal
* from the PrincipalCollection via {@link org.apache.shiro.subject.PrincipalCollection#getPrimaryPrincipal()}.</li>
* <li>If there are no principals from that call (or the PrincipalCollection argument was null to begin with),
* return {@code null}</li>
* </ul>
*
* @param principals the PrincipalCollection holding all principals (from all realms) associated with a single Subject.
* @return the 'primary' principal attributed to this particular realm, or the fallback 'master' principal if it
* exists, or if not {@code null}.
* @since 1.0
*/
protected Object getAvailablePrincipal(PrincipalCollection principals) {
if (principals == null || principals.isEmpty()) {
return null;
}
Object primary;
Collection thisPrincipals = principals.fromRealm(getName());
if (thisPrincipals != null && !thisPrincipals.isEmpty()) {
primary = thisPrincipals.iterator().next();
} else {
//no principals attributed to this particular realm. Fall back to the 'master' primary:
primary = principals.getPrimaryPrincipal();
}
return primary;
}
}