Introduction

Delegated Administration of Identity and Identity Metadata is a key feature of PingOne Advanced Identity Cloud (AIC)’s Organization structure. It allows end-users to self-manage key aspects of themselves, their users, and the metadata within the group that they’re managing. As a Tenant Administrator, you have control over what capabilities are templatized on every identity type (i.e. Users/Orgs) as well as what level of control each type of delegated user has to those capabilities.

This How-To will teach you what Delegated Administration means in AIC and how to create your own Administrative permissions. It expects an existing understanding of REST APIs, AIC’s Organization Model, and (optionally) how to use FroDo CLI.

Understanding the Delegated Administration Model

By default, an Organization will have 3 delegated relationship types: Members, Admins, and Owners. Members have the least amount of privilege while Owners have the most. As a Tenant Administrator, you have the highest level of permissions over and above the 3 delegated relationships.

Users within your tenant can be assigned more than one delegated relationship across more than one Organization or Organization hierarchy (tree). Users can also be assigned more than one delegated relationship type. Some good examples of why you may want to do this include:

• A Medical Provider (Admin) who also is a Patient (Member)
• A Customer Success Manager (Admin) who supports multiple business units or business partners (Multiple Trees)
• A Fan (Member) of multiple Teams in a Franchise

Organization membership is inherited, meaning that if you assign a user as an Owner, Admin, or Member of a parent Organization they will also have that permission to the Organization’s children.

Note that delegated administration in this case is specifically Identity Management (IDM)-focused: meaning that we are managing metadata on Users and Organizations, not delegating Tenant Admin functionality like IGA, Applications, Journeys, etc.

Delegated Administration Defaults

The default Organization model provides a foundation to build additional templated functionality into your IAM strategy. As such, the default permissions for each delegated administration type are focused on creating the Organization and then managing the individuals associated with it.

Think of the default permissions like a series of nested circles with Members in the center. As you traverse wider out in the circle, your permissions increase. An example diagram of what this might look like with additional features on your Organization is below.

Example Relationship Mapping for Default Organization Modeling User Types

Where the Privileges are Managed

Delegated administration for organizations is represented by a relationship between the Organization and the User. The permissions on these relationships are in two JSON configuration files stored within the Identity Manager (IDM) of AIC, called alphaOrgPrivileges and privilegeAssigments. alphaOrgPrivileges and privilegeAssigments are the files we are going to be looking at and modifying within this How-To.

Managing Delegated Admin Privileges

As your business grows your Organization model and the ways your users interact with the Organization will grow alongside it. We need to update our delegated administrator’s permissions to match the capabilities we need each relationship type to be able to do.

Example calls will be provided both as a cURL and FroDo command. If you are using cURL, you will need to generate an Access Token using a service account with the fr:idm:* scope.

Retrieving the Privileges

Retrieving the Organization Privileges

Retrieve your alphaOrgPrivileges using one of the following options. Since we will be updating your Organization privileges, save a copy of the output in case you’d like to revert your changes later.

Option 1: REST

curl --location 'https://{tenant-domain}/openidm/config/alphaOrgPrivileges' \
--header 'Authorization: Bearer ****' -o original_alphaOrgPrivileges.json

Option 2: FroDo

frodo idm export -f original_alphaOrgPrivileges.json -i alphaOrgPrivileges <tenant>

(Optional) Retrieving the Privilege Assignments

If you are looking to create additional permissions you’ll need to pull down the privilegeAssignments.json configuration, which maps the permissions in the privilege file to the appropriate delegated administration type. As before, save a copy of the output in case you’d like to revert your changes later.

Option 1: REST

curl --location 'https://{tenant-domain}/openidm/config/privilegeAssignments' \
--header 'Authorization: Bearer ****' -o original_privilegeAssignments.json

Option 2: FroDo

frodo idm export -f original_privilegeAssignments.json -i privilegeAssignments <tenant>

Understanding the Privileges

