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.

This section describes how to manipulate assignments over the REST interface and the 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 or using the admin UI:

Over 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 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 value(s) 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 drop-down 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 is not 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 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 by using the admin UI:

Over 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": "Roll 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"
      }
    }
  ],
  ...
}

Note that 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 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 by using the admin UI:

Over 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 admin UI

To delete an assignment by using the admin UI, select Manage > Assignment.

Select the assignment you want to remove, then select Delete.

PingIDM 7.5.0

Use assignments to provision users

Create an Assignment

Attribute encryption on assignments

Add an assignment to a role

Delete an assignment