9.4 Role Vault API

This section describes the Role Vault API. It includes these sections:

9.4.1 About the Role Vault API

The Role Vault API allows you to programmatically access role assignments. It includes a set of methods for reporting on role assignments by container, user, group, or role, and for determining whether a user is in a particular role. You might use this API in conjunction with the Role Request activity to write your own workflow that can:

  • Display the current role assignments for a particular user on a form.

  • Allow the user to request a new role assignment.

  • Verify whether the requested roles have any Separation of Duty (SoD) constraints then perform custom branching based on the existing SoD constraints. If the conflicts are allowed, you could invoke the Role Request activity to complete the assignment. Or, you can build in logic before allowing the user to make a role assignment request.

This section includes the following topics:

Accessing the API

The Role Vault API is available from both forms and provisioning requests. The method signatures and return values are the same regardless of where they are used.You access the API by using the Expression Builder.

  • In a workflow, you can access the Role Vault API from an activity (such as the Role Request Activity) through the Vault Expressions panel of the Expression Builder.

  • From a form, you access the Role Script API by creating an event on the form and launching the Expression Builder from the event’s action expression property. The supported script expressions are available under the Vaults Node in the ECMAScript Variables panel.

Locale Handling

Some methods take a locale as a parameter. If you do not specify a locale, the User Application uses:

  • The authenticated user’s preferred locale when run from a form.

  • The User Application’s default locale when run in a workflow.

Security Context

The Role Vault methods run in the following security context:

  • On a form, the security context is that of the currently logged in user.

  • On a workflow, the security context is the LDAP administrator’s security context. Because this might return more data than an end user typically has access to, be careful how you display it.

Working with the Role Script API

The Role Script API methods typically return one of four Role Vault Beans objects (IdentityBeans, RoleAssignmentBeans, RoleBeans, and SodBeans), or one of four Role Vault Bean objects (IdentityBean, RoleAssignmentBean, RoleBean, and SodBean). A Bean object is a specific entry in the Role Subsystem, for example, IdentityBean can represent a specific user in the Identity Vault. A Beans object is a collection or array of Bean objects, for example, IdentityBeans might contain one or more user objects represented as individual Bean objects. You would iterate through the Beans extracting each Bean and working with it as a specific object. The Beans classes implement the Java Iterable interface, so they allow you to obtain member values directly out of the list of Bean objects as arrays.

Getting the Role

This example shows how to use the Beans methods to return a list of member values for the Bean. The expression is used to address the Approval activity to all the user DNs that are assigned to the role. The components of this workflow and their responsibilities are summarized in Table 9-7, Sample Workflow for Roles.

Figure 9-3 Sample Workflow for Roles

Table 9-7 Sample Workflow for Roles

Activity

Activity Type

Description

Start

Start

Logical starting point for all workflows.

Map Role Approver DN

Mapping

The data item mapping source expression

'cn=Doctor-east,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,' + PROVISIONING_DRIVER

is mapped to the target:

flowdata.roledn

Doctor Approval

Approval

This is where the Role Script API is used to define the addressee for the approval activity. The Addressee property uses this expression:

java.util.Arrays.asList(RoleVault.getUsersToRoleAssignments(flowdata.get('roledn'), true).getTargetDns())

  • The expression 

    RoleVault.getUsersToRoleAssignments(flowdata.get(‘roledn’),true)

    returns the RoleAssignmentBeans

  • The method call

    getTargetDns()

    is the RoleAssignmentBeans method that used to return an array of user DN strings.

  • To convert the array to a list so it can be used by the workflow, use the 

    java.util.Arrays.asList(...)

Log Denial/Log Denial

Log

Used to write messages to the log to indicate the result of the request (approved or denied).

Finish

Finish

Logical end point of all workflows
Retrieving SoD Violations

This example shows the methods to use to either array-like methods or a list iterator to walk through the individual RoleAssignmentBean objects contained in the RoleAssignmentBeans object. These methods are common to all of the Beans classes.

Figure 9-4 Sample Workflow for Retrieving SoDs

Table 9-8 Sample Workflow for Retrieving SoDs

Activity Name

Activity Type

Description

Start

Start

Logical starting point for all workflows.

Map SoD Dns

Mapping

 

Log getSodViolations -

Use List

Logging

Illustrates how to use an iterator to walk thru the list of identityBean objects contained in the IdentityBeans returned by the RoleVault method getSodViolations().

The size() method is used to determine if any violations were returned. 

identitybeans.size()==0

To return an iterator to walk the list, use this method:

iterator=identityBeans.iterator()

Log getSodViolations - use index

Logging

Illustrates how to use the index to access the array IdentityBean members returned from IdentityBeans using the Role Vault method getSodViolations(). This is similar to the list processing above, except that it uses the a For loop and a reference by index.

To loop through all the members in the array: 

 for (i = 0; i < identityBeans.size(); 
i++ )

To get the bean at position i in the array:

identityBean = identityBeans.get(i);

