OIM 11g R2 Delegated Administration Model - Sample implementation (Part I)

Introduction

It is a very common requirement from customers to have a delegated administration model that is not tied to the organizations where the administrators are placed.

 

Historically, OIM only supports a one-to-one relationship between Users and Organizations. However, starting with OIM 11g R2 and the introduction of the Catalog, it is possible to publish resources to one or more Organizations.

 

This allows to limit the visibility of the resources to only the users who need them. However, OIM 11g R2 also provides the mechanisms to delegate the administration of Users, Organizations and Resources to specific users regardless of the Organization to which those users belong.

 

This article describes an approach that can be used to implement a Provisioning Solution powered by OIM 11g R2 that is not necessarily tied to an organization-centric model. The intent of this design is to show our readers how to leverage the advanced features of OIM 11g R2 to implement Delegated Administration Models that are resource-centric and not organization-centric.

Main Article

In order to implement a model that is not centered on the relationships between users and organizations, which is quite restrictive, we need to leverage OIM's flexibility for publishing resources to multiple organizations. By doing that, the limitation of having users constrained by the organization to which they belong is overcome. In addition, this model allows users to get access to the resources they need regardless of their placement within the Organizational Structure. The mechanism that makes this possible is called Scoped Administrative Roles (SARs).

 

Scoped Administrative Roles (SARs) are based on Policies that define the privileges of a user upon Entities associated to Organizations. For example: If a user is a member of the Scoped Administrative Role OrclOIMUserAdmin for the North America Organization, this person can View, Modify, Create, Enable and Disable users in the North America Organization regardless of whether the administrative user belongs to the North America Organization or not.

 

The functionality provided by the SARs is the foundation of this implementation. For more details about SARs and OIM's Security Model please refer to the documentation for Oracle Security Architecture for 11.1.2 platform which is accessible here.

 

Delegated Administration Access Requests

By default, the only users authorized to place people in SARs are the members of the SYSTEM ADMINISTRATORS role in OIM, which is an administrative role that applies to all organizations defined in OIM.

 

If the number of Organizations in the company is considerably large, it may become impractical to manually assign users to Administrative Roles within each Organization. In addition, the assignment can not be subjected to an approval workflow.

 

A solution to this problem could be to somehow associate the assignment into SARs to an entity that can be requested in OIM via the Catalog. A good candidate would be a Role. Roles can definitely be requested through the Catalog and their visibility can also be controlled by publishing them to certain Organizations. Requests for Roles can also be subjected to an approval workflow.

 

In order to request inclusion in a SAR, users may submit petitions for one or more OIM Roles. These Roles are associated with one or more Access Policies that will assign Users to one or more SARs. In order to do this, the design includes the definition of a Disconnected Application Instance that represents a list of Delegated Administration Permissions granted to a User. The list of permissions is stored in a child form attached to the main process form for the Application Instance. For more information about Developing Application Instances refer to the Developers Guide for Oracle Identity Manager which can be found here.

 

The list of permissions is published as Entitlements. Each Entitlement represents the membership of the Entitlement Holder in a SAR. This allows Users to request the permissions through the Catalog or select them as entries in the child form of the Application Instance containing the list of Delegated Administration Permissions. So when the Application Instance is provisioned to the User, either via request or via Access Policies, the list of permissions will be added to the User's provisioned Entitlements. For an explanation of the Architecture and the Concepts involving Application Instances refer to Section 8 of the Administrators Guide for Oracle Identity Manager which can be found here.

 

Following this approach simplifies the management of Delegated Administration Permissions by defining meaningful sets of permissions and associating them to a single Role.

 

As previously mentioned, requests for a Role can be subject of Approval in OIM, so one or more Approval Policies can be created to control the granting of roles that will ultimately result in the assignment of administrative users into SARs.

 

The enforcement of the Delegated Administration Model can be automated by associating multiple Entitlements to an Access Policy tied to a Role. Some Customers may define one-to-one relationships between Roles and Entitlements by having the Access Policy provisioning only that one Entitlement when the associated Role is granted to an administrative User. Others may choose to associate a list of Entitlements to a single Role, so the Access Policy will provision a list of Entitlements in this case. Regardless of the approach, this implementation supports any granularity of associations between Entitlements and Roles.

 

Entitlement Definitions

In OIM 11g R2, Entitlements are created by linking a Lookup Type (which is a list of values) to a Form Field in the Child Form added to an Application Instance's Process Form. The Form Field has a property that flags it as an Entitlement field. OIM provides a Scheduled Task called List Entitlements. This task collects the data currently present in the Lookup Types associated to Child Form Fields marked as Entitlements and creates entries in a table containing the Entitlements grouped by Application Instance. Each Application Instance has it's own set of Entitlements.

 

For the purposes of representing SAR assignments as Entitlements, a Lookup Type was created using the following notation:

 

ScopedAdminRole:::

 

An example of an Entitlement definition using this convention would be: ScopedAdminRole:OrclEntitlementViewer:EMEA:true - this means that users having this Entitlement will be assigned the OrclEntitlementViewer administrative role within the scope of EMEA organization and its sub-organizations.

 

Entitlement Provisioning

Once the Entitlements are defined, OIM can provision them along with the Application Instance representing the list of permissions.

 

