Use assignments to provision users

Authorization roles control access to IDM itself. Provisioning roles define rules for how attribute values are updated on external systems. These rules are configured through assignments attached to a provisioning role definition. The purpose of an assignment is to provision an attribute or set of attributes based on an object’s role membership.

The synchronization mapping configuration between two resources provides the logic governing how an account is mapped from a source to a target system. Role assignments provide additional provisioning logic not covered in the basic mapping configuration. The attributes and values updated by using assignments may include group membership, access to specific external resources, and so on. A group of assignments can collectively represent a role.

Assignment objects are created, updated, and deleted like any other managed object. They are attached to a role using the relationships mechanism. Assignments are accessible at the context path /openidm/managed/assignment.

You can create, query, update, and delete assignments using the:

Platform admin UI: Available at people Identities > Manage, and click the vpn_key Assignments tab
Legacy admin UI (deprecated): Available at Manage > Assignment
REST interface: Available at /openidm/managed/assignment

This section describes how to manipulate assignments over the REST interface, the Platform admin UI, and the legacy admin UI. When you have created an assignment and attached it to a role definition, all user objects that reference that role definition will reference the corresponding assignment in their effectiveAssignments attribute.

If you have mapped roles and assignments to properties on a target system, and you are preloading the result set into memory, make sure that your targetQuery returns the mapped property. For example, if you have mapped a specific role to the ldapGroups property on the target system, the target query must include the ldapGroups property when it returns the object.

The following mapping excerpt indicates the target query must return the _id of the object and its ldapGroups property:

"targetQuery": {
    "_queryFilter": true,
    "_fields": "_id,ldapGroups"
}

For more information about preloading the result set for reconciliation operations, refer to Improve Reconciliation Query Performance.

Create an Assignment

You can create assignments over the REST interface, the Platform admin UI, or the legacy admin UI:

Using REST

To create a new assignment over REST, send a PUT or POST request to the /openidm/managed/assignment context path.

The following example creates a new managed assignment named employee. The JSON payload in this example shows the following:

The assignment is applied for the mapping managedUser_systemLdapAccounts. Attributes are updated on the external LDAP system specified in this mapping.
The name of the attribute on the external system with a value to be set is employeeType. It will be set to Employee.

When the assignment is applied during a sync operation, the attribute value Employee is added to any existing values for that attribute. When the assignment is removed (such as if the user is no longer a member of that role), the attribute value Employee is also removed.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "name": "employee",
  "description": "Assignment for employees.",
  "mapping": "managedUser_systemLdapAccounts",
  "attributes": [
    {
      "name": "employeeType",
      "value": [
        "Employee"
      ],
      "assignmentOperation": "mergeWithTarget",
      "unassignmentOperation": "removeFromTarget"
    }
  ]
}' \
"http://localhost:8080/openidm/managed/assignment?_action=create"
{
  "_id": "1a6a3af3-024f-4cf1-b4f6-116b98053816",
  "_rev": "00000000b2329649",
  "name": "employee",
  "description": "Assignment for employees.",
  "mapping": "managedUser_systemLdapAccounts",
  "attributes": [
    {
      "name": "employeeType",
      "value": [
        "Employee"
      ],
      "assignmentOperation": "mergeWithTarget",
      "unassignmentOperation": "removeFromTarget"
    }
  ]
}

Note that at this stage, the assignment is not linked to any role, so no user can make use of the assignment. You must add the assignment to a role, as described in Add an Assignment to a Role.

Using the Platform admin UI

Go to people Identities > Manage, select the vpn_key Assignments tab, and click New Assignment.
Enter a Name and Description for the new assignment.
Select the Mapping to which the assignment should apply. The mapping indicates the target resource, that is, the resource on which the attributes specified in the assignment will be adjusted.
Click Next, then Save.

The assignment’s Details tab displays, with Assignment Attributes and Event Scripts sections.
In the Assignment Attributes section, click Add an attribute to attach an attribute to the assignment.
Select the Target system attribute, and enter the Value of the attribute.
Click the gear icon next to the attribute, and determine the action to take when assigning and unassigning the attribute to a user:
- On Assignment, select one of the following:
  - Merge with target: the attribute value is added to any existing values for that attribute. This operation merges the existing value of the target object attribute with the values from the assignment. If duplicate values are found (for attributes that take a list as a value), each value is included only once in the resulting target. This assignment operation is used only with complex attribute values like arrays and objects, and does not work with strings or numbers.
  - Replace target: the attribute value overwrites any existing values for that attribute. The value from the assignment becomes the authoritative source for the attribute.
