9.4 Role Vault API

This section describes the Role Vault API.

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.

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 Objects pane.

Locale Handling

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.

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 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-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())
  • 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-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.

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.

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 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.

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 DNs 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.

getRoleOwners

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.

getRoleApprovers

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.

SoD Methods

getSodInfo

RoleVault.getSodInfo(sodDN, locale)

Returns a SodBean.

getSodViolations

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.

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.

Hidden Methods

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:

findRoles

RoleVault.findRoles(String attributeKey, String relationalOp, String filterValue, int roleLevel, String locale)

Parameter

Description

attributeKey

 

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 STARTWITH or CONTAINS. When roleLevel is specified, additional scoping is performed based on the roleLevel.

findSods

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

  • less
  • not-less
  • less-or-equal
  • greater
  • not-greater
  • greater-or-equal
  • not-equals
  • equals
  • contains
  • not-contains
  • ends-with
  • not-ends-with
  • starts-with
  • not-starts-with

filterValue

 

locale

Optional.

findSodsByRoles

findSodsByRoles(String roleDNs, String locale)

Returns a SodBeans object containing SodBean objects for the specified role DNs. Locale is an optional parameter.

findSodsByRoles

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

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

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

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

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:

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. 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.

IdentityBean

The IdentityBean class includes methods for retrieving a DN and an identity type. It includes the following 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.

getDns

public String[] getDns()

Returns a String Array of DNs.

getType

public String[]getType()

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 methods 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.

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(String roleDN)

Returns the role’s DN.

getRoleLevel

public long getRoleLevel()

Returns the role level.

getRoleOwner

public java.lang.String getRoleOwner(String roleDN)

Returns the role’s owner.

getRoleApprover

public java.lang.String getRoleApprover(String roleDN)

Returns the role’s approver.

RoleBeans

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

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).

findRoles

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.

SodBean

The SodBean class includes methods for manipulating a single SodBean.

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.

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)

findSodsByRoles

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

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.

getGroupSodViolations

SodBeans getGroupSodViolations(String groupDn)

Returns the SoD violations for a specified group.

getRoleSodViolations

SodBeans getRoleSodViolations(String roleDn) 

Returns the SoD violations for a specified role.

getContainerSodViolations

SodBeans getContainerSodViolations(String containerDn

Returns the SoD violations for a specified container.