This article illustrates the approach of using an Access Policy to provision a set of Permissions when a particular Role is granted to Users.

 

Since the Application Instance for the Permissions List is a Disconnected Application Instance, an invocation of a predefined SOA Composite provided by OIM out of the box will occur when an Access Policy executes the provisioning process of the Disconnected Application Instance. The out-of-the-box SOA Composite application is customized to process the Entitlements as they come in. The SOA Composite is invoked for each Entitlement to be provisioned or revoked. For more details on SOA Composites used in OIM refer to the Developers Guide for Oracle Identity Manager Section 21 which can be found here.

 

A Web Service, created for this implementation, invokes the OIM APIs used to assign/remove Users to/from Scoped Administrative Roles. This Web Service parses the incoming Entitlement according to the format described previously, and executes the proper operation on the Entitlement (Provision or Revoke).

 

The Web Service has two main methods, which are invoked when appropriate within the customized SOA Composite for Disconnected Provisioning. The listings below show the code for those two methods and some other routines:

 

    public AdminRoleMembership addAdminRoleMembershipFor(String userId, String roleName, String scopeId, boolean hierarchy) {
        AdminRole role = this.getAdminRoleByName(roleName);
        String orgKey = this.getOrganizationID(scopeId);
        String usrKey = this.getUserKeyFor(userId);
        AdminRoleMembership membership = new AdminRoleMembership();
        membership.setAdminRole(role);
        membership.setUserId(usrKey);
        membership.setScopeId(orgKey);
        membership.setHierarchicalScope(hierarchy);
        AdminRoleService adminRoleSvc = oimClient.getService(AdminRoleService.class);
        AdminRoleMembership foundMembership = isRoleProvisioned(usrKey, orgKey, roleName); 
        if (foundMembership == null) {
            return adminRoleSvc.addAdminRoleMembership(membership);    
        }
        else {
            return foundMembership;
        }
    }

    public boolean removeAdminRoleMembershipFor(String userId, String roleName, String scopeId, boolean hierarchy) {
        AdminRole role = this.getAdminRoleByName(roleName);
        String orgKey = this.getOrganizationID(scopeId);
        String usrKey = this.getUserKeyFor(userId);
        AdminRoleMembership membership = new AdminRoleMembership();
        membership.setAdminRole(role);
        membership.setUserId(usrKey);
        membership.setScopeId(orgKey);
        membership.setHierarchicalScope(hierarchy);
        AdminRoleService adminRoleSvc = oimClient.getService(AdminRoleService.class);
        AdminRoleMembership foundMembership = isRoleProvisioned(usrKey, orgKey, roleName); 
        if (foundMembership != null) {
            System.out.println("Role Membership " + roleName + " in Organization Key " + orgKey + " for Organization " + scopeId + " will be removed.");
            return adminRoleSvc.removeAdminRoleMembership(foundMembership);
        }
        else {
            return false;
        } 
    }

    private List getScopedAdminRoleMemberships() {
        AdminRoleService adminRoleSvc = this.oimClient.getService(AdminRoleService.class);
        return adminRoleSvc.getScopedAdminRoles();
    }

    private AdminRole getAdminRoleByName(String adminRoleName) {
        List adminRoles = this.getScopedAdminRoleMemberships();
        Iterator adminRolesIter = adminRoles.iterator();
        while (adminRolesIter.hasNext()) {
            AdminRole adminRole = (AdminRole)adminRolesIter.next();
          if (adminRole.getRoleName().equals(adminRoleName)) {
              return adminRole;
          }
        }
        return null;
    }

    private String getOrganizationID(String orgName) {
        OrganizationManager orgManager = this.oimClient.getService(OrganizationManager.class);
        Organization org;
        try {
          org = orgManager.getDetails(orgName, null, true);
          return org.getEntityId();
        } catch (OrganizationManagerException e) {
            e.printStackTrace();
            return null;
        }
    }

    private AdminRoleMembership isRoleProvisioned(String usrKey, String orgKey, String roleName) {
        AdminRoleService adminRoleSvc = oimClient.getService(AdminRoleService.class);
        System.out.println("Organization key for scoping is " + orgKey);
        List memberships = adminRoleSvc.listUsersMembership(usrKey, null, orgKey, true, null);
        System.out.println("Memberships are " + memberships);
        Iterator iter = memberships.iterator();
        while (iter.hasNext()) {
            AdminRoleMembership membership = iter.next();
            System.out.println("AdminRoleName in Membership is " + membership.getAdminRoleName() + " will be compared to " + roleName);
            if (membership.getAdminRoleName().equals(roleName)) {
                System.out.println("Found the membership!!!");
                return membership;
            }        
        }
        System.out.println("The membership in role " + roleName + " for user with key " + usrKey + " was not found");
        return null;
    }

 

The APIs work with keys, meaning that the login id of a user nor the name of the organization can be used directly in the API calls. Developers need to obtain the user key (usr_key) and the organization key (act_key) to be able to successfully call the APIs to manage AdminRoleMemberships. The documentation for the APIs used in this implementation can be found here.

 

Part II of this article will describe how this approach is applied to a theoretical use-case for a Delegated Administration Model.

This article is part of the Oracle Identity Manager Academy which can be accessed here.