- On Unassignment, select one of the following:
  - Remove from target: the attribute value is removed from the system object when the user is no longer a member of the role, or when the assignment itself is removed from the role definition.
  - No Operation: removing the assignment from the user’s effectiveAssignments has no effect on the current state of the attribute in the system object.
Repeat the previous three steps until you’ve added all the attributes required for the assignment.
In the Event Scripts section, click Add an event script to specify any scriptable events associated with this assignment.

The assignment and unassignment operations described in a previous step operate at the attribute level. That is, you specify what should happen with each attribute affected by the assignment when the assignment is applied to a user, or removed from a user.

The scriptable On assignment and On unassignment events operate at the assignment level, rather than the attribute level. Define scripts here to apply additional logic or operations that should be performed when a user (or other object) receives or loses an entire assignment. This logic can be anything that isn’t restricted to an operation on a single attribute.

For information about the variables available to these scripts, refer to Variables available to role assignment scripts.

To attach the new assignment to an existing role definition, refer to Add an Assignment to a Role.

Using the legacy admin UI

Select Manage > Assignment > New Assignment.
Enter a name and description for the new assignment.
Select the mapping to which the assignment should apply. The mapping indicates the target resource, that is, the resource on which the attributes specified in the assignment will be adjusted.
Select Save to add the assignment.
Select the Attributes tab and select the attribute or attributes whose values will be adjusted by this assignment. The attribute you select here will determine what is displayed next:
- Regular text field—specify what the value of the attribute should be, when this assignment is applied.
- Item button—specify a managed object type, such as an object, relationship, or string.
- Properties button—specify additional information, such as an array of role references.
Select the assignment operation from the dropdown list:
- Merge With Target: the attribute value will be added to any existing values for that attribute. This operation merges the existing value of the target object attribute with the values from the assignment. If duplicate values are found (for attributes that take a list as a value), each value is included only once in the resulting target. This assignment operation is used only with complex attribute values like arrays and objects, and does not work with strings or numbers.
- Replace Target: the attribute value will overwrite any existing values for that attribute. The value from the assignment becomes the authoritative source for the attribute.
Select the unassignment operation from the list:
- Remove From Target: the attribute value is removed from the system object when the user is no longer a member of the role, or when the assignment itself is removed from the role definition.
- No Operation: removing the assignment from the user’s effectiveAssignments has no effect on the current state of the attribute in the system object.
Select the Events tab to specify any scriptable events associated with this assignment.

The assignment and unassignment operations described in the previous step operate at the attribute level. That is, you specify what should happen with each attribute affected by the assignment when the assignment is applied to a user, or removed from a user.

The scriptable On assignment and On unassignment events operate at the assignment level, rather than the attribute level. Define scripts here to apply additional logic or operations that should be performed when a user (or other object) receives or loses an entire assignment. This logic can be anything that isn’t restricted to an operation on a single attribute.

For information about the variables available to these scripts, refer to Variables available to role assignment scripts.
Select the assignment_ind Roles tab to attach this assignment to an existing role definition.

Attribute encryption on assignments

Assignment attributes are encrypted if the corresponding connector attribute indicates confidentiality, based on the attribute’s nativeType (such as JAVA_TYPE_GUARDEDSTRING or JAVA_TYPE_GUARDED_BYTE_ARRAY).

The managed assignment object includes the following property:

"attributeEncryption" : { }

If attributeEncryption is not present on managed/assignment, the assignment attributes are not encrypted. If the property is present but empty, it defaults to IDM’s default encryption cipher. To specify a different cipher, add the cipher property. For example:

"attributeEncryption" : {
  "cipher" : "AES/CBC/PKCS5Padding"
}

This functionality uses the idm.assignment.attribute.encryption secret. For more information, refer to Secret stores.

Add an assignment to a role

After you have created a role and an assignment, you create a relationship between the assignment and the role in much the same way as a user references a role.

