Use assignments to provision users

Authorization roles control access to IDM itself. Provisioning roles define the rules for how attribute values update on external systems.

You configure these rules using assignments that are attached to a provisioning role definition or directly assigned to a user. Assignments provision an attribute or set of attributes based on an object’s role membership or through a direct assignment. After you configure a synchronization mapping configuration between two resources to provide the basic account provisioning logic (how an account is mapped from a source to a target system), then you can use role assignments to add more logic. The attributes and values that are updated by using assignments might include membership in external groups, access to specific external resources, and so on. A set of assignments can collectively represent a role.

Assignment objects are created, updated, and deleted like any other managed object, and are attached to a role by using the relationships mechanism, in much the same way as a role is granted to a user. Assignments are stored in the repository and are accessible at the context path /openidm/managed/realm-name_assignment.

This section describes how to manage assignments over the REST interface, and by using the Advanced Identity Cloud admin UI.

When you create an assignment, and if desired, attach it to a role definition, all user objects that reference that role definition will, as a result, 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 that the target query must return the _id of the object as well as 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 Advanced Identity Cloud admin UI.

Over REST

To create a new assignment over REST, send a PUT or POST request to the /openidm/managed/realm-name_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 managedAlpha_user_systemLdapAccounts, so attributes will be updated on the external LDAP system specified in this mapping.

The external system must be configured through a connector and a mapping defined before you can attach an assignment to the mapping.
The name of the attribute on the external system whose value will be set is employeeType, and its value 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 (if the role is deleted, or if the user is no longer a member of that role), the attribute value Employee is removed from the values of that attribute.

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "name": "employee",
  "description": "Assignment for employees",
  "mapping": "managedAlpha_user_systemLdapAccounts",
  "attributes": [
    {
      "name": "employeeType",
      "value": [
        "Employee"
      ],
      "assignmentOperation": "mergeWithTarget",
      "unassignmentOperation": "removeFromTarget"
    }
  ]
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_assignment?_action=create"
{
  "_id": "1a6a3af3-024f-4cf1-b4f6-116b98053816",
  "_rev": "132bbd98-b3d6-4d70-9274-7bcd4e765d3a-6329",
  "name": "employee",
  "description": "Assignment for employees",
  "mapping": "managedAlpha_user_systemLdapAccounts",
  "attributes": [
    {
      "name": "employeeType",
      "value": [
        "Employee"
      ],
      "assignmentOperation": "mergeWithTarget",
      "unassignmentOperation": "removeFromTarget"
    }
  ]
}

At this stage the assignment is not linked to any role, so no user can make use of the assignment. To make use of the assignment, either Add a user directly to an assignment or Add an assignment to a role.

Using the Advanced Identity Cloud admin UI

Select Identities > Manage > Alpha realm - Assignments > + New Alpha realm - assignment.
Enter a name, description, and 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.
Click + Add an attribute to attach an attribute to your assignment.
Select the Target system attribute, enter the Value of the attribute.
Click the gear icon and determine the action to take when assigning and unassigning the attribute to a user:
1. 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 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 overwrites any existing values for that attribute. The value from the assignment becomes the authoritative source for the attribute.
2. 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: When you remove the assignment from the user’s effectiveAssignments, it has no effect on the current state of the attribute in the system object.
Repeat steps 4-6 until you have added all the attributes required for the assignment.
Click Save.

Modify an assignment

After you create an assignment, you can modify it by doing one or more of the following:

Add script logic when assignment is granted or revoked
Add a user directly to an assignment
Add an assignment to a role
Delete an assignment

Add script logic when assignment is granted or revoked

After you create an assignment, you can specify custom logic to take place during assignment or unassignment of an assignment.

These scripts apply additional logic or operations that should be performed when a user (or other object) receives or loses an entire assignment. This logic must not be restricted to an operation on a single attribute.

For example, if an assignment is removed from a user, in the onUnassignment event, the system can automatically perform additional actions such as revoking access to any external systems, sending notifications to managers or IT staff, and archiving or deleting the users’s data.

To create a script to associate with an assignment event:

On the Details tab of the assignment in the Event Scripts section, click Add an event script.
In the Event box, select the script to apply to onAssignment or onUnassignment of the assignment to the user.

Define the script by specifying what should happen to each attribute in the script.

The scriptable onAssignment and onUnassignment events operate at the assignment level, rather than the attribute level.

The onAssignment and onUnassignment events occur before the onCreate or onUpdate scripts.

Table 1. Variables available in assignment script
Variable	Description
`sourceObject`	The full, original object from the source system (in this case, Advanced Identity Cloud).
`targetObject`	The current, computed value, from the mapping logic. This results from the property mapping logic or prior assignment computation.
`existingTargetObject`	The object that exists (if any) in the current target system, before the update is made.
`linkQualifier`	A string value that represents a version of the source object as it is mapped to a record in the target system. There can be multiple `linkQualifiers` for a given mapping, but in this context, it is the one being processed. For more information, refer to Map a single source object to multiple target objects.
`attributeName`	The name of the attribute in the assignment to reference.
`attributeValue`	The value of an attribute in the assignment to reference.
`attributesInfo`	A mechanism that allows one invocation of an `onAssignment` or `onUnassignment` events to communicate helpful information to other invocations, as needed.

