Role-based User Provisioning

To provision users based on roles, you must specify an Admin Portal role. Users with the Admin Portal role will be matched to existing or new accounts in your app, within the specified groups.

The CyberArk Identity Platform immediately synchronizes user account and role mapping changes.

Provisioning assigns users access and assignments based on the top-most role mapping. The order of the roles displayed in the Role Mappings section represents priority. The role at the top of the list has user provisioning priority. For example, if a user has mapped provisioning for multiple roles, the CyberArk Identity Platform provisions the user, based on the top-most role in the list. For more details, see Setting up app-specific provisioning.

To automatically provision users with accounts:

1. Ensure that the provisioning credentials are entered and verified.

2. Go to the Role Mappings section, on the Provisioning page.

3. Click Add, to open the Role Mapping dialog box.

4. Select a Role.

5. Click Add and select a Destination Group from the drop-down list.

   A Destination Group (named after the selected role), automatically populates the list of groups available from the drop-down list. If that Destination Group is selected:

   • If the Destination Group does not exist in the application, a group is created.
   • If the Destination Group already exists in the application, the existing group is used.
   • User members that are associated with the role are added as members of the Destination Group.

📘

Note

(Optional) Type in a new group name, to map the group to the selected role. The newly created Destination Group is also created in the application. If the role is removed from role mapping, the Destination Group remains within the application, without affecting existing membership.

Changing the role or role name only affects group creation if the group name in the role mapping is also changed.

6. (Optional) Add more Destination Groups, if desired, by repeating the previous two steps.

7. Click Done to save the role mapping and return to the Provisioning page.

8. Continue adding role mappings, as desired.

   • To change a mapping, select the role mapping and click Modify from the Actions list.
   • To remove a mapping, select the role mapping and click Delete from the Actions list.

📘

Note

The provisioning script is intended for advanced users who are familiar with editing server-side JavaScript code.

9. When role mapping is complete, click Save to save the provisioning details.

📘

Note

Any time role mapping provisioning changes, the CyberArk Identity automatically runs a synchronization. If desired, you can run a preview synchronization or a real synchronization.

Update Role Mappings

You can use the UpdateAppRoleMappings API to update only the role mapping section of a specific application using using appkey.
You can perform the following operations:

• Add
• Remove
• Replace
• Update

Request sample:
URL: https://{{tenant_id}}/UserProv/UpdateAppRoleMappings

Action: POST

{
    "appKey": "e2848205-55b9-434b-9cfc-113452c5a3b4",
    "operation": "add/remove/replace/update"
    "settings": {
        "RoleMappings": [
            {
                "RoleName": "Role1",
                "DestinationGroups": [
                    {
                        "Friendly": "Role1"
                    }
                ]
            },
            {
                "RoleName": "Role3",
                "DestinationGroups": [
                    {
                        "Friendly": "Role3"
                    }
                ]
            }
        ]
    }
}

Validations:

• ‘AppKey’ should be available and valid.
• One of the following ‘Operation’ should be available: add/remove/update/replace.
• ‘RoleName’ must be valid. You must create or use the existing Role name in the Admin portal.

Add operation

Use this operation to add the new Role Mapping to existing Role Mappings.
Payload :

URL: https://{{tenant_id}}/UserProv/UpdateAppRoleMappings

Action Method: POST

{
    "appKey": "e2848205-55b9-434b-9cfc-113452c5a3b4",
    "operation": "add",
    "settings": {
        "RoleMappings": [
            {
                "RoleName": "Role1",
                "DestinationGroups": [
                    {
                        "Friendly": "Role1"
                    }
                ]
            },
            {
                "RoleName": "Role3",
                "DestinationGroups": [
                    {
                        "Friendly": "Role3"
                    }
                ]
            }
        ]
    }
}

Try the API in Postman:

Once you invoke the API, you can view the newly added role in the application as shown in the image below.

Remove operation

You can use this operation to remove the existing Role Mappings.

URL: https://{{tenant_id}}/UserProv/UpdateAppRoleMappings

Action Method: POST

{
      "appKey": "e2848205-55b9-434b-9cfc-113452c5a3b4",
              "operation":"remove", 
      "settings": {
        "RoleMappings": [       
            {
"RoleName": "Role1"                
            },
            {
"RoleName": "Role3"             
            },
            {
            "RoleName": "AWS Role"
            }
        ]
    }
          
}

Once you invoke the API, the above mentioned roles are removed from the application.

Update operation

You can use this operation to update the existing Role Mappings.

URL: https://{{tenant_id}}/UserProv/UpdateAppRoleMappings

Action Method: POST

{
    "appKey": "e2848205-55b9-434b-9cfc-113452c5a3b4",
    "operation": "update",
    "settings": {
        "RoleMappings": [
            {
                                       "RoleName": "Role1",
            "DestinationGroups": [
                    {
"Friendly": "Role11"
                    }
                ] },
            {
                "RoleName": "Role3",
                "DestinationGroups": [
                    {
                        "Friendly": "Role31"
                    }
                ]
            }
        ]
    }
}

Once you invoke the API, the above mentioned roles are updated in the application.

Replace operation

You can use this operation to replace all existing mappings with new mappings specified in the payload.

URL: https://{{tenant_id}}/UserProv/UpdateAppRoleMappings

Action Method: POST

{
    "appKey": "e2848205-55b9-434b-9cfc-113452c5a3b4",
    "operation": "replace",
    "settings": {
        "RoleMappings": [
            {
                "RoleName": "Role1",
                "DestinationGroups": [
                    {
                        "Friendly": "Role1"
                    }
                ]               
            },
            {
                "RoleName": "Role3",
                "DestinationGroups": [
                    {
                        "Friendly": "Role3"
                    }
                ]               
            }
        ]
    }
}

Once you invoke the API, the above mentioned roles are replaced from the application.