Update a role definition to include one or more assignments over the REST interface, or using the Platform admin UI or the legacy admin UI:

Using REST

Update the role definition to include a reference to the ID of the assignment in the assignments property of the role. The following example adds the employee assignment (ID 1a6a3af3-024f-4cf1-b4f6-116b98053816) to an existing employee role (ID 2243f5f8-ed75-4c3b-b4b3-058d5c58fbb4):

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[
  {
    "operation": "add",
    "field": "/assignments/-",
    "value": { "_ref": "managed/assignment/1a6a3af3-024f-4cf1-b4f6-116b98053816" }
  }
]' \
"http://localhost:8080/openidm/managed/role/2243f5f8-ed75-4c3b-b4b3-058d5c58fbb4"
{
  "_id": "2243f5f8-ed75-4c3b-b4b3-058d5c58fbb4",
  "_rev": "00000000e85263c7",
  "privileges": [],
  "name": "employee",
  "description": "Role granted to all permanent employees"
}

To check that the assignment was added successfully, query the role’s assignments property:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/role/2243f5f8-ed75-4c3b-b4b3-058d5c58fbb4/assignments?_queryFilter=true&_fields=_ref/*,name,assignments"
{
  "result": [
    {
      "_id": "d15822f0-05bc-464a-927d-8e5018a234d3",
      "_rev": "0000000010eea343",
      "_refResourceCollection": "managed/assignment",
      "_refResourceId": "1a6a3af3-024f-4cf1-b4f6-116b98053816",
      "_refResourceRev": "00000000b2329649",
      "name": "employee",
      "_ref": "managed/assignment/1a6a3af3-024f-4cf1-b4f6-116b98053816",
      "_refProperties": {
        "_id": "d15822f0-05bc-464a-927d-8e5018a234d3",
        "_rev": "0000000010eea343"
      }
    }
  ],
  ...
}

The assignments property references the assignment that you created in the previous step.

To remove an assignment from a role definition, remove the reference to the assignment from the role’s assignments property.

Using the Platform admin UI

Go to people Identities > Manage, select the assignment_ind Roles tab, and select the role to which you want to add an assignment.
Select the Managed Assignments tab, and click Add Managed Assignments.
Select the assignment that you want to add to the role, then click Save.

Using the legacy admin UI

Select Manage > Role, and select the role to which you want to add an assignment.
Select the Managed Assignments tab, and select Add Managed Assignments.
Select the assignment that you want to add to the role, then select Add.

Delete an assignment

Delete assignments over the REST interface, or using the Platform admin UI or the legacy admin UI:

Using REST

To delete an assignment over the REST interface, simply delete that object. The following example deletes the employee assignment created in the previous example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/managed/assignment/1a6a3af3-024f-4cf1-b4f6-116b98053816"
{
  "_id": "1a6a3af3-024f-4cf1-b4f6-116b98053816",
  "_rev": "00000000b2329649",
  "name": "employee",
  "description": "Assignment for employees.",
  "mapping": "managedUser_systemLdapAccounts",
  "attributes": [
    {
      "name": "employeeType",
      "value": [
        "Employee"
      ],
      "assignmentOperation": "mergeWithTarget",
      "unassignmentOperation": "removeFromTarget"
    }
  ]
}

You can delete an assignment, even if it is referenced by a managed role. When the assignment is removed, any users to whom the corresponding roles were granted will no longer have that assignment in their list of effectiveAssignments. For more information about effective roles and effective assignments, refer to Effective roles and effective assignments.

Using the Platform admin UI or the legacy admin UI

To delete an assignment using the Platform admin UI, go to people Identities > Manage, select the vpn_key Assignments tab, and select the assignment you want to remove. Click Delete Assignment.

To delete an assignment using the legacy admin UI, select Manage > Assignment. Select the assignment you want to remove, then select Delete.

PingIDM

Use assignments to provision users

Create an Assignment

Using REST

Using the Platform admin UI

Using the legacy admin UI

Attribute encryption on assignments

Add an assignment to a role

Using REST

Using the Platform admin UI

Using the legacy admin UI

Delete an assignment

Using REST

Using the Platform admin UI or the legacy admin UI