Open the original_alphaOrgPrivileges.json file in a text editor of your choosing. You’ll find a JSON object with two main keys: the _id telling you what config file you’re looking at (should be alphaOrgPrivileges if you pulled the right file) and a privileges array that holds all of the capabilities for each delegation type.

Let’s take a look at a single privilege to understand how this works. I’ve stripped out the details so that we can look at the keys specifically.

{
    "accessFlags": [
        {
            "attribute": "",
            "readOnly": true
        }
    ],
    "actions": [],
    "filter": "queryfilter",
    "name": "descriptive-permission-name",
    "path": "managed/path",
    "permissions": [
        "CREATE",
        "VIEW",
        "UPDATE",
        "DELETE",
        "ACTION"
    ]
}

Default Privilege Assignments

The privilegeAssignments.json configuration file comes with a series of default privilege assignments which map to the name attribute in the privileges of your alphaOrgPrivileges file.

Default Owner Privileges (an Owner being defined by the ownerOfOrg relationship field):

• owner-view-update-delete-orgs
• owner-create-orgs
• owner-view-update-delete-admins-and-members
• owner-create-admins
• admin-view-update-delete-members
• admin-create-members

Default Admin Privileges (an Admin being defined by the adminOfOrg relationship field):

• admin-view-update-delete-orgs
• admin-create-orgs
• admin-view-update-delete-members
• admin-create-members

Note: owner-view-update-delete-admins-and-members applies to both Admins and Members through the memberOfOrgIDs Relationship-Derived Virtual Property (RDVP), meaning that if an Administrator is assigned to an Organization and is not a member, an Owner will not be able to see or manage them (and additionally, if an Admin is a Member, and Admin can see and manage them). I’ll show you later in this document how you can break down permissions by Owner, Admin, and Member.

Reading an Existing Privilege

So let’s see what this means in practice. Taking a look at the permission owner-view-update-delete-orgs, we can learn the following:

Modifying Privileges

Make a copy of your alphaOrgPrivileges file and name it something like updated_alphaOrgPrivileges. When you’ve made your changes to the file, PUT the file back into your tenant to auto-update the privileges for your delegated administration.

Copy Command

cp original_alphaOrgPrivileges.json updated_alphaOrgPrivileges.json

Option 1: REST

curl --location --request PUT 'https://{tenant-domain}/openidm/config/alphaOrgPrivileges' \
--header 'Accept: application/json, text/javascript, */*; q=0.01' \
--header 'Content-Type: application/json' \
--header 'Bearer ****' \
--data updated_alphaOrgPrivileges.json

Option 2: FroDo

frodo idm import -f updated_alphaOrgPrivileges.json -i alphaOrgPrivileges <tenant>

The same can be said for your privilegeAssignments configuration file. Copy, and then PUT.

Copy Command

cp original_privilegeAssignments.json updated_privilegeAssignments.json

Option 1: REST

curl --location --request PUT 'https://{tenant-domain}/openidm/config/privilegeAssignments' \
--header 'Accept: application/json, text/javascript, */*; q=0.01' \
--header 'Content-Type: application/json' \
--header 'Bearer ****' \
--data updated_privilegeAssignments.json

Option 2: FroDo

frodo idm import -f updated_privilegeAssignments.json -i privilegeAssignments <tenant>

When you’re done modifying permissions, it’s possible that your privileges will look more like a Venn Diagram than a series of nested circles.

Let’s take a look at some ways we may want to modify our privileges.

Updating Existing Privileges

In most cases, the existing privilege set defined in your alphaOrgPrivileges will already cover what actions you want your delegated administrator to take - you’ll just need to update what attributes they have access to.

As an example, let’s say that we want our Administrators to be able to view the first and last name of their pre-existing Members but not be able to update them.

Default Admin Behavior - Managing Member First Name and Last Name

Make a copy of your alphaOrgPrivileges file and search for the admin-view-update-delete-members privilege. Under its accessFlags, you can see that the readOnly values for both givenName and sn are set to false.