All beans support a getBean method that takes a dn string as the input paramter and returns the bean if there is one contained in the array for that dn.

All Beans classes support a getBean() that takes a DN string as the input parameter. It returns the bean if the array contains one for that DN.

Finish

Finish

Logical end point for all workflows.

9.4.2 Role Script API Reference

The Role Script API includes the methods available in the ECMA expression builder. These are the methods available for forms and workflows. The methods are grouped for convenience as follows:

Container and Group Methods

getContainersToRoleAssignments
RoleVault.getContainersToRoleAssignments(roleDN)

Returns a RoleAssignmentBeans object that contains a list of RoleAssignmentBean objects. The RoleAssignmentBean objects include the container DN(s) assigned to the specified roleDN.

getGroupsToRoleAssignments
RoleVault.getGroupsToRoleAssignments(roleDN)

Returns a RoleAssignmentBeans object that contains a list of RoleAssignmentBean objects. The RoleAssignmentBean objects include the Group DNs assigned to the specified roleDN.

Role Methods

getRoleAssignmentCause
RoleVault.getRoleAssignmentCause(identityDn, roleDn)

Returns anIdentityBeans object that contains a list of IdentityBean objects. The IdentityBeans object shows the cause hierarchy for the role assignment for the specified identityDn and roleDn. For explicit assignments, it includes the DN of the user who made the request.

getRoleInfo
RoleVault.getRoleInfo(roleDN, locale)

A role lookup method that returns a RoleBean.

getRolesToContainerAssignments
RoleVault.getRolesToContainerAssignments(containerDN)

Returns a RoleAssignmentBeans object that contains a list RoleAssignmentBean. The RoleAssignmentBean objects contain the role DN(s) assigned to the specified containerDN.

getRolesToGroupAssignments
RoleVault.getRolesToGroupAssignments(groupDN)

Returns a RoleAssignmentBeans object that contains a list of RoleAssignmentBean objects. They include the role DNs for the specified groupDN.

getRolesToRoleAssignments
RoleVault.getRolesToRoleAssignments(roleDN)

Returns a RoleAssignmentBeans object that contains a list of RoleAssignmentBean objects. The RoleAssignmentBean objects include the child role DNs assigned to the specified roleDN.

getRolesToUserAssignments
RoleVault.getRolesToUserAssignments(userDN)

Returns a RoleAssignmentBeans object that contains a list of RoleAssignmentBean objects. These beans include the role DN(s) assigned to the specified userDN.

getRolesUserIn
RoleVault.getRolesUserIn(userDN)

Return a list of role DNs where the specified userDN is a member.

SoD Methods

getSodInfo
RoleVault.getSodInfo(sodDN, locale)

Returns a SodBean.

getSodViolations
RoleVault.getSodViolations(sodDn)

Return a IdentityBeans object that contains a list of IdentityBean objects. They represent the users, groups, containers, and roles in violation of the specified sodDN.

User Methods

getUsersInRole
RoleVault.getUsersInRole(roleDN)

Returns a list of user DNs who are members of the specified roleDn

getUsersToRoleAssignments
RoleVault.getUsersToRoleAssignments(roleDN, direct)

Returns RoleAssignmentBeans object that contains a list of RoleAssignmentBean objects. The beans include the user DNs assigned to the specified roleDN. Specifying the direct argument means that only explicitly assigned to roles should be returned.

isUserAppAdmin
RoleVault.isUserAppAdmin(userDN)

Returns true if the current user is a Global Administrator.

isUserAttestationManager
RoleVault.isUserAttestationManager(userDN)

Returns true if the current user is an Attestation Officer.

isUserComplianceAdmin
RoleVault.isUserComplianceAdmin(userDN)

Returns true if the current user a Compliance Administrator.

isUserInRole
RoleVault.isUserInRole(roleDN, userDN)

Returns true if role is currently assigned to the specified user. The role can be assigned either explicitly or implicitly.

isUserProvAdmin
RoleVault.isUserProvAdmin(userDN)

Returns true if the current user is a Provisioning Administrator.

isUserRoleAdmin
RoleVault.isUserRoleAdmin(userDN)

Returns true if the current user is a Role Administrator.

9.4.3 Role Vault Bean API Reference

There are four Bean classes that represent the data returned by the Role Vault API. They are IdentityBean, RoleAssignmentBean, RoleBean, and SodBean. In many cases multiple instances of these beans are returned. If a List is used to return multiple beans, you need to iterate through the list to retrieve the required data. To make it easier to manipulate data from a script, four other Beans classes are provided. They are IdentityBeans, RoleAssignmentBeans, RoleBeans, and RoleBeans. These classes make it easier to retrieve data from individual bean classes without iterating through a list.

IdentityBean

The IdentityBean class includes methods for retrieving a DN and an identity type. It includes these methods:

getDn
public java.lang.String getDn()

Returns the DN of the identity.

getType
public java.lang.String getType()

Returns the type of the identity. Valid types are:

  • C: Container

  • G: Group

  • R: Role

  • U: User