Role assignment scripts must always return targetObject, otherwise other scripts and code that occur downstream of your script will not work as expected. For example, specify:

return targetObject;

Add a user directly to an assignment

You can add an assignment directly to users in Advanced Identity Cloud instead of through a role.

Add users to an assignment directly over REST or using the Advanced Identity Cloud admin UI.

Over REST

Update the assignment definition to include a reference to the ID of the user in the members property of the assignment.

The following example adds the user (ID 1a6a3af3-024f-4cf1-b4f6-116b98053816) to an existing assignment (ID assignmentTest):

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[
{
  "operation": "add",
  "field": "/members/-",
  "value": { "_ref": "managed/realm-name_user/1a6a3af3-024f-4cf1-b4f6-116b98053816" }
}
]' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_assignment/assignmentTest"
{
  "_id": "assignmentTest",
  "_rev": "4f50bccb-dbad-46dd-b703-962ae61c77c9-1683",
  "name": "assignmentTest",
  "description": "This is an assignment",
  "mapping": "managedAlpha_user_systemLdapAccounts",
  "attributes": []
}

Using the Advanced Identity Cloud admin UI

Select Identities > Manage > Alpha realm - Assignments > assignment.
Select the Assignment Members tab.
Click +Add Assignment Members.
Select the user(s) to directly add to the assignment.
Click Save.

Add an assignment to a role

After you create a role and an assignment, 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 Advanced Identity Cloud 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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[
{
    "operation": "add",
    "field": "/assignments/-",
    "value": { "_ref": "managed/realm-name_assignment/1a6a3af3-024f-4cf1-b4f6-116b98053816" }
  }
]' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/2243f5f8-ed75-4c3b-b4b3-058d5c58fbb4"
{
  "_id": "2243f5f8-ed75-4c3b-b4b3-058d5c58fbb4",
  "_rev": "132bbd98-b3d6-4d70-9274-7bcd4e765d3a-4145",
  "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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/2243f5f8-ed75-4c3b-b4b3-058d5c58fbb4/assignments?_queryFilter=true&_fields=_ref/*,name,assignments"
{
  "result": [
    {
        "_id": "8189bbb9-a7fb-45cb-b4c0-49a6ddd47b64",
        "_rev": "132bbd98-b3d6-4d70-9274-7bcd4e765d3a-4144",
        "_refResourceCollection": "managed/realm-name_assignment",
        "_refResourceId": "1a6a3af3-024f-4cf1-b4f6-116b98053816",
        "_refResourceRev": "132bbd98-b3d6-4d70-9274-7bcd4e765d3a-6329",
        "name": "Employee",
        "_ref": "managed/realm-name_assignment/alpha_assignment/1a6a3af3-024f-4cf1-b4f6-116b98053816",
        "_refProperties": {
            "_id": "8189bbb9-a7fb-45cb-b4c0-49a6ddd47b64",
            "_rev": "132bbd98-b3d6-4d70-9274-7bcd4e765d3a-4144"
        }
    }
  ],
  ...
}

The assignments property references the assignment shown 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 Advanced Identity Cloud admin UI

You can assign an assignment to a role in the following ways:

From an assignment to a role
From a role to an assignment
From assignment to role
Select Identities > Manage > Alpha realm - Assignments > assignment.

Click the Managed Roles tab.

Click + Add Managed Roles.

Select the role(s) to associate to the assignment.

Click Save.
From role to assignment
Select Identities > Manage > Alpha realm - Roles > role.

Select the Managed Assignments tab and click + Add Managed Assignments.

Select the assignment(s) to associate to the role.

Click Save.

Delete an assignment

You can delete assignments over REST or using the Advanced Identity Cloud admin UI.

Deleting an assignment may result in large downstream impacts, such as removing attributes or access to many users in an external system.

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.

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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_assignment/1a6a3af3-024f-4cf1-b4f6-116b98053816"
{
  "_id": "1a6a3af3-024f-4cf1-b4f6-116b98053816",
  "_rev": "132bbd98-b3d6-4d70-9274-7bcd4e765d3a-6329",
  "name": "employee",
  "description": "Assignment for employees",
  "mapping": "managedAlpha_user_systemLdapAccounts",
  "attributes": [
    {
      "name": "employeeType",
      "value": [
        "Employee"
      ],
      "assignmentOperation": "mergeWithTarget",
      "unassignmentOperation": "removeFromTarget"
    }
  ]
}

Using the Advanced Identity Cloud admin UI

In the Advanced Identity Cloud admin UI, select Identities > Manage > Alpha realm - Assignments > assignment.
In the Details tab > Delete Alpha realm - Assignment section, click Delete Alpha realm - Assignment.
A confirmation dialog displays. Click Delete.

PingOne Advanced Identity Cloud

Use assignments to provision users

Create an assignment

Modify an assignment

Add script logic when assignment is granted or revoked

Add a user directly to an assignment

Add an assignment to a role

Delete an assignment