{
    "accessFlags": [
        {
            "attribute": "userName",
            "readOnly": false
        },
        {
            "attribute": "password",
            "readOnly": false
        },
        {
            "attribute": "givenName",
            "readOnly": false // <-- this one
        },
        {
            "attribute": "sn",
            "readOnly": false // <-- and this one
        },
        ...
    ],
    "actions": [],
    "filter": "/memberOfOrgIDs eq \"__org_id_placeholder__\"",
    "name": "admin-view-update-delete-members",
    "path": "managed/alpha_user",
    "permissions": [
        "VIEW",
        "DELETE",
        "UPDATE"
    ]
}

Let’s set both of those fields to true.

// Inside the "accessFlags" section of "admin-view-update-delete-members":
{
    "attribute": "givenName",
    "readOnly": true
},
{
    "attribute": "sn",
    "readOnly": true
},

Save and push the updated config. When you refresh the page as an admin, you’ll see that you have read-only permissions to those attributes.

Updated Admin Behavior - Read Only

Some other reasons why you may modify an existing privilege include:

• Adding Attributes on Organizations or Members for Owners and/or Admins to manage or view. This is your most likely use case as you add custom attributes to your Organization or leverage existing indexed attributes on your Users.
• Removing Attributes that you don’t want Owners and/or Admins to manage at all. As you specify what permissions each role is capable of managing, it’s likely that some features and functionality should be stripped from the delegated administrator.
• Modifying Attribute Permissions so that an Owner and Admin has distinctly different permissions when interacting with an Organization.

Note: Modify the Filters and Permissions at your own risk. Updating these values without careful consideration could result in over-permissioning your delegated administrators to an unexpected subset of Users and Organizations.

Creating New Privileges

There may be rare cases in which you’d like to create an additional delegated administrative permission. To do so, you’ll need to update the privilegeAssignments file to handle that permission.

In this example, let’s create a privilege that enables administrators to view, edit, and delete the first and last name of a subset of their Members. This subset will be defined by a “Enable Customer Support” attribute that we’ll define on the User object - that way, Members can self-service if they want their name to be updated by an Administrator.

Creating an Attribute to Filter by

To create this attribute, head to the Native Consoles → Identity Management and then to your Managed Alpha User (Configure → Managed Objects → alpha_User).

The Managed Alpha User

Once there, select “Add a Property” and create a new attribute with the following details:

Once created, select the attribute and under Show advanced options set “Searchable” to true (enabled).

Setting Searchable to True

After saving our updates, when we look at a User we’ll see the “Enable Customer Support” option on their profile.

The User’s View

Now that we have the attribute we want to filter by, let’s create a new privilege which will look for this filter.

Creating the New Privilege

Make a copy of your privilegeAssignments file. Within that file, underneath the adminPrivileges privilegeAssignment, add the privilege "admin-view-update-delete-supportable-members". Your adminPrivileges should look something like this:

{
    "name": "adminPrivileges",
    "privileges": [
        "admin-view-update-delete-orgs",
        "admin-create-orgs",
        "admin-view-update-delete-members",
        "admin-view-update-delete-supportable-members", // <-- This one is new!
        "admin-create-members"
    ],
    "relationshipField": "adminOfOrg"
}

Save and push the updated privileges config.

Next, inside the alphaOrgPrivileges, let’s make a new privilege. I’ll be copying the functionality from within admin-view-update-delete-members to start.

In our last example, we prevented Admins from being able to update an existing Member’s first name and last name. This privilege is going to let us update the names of Members who fulfill a specific criteria, in this case if the member has enabled the “supportable” permission.

In our new admin-view-update-delete-supportable-members privilege, let’s change the readOnly values of givenName and sn back to false. Additionally, let’s update the filter to only include Members who have the custom_supportable attribute set to true:

"filter": "/memberOfOrgIDs eq \"__org_id_placeholder__\" and custom_supportable eq true"

