This section describes 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.
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 Objects pane.
Some methods take a locale as a parameter. If you do not specify a locale, the User Application uses one of the following:
The authenticated user’s preferred locale when run from a form.
The User Application’s default locale when run in a workflow.
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.
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 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.
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-2 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).getTargetDn())
|
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. |
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-3 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 through 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. |
The Role Script API includes the methods available in the ECMA Expression Builder. These are the methods available for forms and workflows.
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.
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.
RoleVault.getRoleAssignmentCause(identityDn, roleDn)
Returns an IdentityBeans 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.
RoleVault.getRolesToContainerAssignments(containerDN)
Returns a RoleAssignmentBeans object that contains a list RoleAssignmentBean. The RoleAssignmentBean objects contain the role DNs assigned to the specified containerDN.
RoleVault.getRolesToGroupAssignments(groupDN)
Returns a RoleAssignmentBeans object that contains a list of RoleAssignmentBean objects. They include the role DNs for the specified groupDN.
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.
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.
RoleVault.getRolesUserIn(userDN)
Return a list of role DNs where the specified userDN is a member.
RoleVault.getRoleOwners(roleDN)
Returns the IdentityBeans object that contains a list of IdentityBean objects. The IdentityBeans object shows the owners of the specified role DN.
RoleVault.getRoleApprovers(roleDN)
Returns the IdentityBeans object that contains a list of IdentityBean objects. The IdentityBeans object shows the approvers of the specified role DN.
RoleVault.getSodViolations(sodDn)
Returns an IdentityBeans object that contains a list of IdentityBean objects. They represent the users, groups, containers, and roles in violation of the specified sodDN.
RoleVault.getUsersInRole(roleDN)
Returns a list of user DNs who are members of the specified roleDn.
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.
RoleVault.isUserAppAdmin(userDN)
Returns True if the current user is a Global Administrator.
RoleVault.isUserAttestationManager(userDN)
Returns True if the current user is an Attestation Officer.
RoleVault.isUserComplianceAdmin(userDN)
Returns True if the current user a Compliance Administrator.
RoleVault.isUserInRole(roleDN, userDN)
Returns True if role is currently assigned to the specified user. The role can be assigned either explicitly or implicitly.
RoleVault.isUserProvAdmin(userDN)
Returns True if the current user is a Provisioning Administrator.
RoleVault.isUserRoleAdmin(userDN)
Returns True if the current user is a Role Administrator.
The following methods are part of the Role Vault API, but helper methods are not provided in the Expression Builder in Designer. You must manually type the method. The Expression Builder supports the following methods:
RoleVault.findRoles(String attributeKey, String relationalOp, String filterValue, int roleLevel, String locale)
Parameter |
Description |
---|---|
attributeKey |
Valid values are: RoleLevel, Description, Name, RoleCategoryKey, owner |
relationalOp |
Valid values are: less, not-less, less-or-equal, not-less-or-equal, greater, not-greater, greater-or-equal, not-greater-or-equal, not-equals, equals, contains, not-contains, ends-with, not-ends-with, starts-with, not-starts-with |
filterValue |
|
roleLevel |
optional. |
locale |
optional. |
Returns a RoleBeans object. You can use then access a list of roleBeans based on the attributeKey and its relation to the filterValue. Use the relationalOp such as starts-with or contains. When roleLevel is specified, additional scoping is performed based on the roleLevel.
RoleVault.findSods(String attributeKey, String relationalOp, String filterValue, String locale)
Returns a SodBeans object that contains a list of sodBeans based on the attributeKey relation to the filterValue based on the relationalOp.
Table 9-9 Enter Table Title Here
Parameter |
Description |
---|---|
attributeKey |
|
relationalOp |
Valid values are
|
filterValue |
|
locale |
Optional. |
findSodsByRoles(String roleDNs, String locale)
Returns a SodBeans object containing SodBean objects for the specified role DNs. Locale is an optional parameter.
findSodsByRoles(/*arraylist*/roledns, String locale)
Returns a SodBeans object containing a list of SodBean objects that include any of the specified roledns. Locale is optional.
findSodsByRoles(String role1, String role2, String locale)
Returns a SodBeans object containing a list of SodBean objects that have a conflict between the two roles specified. Locale is optional.
getContainerSodViolations(String containerdn)
Returns a SodBeans object containing a list of SodBean objects where the specified container has roles assigned in violation of existing SoD contraints.
getGroupSodViolations(String groupdn )
Returns a SodBeans object that contains a list of sodBeans where the specified group has roles assigned in violation of existing SoD contraints.
getRoleSodViolations(String roledn )
Returns a SodBeans object that contains a list of SodBean objects where the specified roleDN has roles assigned in violation of existing SoD contraints.
Example:
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. Methods that are invoked from the form script that return multiple beans return a list of bean objects. To make it easier to manipulate data from a script, four other Beans classes are provided. They are IdentityBeans, RoleAssignmentBeans, RoleBeans, and SodBeans. These classes make it easier to retrieve data from individual bean classes without iterating through a list.
The IdentityBean class includes methods for retrieving a DN and an identity type. It includes the following methods:
public java.lang.String getDn()
Returns the DN of the identity.
public java.lang.String getType()
Returns the type of the identity. Valid types are:
C: Container
G: Group
R: Role
U: User
The IdentityBeans class includes methods for manipulating one or more IdentityBeans objects or a list of IdentityBeans objects.
public String[] getDns()
Returns a String Array of DNs.
public String[]getType()
Returns a String Array of identity types. Values are:
U: Indicates User
G: Indicates Group
C: Indicates Container
R: Indicates Role
public IdentityBean getIdentityBean(Stringdn);
Returns the Identity Bean with the specified DN.
public int size()
Returns the number of Identity Beans.
public IdentityBean getBean(int n)
n is the index of the required bean.
Returns the IdentityBean at the specified index.
The RoleAssignmentBean class includes methods for manipulating a single RoleAssignmentBean. The methods include:
public long getEffectiveTime()
Returns the role’s effective time. (java.util.Date.getTime()).
public long getExpirationTime()
Returns the role’s expiration time.
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.
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.
The RoleAssignmentBeans class includes methods for manipulating one or more RoleAssignmentBeans objects as well as a list of RoleAssignmentBeans.
public Long[] getEffectiveTimes()
Returns the role’s effective time.
public long[] getExpirationTimes()
Returns the role’s expiration times.
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.
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.
public RoleAssignmentBean getRoleAssignmentBean(String targetDN)
Returns the role assignment bean with the corresponding DN.
public int size()
Returns the number of role assignment beans.
public RoleAssignmentBean getBean(int n)
Returns the Role assignment bean at the specified index.
The RoleBean class includes methods for manipulating a single RoleBean.
public java.lang.String getDescription()
Returns the localized role description.
public java.lang.String getName()
Returns the localized role name.
public java.lang.String getRoleDn(String roleDN)
Returns the role’s DN.
public long getRoleLevel()
Returns the role level.
public java.lang.String getRoleOwner(String roleDN)
Returns the role’s owner.
public java.lang.String getRoleApprover(String roleDN)
Returns the role’s approver.
The RoleBeans class includes methods for manipulating one or more RoleBeans as well as a list of RoleBeans.
public String[]getDescriptions()
Returns the localized role description.
public String[] getNames()
Returns the localized role names.
public String[] getRoleDns()
Returns the role DNs.
public long[] getRoleLevels()
Returns the role levels
public RoleBean getRoleBean(String roleDN)
Returns the RoleBean with the specified role DN.
public int size()
Returns the number of RoleBeans in the list.
public RoleBean getBean(int n)
Returns the RoleBean at the specified index (n).
Returns the roles based on filter values. It has four methods. These methods must be mentioned separately because different parameters are passed in each of these methods.
findRoles
public RoleBeans findRoles(String attributeKey, String relationalOp, String value, String locale, int roleLevel)
Returns the roles based on filter values.
findRoles
public RoleBeans findRoles(String attributeKey, String relationalOp, String value, int roleLevel)
Returns the roles based on filter values.
findRoles
public RoleBeans findRoles(String attributeKey, String relationalOp, String value, String locale)
Returns the roles based on filter values.
findRoles
public RoleBeans findRoles(String attributeKey, String relationalOp, String value)
Returns the roles based on filter values.
The SodBean class includes methods for manipulating a single SodBean.
public java.lang.String getDescription()
Returns the SoD’s localized description.
public java.lang.String getName()
Returns the SoD’s localized name.
public java.lang.String getRole1Dn()
Returns a role included in the SoD conflict. No special considerations are made between Role1Dn and Role2Dn.
public java.lang.String getRole2Dn()
Returns a role included in the SoD conflict. No special consideration is made between Role1Dn and Role2Dn.
public java.lang.String getSodDn()
Returns the SoD DN.
The SodBeans class includes methods for manipulating one or more SoDBeans objects along with a list of SodBeans.
public String [] getDescriptions()
Returns the localized description of the SoD.
public String [] getNames()
Returns the localized names of the SoD.
public String[] getRole1Dns()
Returns the first role in the SoD conflict. No special consideration is made for Role1Dn and Role2Dn.
public String[] getRole2Dns()
Returns the second role in the SoD conflict.
public String[] getSodDns()
Returns SoD DNs.
public SodBean getSodBean(String sodDn)
Returns the SodBean with the specified SodDn.
public int size()
Returns the number of SodBeans.
public SodBean getBean(int n)
Returns the SodBean at the specified index (n)
findSodsByRoles has six methods. These methods must be mentioned separately because different parameters are passed in each of these methods.
findSodsByRoles
public SodBeans findSodsByRoles(List<String> roleDns, String locale)
Returns the SoDs based on a list of role DNs.
findSodsByRoles
public SodBeans findSodsByRoles(List<String> roleDns)
Returns the SoDs based on a list of role DNs by using the default application locale.
findSodsByRoles
public SodBeans findSodsByRoles(String targetRoleDn, String sourceRoleDn, String locale)
Returns the SoDs based on source and target DNs.
findSodsByRoles
public SodBeans findSodsByRoles(String targetRoleDn, String sourceRoleDn)
Returns the SoDs based on source and target DNs.
findSodsByRoles
public SodBeans findSodsByRoles(String[] roleDns)
Returns the SoDs based on an array of role DNs.
findSodsByRoles
public SodBeans findSodsByRoles(String[] roleDns, String locale)
Returns the SoDs based on an array of role DNs.
findSods has two methods. These methods must be mentioned separately because different parameters are passed in each of these methods.
findSods
public SodBeans findSods(String attributeKey, String relationalOp, String value, String locale)
Returns the SoDs based on the DAL attribute filter.
findSods
public SodBeans findSods(String attributeKey, String relationalOp, String value)
Returns the SoDs based on the DAL attribute filter.
SodBeans getGroupSodViolations(String groupDn)
Returns the SoD violations for a specified group.
SodBeans getRoleSodViolations(String roleDn)
Returns the SoD violations for a specified role.
SodBeans getContainerSodViolations(String containerDn
Returns the SoD violations for a specified container.