Package com.ibm.portal.ac

This package and its sub packages define the portal access control (PAC) API.

See:
Description

Interface Summary

AccessControlAttributeBasedSecurity	The AccessControlAttributeBasedSecurityInterface defines a method to get called by the AccessControlAttributeBasedSecurity pattern.
ContentItem	The AccessControlAttributeBasedSecurityCallbackInterface provides methods to retrieve detailed information about the current ContentItem.

Package com.ibm.portal.ac Description

This package and its sub packages define the portal access control (PAC) API.

Overview

The PAC API offers functionality to retrieve and modify access control related information of any resources (e.g. portlets, pages) that are managed by portal access control. In particular, the following data objects and relationships can be created, retrieved, modified and deleted:

• Managed Protected Resources:
  Any Portal entity that is individually managed and thus protected by portal access control has a corresponding managed protected resource.
• Role Types
  A role type represents a named set of privileges, for example EDITOR, representing all privileges needed to view and edit a resource.
• Roles:
  A role type on a specific resource is called a role, for example Editor@page1
• Role Assignments:
  Role assignments are mappings of a single principal (user or group) to a single role, for example Bob is Editor@TestPage.
• Permissions:
  A Permission is a privilege that allows to perform a specific set of privilege on a specific resource. Although any permission is a result of some role assignment(s) there is not direct relationship between permissions and role assignments: The Permission for Bob to view a page might be caused by a direct role assignment of the action on the page to Bob, or any assignment of the action on any parent page to any group that Bob is member of.

Class Overview - Service Interfaces

The main service interfaces as listed below can be retrieved through the AccessControlHome

• com.ibm.portal.ac.AccessControlEnvironment:
  The AccessControlEnvironment provides some general information about the Access Control configuration, for example the available role types.
• com.ibm.portal.ac.AccessControlGlobalRuntimeModel:
  The AccessControlGlobalRuntimeModel provides read access to the current access control permissions on any resource that is registered at Portal Access Control.
• com.ibm.portal.ac.AccessControlRuntimeModel:
  The AccessControlRuntimeModel provides read access to the current access control permissions on one specific resource.
• com.ibm.portal.ac.ManagedProtectedResource:
  The ManagedProtectedResource provides read access to the access control configuration of any resource that is registered at PAC.
• com.ibm.portal.ac.ManagedProtectedResourceController:
  The ManagedProtectedResourceController provides write access to the access control configuration of any resource that is registered at PAC.
• com.ibm.portal.ac.RoleData:
  The RoleData provides read access to the role data of a single resource, such as role assignments.
• com.ibm.portal.ac.RoleDataController:
  The RoleData provides write access to the role data of a single resource, such as role assignments.
• com.ibm.portal.ac.ManagedProtectedResourceModel:
  The ManagedProtectedResource represents the hierarchical tree model of protected resources per Database Domain.

Code Samples

Retrieve ManagedProtectedResource and RoleData Instances

The following sample shows how instances of the ManagedProtectedResource and RoleData can be retrieved through a JNDI lookup and the CommunityHome class. Additionally, the owner of the resource and all principals that are directly mapped to the EDITOR role type are retrieved.

        Identifiable resource = ... ; // some resource, for example a portlet
        Context ctx = new InitialContext();
        AccessControlHome home = (AccessControlHome) ctx.lookup(AccessControlHome.JNDI_NAME);
        ManagedProtectedResource pacResource = home.getManagedProtectedResource(resource);
        RoleData resourceRoleData = home.getRoleData(resource);
        Principal owner = pacResource.getOwner();
        Set editors = resourceRoleData.getMappedPrincipals(RoleType.EDITOR);

Retrieve Role Assignments

The following sample shows how to retrieve all Role Assignments that are effective for a principal on a resource.

        Identifiable resource = ... ; // some resource, for example a portlet
        Principal bob = ... ; // some principal, for example Bob
        Context ctx = new InitialContext();
        AccessControlHome home = (AccessControlHome) ctx.lookup(AccessControlHome.JNDI_NAME);
        RoleData resourceRoleData = home.getRoleData(resource);
        Set assignments = resourceRoleData.getRoleAssignments(bob);
        for (RoleAssignment assignment: assignments) {
           // p is either bob or any group that bob belongs to
           Principal p = assignment.getPrincipal; 
           Role role = assignment.getRole();
           // resourceID is either the ID of the above resource or of any parent
           ObjectID resourceID = role.getResourceID();
           // the role type of the mapping
           RoleType roleType = role.getRoleType();
        }

Evaluate if a principal has certain permissions

The following sample shows how to evaluate if a principal has view permissions on a resource

        Identifiable resource = ... ; // some resource, for example a portlet
        Principal bob = ... ; // some principal, for example Bob
        Context ctx = new InitialContext();
        AccessControlHome home = (AccessControlHome) ctx.lookup(AccessControlHome.JNDI_NAME);
        AccessControlRuntimeModel runtimeModel = home.getAccessControlRuntimeModel(resource);
        boolean isAllowed = runtimeModel.isAllowed(bob, RoleType.USER);
        
        // the following is equivalent
        AccessControlEnvironment environment = home.getAccessControlEnvironment();
        Permission permission = environment.getPermission(resource, RoleType.USER);
        AccessControlGlobalRuntimeModel gobalModel = home.getAccessControlGlobalRuntimeModel();
        globalModel.hasPermission(bob, permission); 

Modify role blocks for a resource

The following sample shows how to add, set or remove role blocks on a resource

        Identifiable resource = ... ; // some resource, for example a portlet
        Principal bob = ... ; // some principal, for example Bob
        Context ctx = new InitialContext();
        AccessControlHome home = (AccessControlHome) ctx.lookup(AccessControlHome.JNDI_NAME);
        ManagedProtectedResource resourceController = home.getManagedProtectedResourceController(resource);
        Collection roleBlocks = Collection.singleton(RoleType.EDITOR);
        
        // the EDITOR inheritance role block is added to the existing role blocks 
        resourceController.addInheritanceBlockedRoleTypes(roleBlocks);

        // the EDITOR inheritance role block is set (so it becomes the only inheritance block) 
        resourceController.setInheritanceBlockedRoleTypes(roleBlocks);
        
        // the EDITOR inheritance role block is removed 
        resourceController.removeInheritanceBlockedRoleTypes(roleBlocks);        

Assign principals to roles

The following sample shows how to assign principals to a role

        Identifiable resource = ... ; // some resource, for example a portlet
        Principal bob = ... ; // some principal, for example Bob
        Context ctx = new InitialContext();
        AccessControlHome home = (AccessControlHome) ctx.lookup(AccessControlHome.JNDI_NAME);
        RoleDataController roleController = home.getRoleDataController(resource);
        Collection principals = Collection.singleton(bob);
        // bob is assigned the EDITOR role
        roleController.addPrincipalsToRole(RoleType.EDITOR, principals);
                
        // bob is unassigned from the MANAGER role
        roleController.removePrincipalsFromRole(RoleType.MANAGER, principals);