Your new privilege should look something like this:

{
    "accessFlags": [
        {
        "attribute": "userName",
        "readOnly": false
        },
        {
        "attribute": "password",
        "readOnly": false
        },
        {
        "attribute": "givenName",
        "readOnly": false // <-- Make sure to change this back
        },
        {
        "attribute": "sn",
        "readOnly": false // <-- Change this one too
        },
        ...
    ],
    "actions": [],
    "filter": "/memberOfOrgIDs eq \"__org_id_placeholder__\" and custom_supportable eq true", // <-- Your new filter
    "name": "admin-view-update-delete-supportable-members", // <-- Your new privilege
    "path": "managed/alpha_user",
    "permissions": [
        "VIEW",
        "DELETE",
        "UPDATE"
    ]
}

Save and push the updated alpha org privileges config.

Testing the Functionality

Log in as a Member and an Administrator on two separate browsers. By default, the Administrator won’t be able to manage the Member’s first and last name. As the Member, set “Enable Customer Support” to true (enabled) and then refresh the Administrator’s page. You now have access as an Administrator to manage the Member’s name!

Setting Member’s Support to Enabled (under /enduser/?realm=/alpha#/profile)

Supporting that Identity as an Administrator

By creating a new privilege we can filter to specific subsets of users that we want different sets of delegated administration to manage. Some other reasons why you may create a new privilege include:

• Custom Relationships such as Employee/Manager, Department Leader/Team, Family Head/Members which have increased permissions than a standard Administrator
• Attribute-based flags (ABAC and RBAC) where users can self-service or be dynamically added to specific support tiers or management rights

Splitting Owner, Admin, and Member Privileges

As noted in Default Privilege Assignments, there are some privileges that apply to both Administrators and Members due to the default configuration of the Organization and User. There may be situations, however, where it’s advantageous to have a separate privilege applying to Owners, Admins, or Members only.

In this example, we’ll create a new privilege for Owners to be able to view, update, and delete attributes on Administrators only. To do that, we’ll need to define a way to reference Admins and their downstream Organizations that they are managing.

Creating the Admin of Orgs Reference

First off, we’re going to need to create a new RDVP on our Managed Organization which tracks the IDs of the Children.

In your Native IDM console (Native Consoles → Identity Management) and head to your Managed Organization (Configure → Managed Objects → alpha_organization).

Editing the Alpha Organization

Once there, select “Add a Property” and create a new attribute with the following details:

Select the newly-created attribute, and under Details → Advanced Options, disable Viewable and User Editable and enable Virtual and Return by Default. You know you’ve done this right when after saving the Query Configuration tab appears on the page.

Editing the Child IDs Advanced Properties

Select Query Configuration, and input the following fields:

Setting the ChildIDs Query

Next, we will need to notify the appropriate relationships that changes have been made so that they update correctly. To do that, head back to the Organization Attribute management screen.

Once there, select the parent attribute. Under Relationship Configuration, select the Edit button next to the “parent” alpha_organization and set “Notify” to true (enabled). This notifies the child that a relationship change has occurred on the parent.

Editing the Child Relationship

Ensuring the Child is Notified on Relationship Change

Back on the main Organization screen, Select the children attribute and under Details → Advanced Options → Notify Relationships select parent and admins. This notifies the parent and the admins that a change has occurred on the child.

Notifying the Parent and Admin of Changes on the Child

Finally, we’re going to need to create a new RDVP on our Managed User which tracks the Organizations a User is an Administrator of. Head to your Managed Alpha User (Configure → Managed Objects → alpha_user) and select the first Generic Indexed Multivalue attribute you aren’t using (mine is frIndexedMultivalued1). Note that you can use a custom attribute, but if an attribute is already there let’s use it!

Just like with the childIDs, under advanced options deselect “Viewable”, “Searchable”, and “User Editable” and select “Virtual” and “Return by Default”. I’m also renaming my title to “Admin of Org IDs” so it’s easier for me to find later.

Enabling the RDVP

Select Query Configuration, and input the following fields:

Setting the Query

Now for an RDVP to take effect we will need to make a change in our Organization. Make a Child Organization and assign it to the Organization you’ve been testing with.

The Child to Parent Org Relationship

If you’ve set up your new RDVP correctly, you’ll see back on your parent organization, inside of “Raw JSON”, that the child you just created has been assigned.

There’s the Child Org ID!

The same will be said for your Admin. If you look at their frIndexedMultivalued1 attribute (the one we set in this example), both the IDs of the Parent they are directly assigned to AND the Child they now manage are present.

AdminOrgIDs in Practice

Now that we have the means to reference specifically organization IDs related to our Administrators, let’s create a privilege that targets Administrators only.

Creating the Owner-to-Admin Privilege

Make a copy of your privilegeAssignments file. Within that file, underneath the ownerPrivileges privilegeAssignment, add the privilege "owner-view-update-delete-admins". Your ownerPrivileges should look something like this:

{
    "name": "ownerPrivileges",
    "privileges": [
        "owner-view-update-delete-orgs",
        "owner-create-orgs",
        "owner-view-update-delete-admins-and-members",
        "owner-view-update-delete-admins", // <-- This is your new privilege
        "owner-create-admins",
        "admin-view-update-delete-members",
        "admin-create-members"
    ],
    "relationshipField": "ownerOfOrg"
}

Save and push the updated privileges config.

In our last example, we prevented Admins from being able to update an existing Member’s first name and last name. By default, since owners have their own privilege to manage Admins and Members (owner-view-update-delete-admins-and-members), an Owner is still able to manage these attributes. Let’s change it so an Owner can still change the first and last name on a Member but not on an Administrator.

Going back to the alphaOrgPrivileges, let’s duplicate the owner-view-update-delete-admins-and-members permission.

In our new owner-view-update-delete-admins privilege, let’s change the readOnly values of givenName and sn to true just like we did for admin-view-update-delete-members. Additionally, we are going to change our filter so that it targets the new “Admin of Org IDs” (frIndexedMultivalued1) attribute we created on our users.

Your new privilege should look something like this:

{
    "accessFlags": [
        {
            "attribute": "userName",
            "readOnly": false
        },
        {
            "attribute": "password",
            "readOnly": false
        },
        {
            "attribute": "givenName",
            "readOnly": true // <-- This should be set
        },
        {
            "attribute": "sn",
            "readOnly": true // <-- And this
        },
        ...
    ],
    "actions": [],
    "filter": "/frIndexedMultivalued1 eq \"__org_id_placeholder__\"", // <-- Your new query
    "name": "owner-view-update-delete-admins", // <-- Your new privilege
    "path": "managed/alpha_user",
    "permissions": [
        "VIEW",
        "DELETE",
        "UPDATE"
    ]
}

Save and push the updated alpha org privileges config.

Testing the Functionality

Now, let’s log in as an Owner. When you select a Member, you’ll see that you can update their first name and last name.

The Owner’s Member Management Permissions

When you select the Administrator, you’ll see that you can’t update their first and last name!

The Owner’s Admin Management Permissions

We’ve now seen how to manage privileges for each delegated administration type. Note that you can extend this further, by:

• Tracking OwnerOfOrgIDs so that you can delegate permission to Owner users from Members or Admins
• Creating new Delegated Administration types where you can granularize the management of users further

Note that if you add any new RDVPs to match what you did for admins you’d have to use a new indexed attribute and add that relationship (for example, owners) to the “Notify Relationships” on the Children relationship just like you did for admins.

Conclusion

This How-To should give you the tools you need to read, manage, and update delegated administrative permissions for your Organization users within your AIC tenant. With it you should be able to build access policies and controls that define fine-grained permissions for each user type that can self-serve themselves, their Organizations, and the people they are related to.