Chapter 3. Authorization Manager

package org.jboss.security; 

import java.security.Principal;
import java.security.acl.Group;
import java.util.Map;
import java.util.Set;

import org.jboss.security.authorization.AuthorizationException;
import org.jboss.security.authorization.Resource; 
/**
 *  Generalized Authorization Manager Interface. 
 */
public interface AuthorizationManager 
{  
   /**
    * Authorize a resource
    * @param resource
    * @return
    * @throws AuthorizationException
    */
   public int authorize(Resource resource) throws AuthorizationException; 
  
   
   /** Validates the application domain roles to which the operational
   environment Principal belongs.
   @param principal - the caller principal as known in the operation environment.
   @param roles - the Set<Principal> for the application domain roles that the
    principal will be validated against.
   @return true if the principal has at least one of the roles in the roles set,
       otherwise false.
    */
   public boolean doesUserHaveRole(Principal principal, Set roles); 
   
   
   /** Returns the set of domain roles assigned to the principal.
   @return The Set<Principal> for the application domain roles that the
    principal has been assigned.
    */
   public Set getUserRoles(Principal principal); 
   
   /**
    * Trust-based use-cases may need to determine the roles of the target
    * principal, which are derived by the Authentication Manager via a principal
    * from another domain. 
    * An implementation of this interface may need to contact a trust provider
    * for additional information about the principal
    * @param targetPrincipal - the principal applicable in current domain
    * @param contextMap - read-only contextual information that can assist the
    *                                     implementation when determining roles
    * @return roles from the target domain
    */
   public Group getTargetRoles(Principal targetPrincipal, Map contextMap);
 }

package org.jboss.security.authorization;

import java.util.Map; 

/**
 *  Resource that is subject to Authorization Decisions 
 */
public interface Resource
{ 
   //Get the Layer (Web/EJB etc)
   public ResourceType getLayer();
   
   //Return the contextual map
   public Map getMap(); 
}

package org.jboss.security.authorization;

import java.util.Map;

import javax.security.auth.Subject;
import javax.security.auth.callback.CallbackHandler; 

/**
 *  Represents a Policy Decision Module that is used by the
 *  Authorization Context 
 */
public interface AuthorizationModule
{
   /**
    * Abort the Authorization Process
    * @return true - abort passed, false-otherwise
    */
   boolean abort() throws AuthorizationException;
   
   /**
    * Overall authorization process has succeeded.
    * The module can commit any decisions it has made, with
    * third party systems like a database.
    * @return 
    */
   boolean commit() throws AuthorizationException;
   
   /**
    * Initialize the module
    * 
    * @param subject the authenticated subject
    * @param handler CallbackHandler
    * @param sharedState state shared with other configured modules 
    * @param options options specified in the Configuration 
    *                for this particular module
    */
   void initialize(Subject subject, CallbackHandler handler,
         Map sharedState, Map options);
   
   /**
    * Authorize the resource
    * @param resource
    * @return AuthorizationContext.PERMIT or AuthorizationContext.DENY
    */
   int authorize(Resource resource);
   
   /**
    * A final cleanup opportunity offered
    * @return cleanup by the module passed or not
    */
   boolean destroy();
}

package org.jboss.security.authorization; 

/**
 *  Interface to register policies 
 */
public interface PolicyRegistration
{
   /**
    * Registers a policy given the location and a context ID
    * @param contextID
    * @param location - location of the Policy File
    */
   void registerPolicy(String contextID, URL location);
   
   /**
    * 
    * Registers a policy given an XML-based stream and a context ID
    * 
    * @param contextID
    * @param stream - InputStream that is an XML stream
    */
   void registerPolicy(String contextID, InputStream stream);
   
   /**
    * Unregister a policy  
    * @param contextID Context ID
    */
   void deRegisterPolicy(String contextID); 
   
   /**
    * Obtain the registered policy for the context ID
    * @param contextID - Context ID
    * @param contextMap - A map that can be used by the implementation
    *                                     to determine the policy choice (typically null)
    */
   Object getPolicy(String contextID, Map contextMap);
}

  * JBoss, Home of Professional Open Source
  * Copyright 2005, JBoss Inc., and individual contributors as indicated
  * by the @authors tag. See the copyright.txt in the distribution for a
  * full listing of individual contributors.
  *
  * This is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License as
  * published by the Free Software Foundation; either version 2.1 of
  * the License, or (at your option) any later version.
  *
  * This software is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
  * License along with this software; if not, write to the Free
  * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
  */
package org.jboss.security.authorization;

import java.util.Map;

/**
 *  Resource that is subject to Authorization Decisions
 *  @author <a href="mailto:Anil.Saldhana@jboss.org">Anil Saldhana</a>
 *  @version $Revision$
 */
public interface Resource
{ 
   //Get the Layer (Web/EJB etc)
   public ResourceType getLayer();
   
   //Return the contextual map
   public Map getMap(); 
}