IdentityBeans

The IdentityBeans class includes methods for manipulating one or more IdentityBeans objects or a list of IdentityBeans objects. It includes these methods:

getDns
public String[] getDns()

Returns a String Array of DNs.

getTypes
public String[]getTypes()

Returns a String Array of identity types. Values are:

  • U: Indicates User

  • G: Indicates Group

  • C: Indicates Container

  • R: Indicates Role

getIdentityBean
public IdentityBean getIdentityBean(Stringdn);

Returns the Identity Bean with the specified DN.

size()
public int size()

Returns the number of Identity Beans.

getBean()
public IdentityBean getBean(int n)

n is the index of the required bean.

Returns the IdentityBean at the specified index.

RoleAssignmentBean

The RoleAssignmentBean class includes methods for manipulating a single RoleAssignmentBean. The methods include:

getEffectiveTime
public long getEffectiveTime()

Returns the role’s effective time. (java.util.Date.getTime()).

getExpirationTime
public long getExpirationTime()

Returns the role’s expiration time.

getTargetDn 
public java.lang.String getTargetDn()

Returns the DN. The type of DN is based on the context of the method returning the bean. It can be a DN for a user, group, container, or role.

getType
public java.lang.String getType()

Returns the role’s assignment type. Values can be:

  • G=Assignment was made through membership in a group.

  • C=The assignment was made through membership in a container.

  • E=The assignment was explicit.

  • R=The assignment was inherited through the role hierarchy.

RoleAssignmentBeans

The RoleAssignmentBeans class includes method for manipulating one or more RoleAssignmentBeans objects as well as a list of RoleAssignmentBeans.

getEffectiveTimes
public Long[] getEffectiveTimes()

Returns the role’s effective time.

getExpirationTimes
public long[] getExpirationTimes()

Returns the role’s expiration times.

getTargetDns
public String[] getTargetDns()

Returns target DNs. This could be a user, group, container, or role DNs based on the context of the method that returns the bean.

getTypes()
public String[] getTypes()

Returns the assignment types. Values are:

  • G: Assignment was derived from group membership.

  • C: Assignment was derived from Container.

  • E: Assignment was explicit.

  • R: Assignment was through role hierarchy.

getRoleAssignmentBean
public RoleAssignmentBean getRoleAssignmentBean(String targetDN)

Returns the role assignment bean with the corresponding DN.

size
public int size()

Returns the number of role assignment beans.

getBean
public RoleAssignmentBean getBean(int n)

Returns the Role assignment bean at the specified index.

RoleBean

The RoleBean class includes methods for manipulating a single RoleBean. The methods include:

getDescription 
public java.lang.String getDescription()

Returns the localized role description.

getName
public java.lang.String getName()

Returns the localized role name.

getRoleDn
public java.lang.String getRoleDn()

Returns the role’s DN.

getRoleLevel
public long getRoleLevel()

Returns the role level.

RoleBeans

The RoleBeans class includes methods for manipulating one or more RoleBeans as well as a list of RoleBeans. Methods include:

getDescription
public String[]getDescriptions()

Returns the localized role description.

getNames
public String[] getNames()

Returns the localized role names.

getRoleDns
public String[] getRoleDns()

Returns the role DNs.

getRoleLevels
public long[] getRoleLevels()

Returns the role levels

getRoleBean
public RoleBean getRoleBean(String roleDN)

Returns the RoleBean with the specified role DN.

size
public int size()

Returns the number of RoleBeans in the list.

getBean
public RoleBean getBean(int n)

Returns the RoleBean at the specified index (n).

SodBean

The SodBean class includes methods for manipulating a single SodBean. The methods include:

getDescription 
public java.lang.String getDescription()

Returns the SoD’s localized description.

getName
public java.lang.String getName()

Returns the SoD’s localized name.

getRole1Dn
public java.lang.String getRole1Dn()

Returns a role included in the SoD conflict. No special considerations are made between Role1Dn and Role2Dn.

getRole2Dn
public java.lang.String getRole2Dn()

Returns a role included in the SoD conflict. No special consideration is made between Role1Dn and Role2Dn.

getSodDn
public java.lang.String getSodDn()

Returns the SoD DN.

SodBeans

The SodBeans class includes methods for manipulating one or more SoDBeans objects along with a list of SodBeans. Methods include:

getDescriptions
public String [] getDescriptions()

Returns the localized description of the SoD.

getNames
public String [] getNames()

Returns the localized names of the SoD.

getRole1Dns
public String[] getRole1Dns()

Returns the first role in the SoD conflict. No special consideration is made for Role1Dn and Role2Dn.

getRole2Dns
public String[] getRole2Dns()

Returns the second role in the SoD conflict.

getSodDns
public String[] getSodDns()

Returns SoD DNs.

getSodBean
public SodBean getSodBean(String sodDn)

Returns the SoDBean with the specified SodDn

size
public int size()

Returns the number of SodBeans.

getBean
public SodBean getBean(int n)

Returns the SodBean at the specified index (n)