PingOne Advanced Identity Cloud

Configure relationships

Relationships in Advanced Identity Cloud let you link managed objects to one another. For example, you can connect end users to managers, end users to devices, or organizations to child organizations.

The default Advanced Identity Cloud schema defines several user properties as relationships. For example, the manager property on the user managed object type is a relationship that links a user to their manager (who is also a user). This relationship is many-to-one and bidirectional, which means while each user can have only one manager, a single manager can have many direct reports.

Default relationship properties on the user managed object type
Relationship property Description

manager

A many-to-one relationship linking a user to their manager, who is another managed/user object.

reports

The reverse relationship of manager. This is a one-to-many relationship linking a manager to their direct reports (other managed/user objects).

roles

A relationship linking a user to their assigned provisioning and business roles (typically referencing managed/role and internal/role objects). This is used to drive automated provisioning and access to downstream applications.

authzRoles

A relationship linking a user to their authorization roles. While roles govern what a user can access in external systems, authzRoles determine a user’s security context and administrative privileges within Advanced Identity Cloud (for example, granting a user the internal/role/openidm-admin role).

memberOfOrg

A relationship linking the user to one or more organizations (managed/organization). This is used to build hierarchical tenant or department structures and enforce delegated administration.

You can create your own custom relationship properties. A common use case is to create a custom device managed object type and then create a custom relationship property to link end users to the devices they own. This allows you to find all devices assigned to a specific end user, or to identify the owner of a particular device.

This page describes how to manage relationships in the Advanced Identity Cloud admin console. Learn about managing custom relationships using the schema API.

Best practices for relationships

Consider these best practices when managing relationships:

  • Plan your relationships carefully before creating them. Consider the use cases you want to support, the cardinality and direction of the relationships, and how they will be used in the UI and API.

  • Use clear and consistent naming conventions for relationship properties to make it easy to understand the purpose of each relationship.

  • Document the relationships you create, including their purpose, cardinality, and any RDVPs, to ensure that other administrators and developers understand how to use them effectively.

  • Regularly review and maintain your relationships to ensure they continue to meet your needs and that any changes to your identity data model are reflected in your relationships.

Each managed object type is limited to 10 custom relationship properties. If you need more, you must define additional relationships from the related managed object type instead. Learn more in Create a custom relationship.

Plan your relationships

Consider the following when planning your relationships.

Objects: Which managed objects need relating?

You can establish relationships between any two managed object types in the system. Common relationship patterns include:

  • User to Manager: Linking an employee to their supervisor.

  • User to Device: Assigning a specific piece of hardware to an individual.

  • Organization to Child Organization: Structuring parent companies and their subsidiaries.

  • Custom relationships: Building custom parent/child or owner/member hierarchies between any of your custom managed object types.

Cardinality: How many managed objects are allowed on each side of the relationship?

It can be one of the following:

  • One-to-one: Each object can be related to at most one corresponding object.

  • One-to-many: One object can be related to many corresponding objects, but each of those objects can only relate back to the original object.

  • Many-to-one: Many objects can be related to the same corresponding object, but that object can only relate back to one object on the original side.

  • Many-to-many: Objects on both sides can be related to multiple corresponding objects.

    You choose the cardinality when you create a custom relationship in the Advanced Identity Cloud admin console. You can’t change it later through this UI, so it’s important to plan this carefully.

    To change cardinality after creation, you must update the schema directly, or use the legacy IDM admin console, and then clean up any existing data that violates the new cardinality. Learn more in Update a custom relationship.

Direction: Is the relationship exposed on one or both of the managed objects?

Whether the relationship is exposed on one or both of the related objects:

  • One-way: Only one side exposes the relationship in the schema.

  • Two-way (bidirectional): Both sides expose the relationship in the schema. A change to one object in the relationship is automatically reflected on the other. For example, in a bidirectional relationship between a user and a device, if you assign a new device to the user, the user is automatically set as the owner on the corresponding device object.

    You can’t create one-way relationships in the Advanced Identity Cloud admin console, but they can exist in the schema.

Manage relationships

  1. In the Advanced Identity Cloud admin console, go to people Identities > Configure.

  2. On the Managed Object Types page, select the managed object type. For example, select Alpha realm – User.

  3. Click the Relationships tab to display all existing relationships defined for the managed object type.

  4. Do one of the following:

When you delete a relationship, Advanced Identity Cloud removes its configuration, including the relationship property definitions on the source and related managed object types, and any derived properties created from it.

However, when you delete a custom relationship property, Advanced Identity Cloud doesn’t automatically remove existing values for that property from your managed objects. You must manually update those objects to remove any leftover data. Otherwise, this orphaned data might unpredictably resurface if you later reuse the same reference attribute for a different relationship or data set.

Create a custom relationship

  1. On the Relationships tab, click add Relationship.

  2. In the Create Relationship modal, define the relationship between the managed object types:

    1. In the Object Type list, select the object type to relate to.

    2. Select the relationship’s cardinality.

    3. Click Next.

  3. On the Relationship Property page, define the relationship properties for each side of the relationship, and click Next.

  4. (optional) On the Derived Properties page, define RDVPs on the relationship, and click Next.

    Learn more in Manage relationship-derived virtual properties (RDVPs).

  5. Define additional relationship settings.

  6. Click Save.

Modify a relationship

You can’t change the cardinality or direction of an existing relationship in the Advanced Identity Cloud admin console. To change these, you must delete the existing relationship and create a new one with the required configuration.

  1. On the Relationships tab, click the relationship you want to modify.

  2. Make your changes in the available tabs:

  3. Click Save.

Delete a relationship

Before deleting a relationship in the UI, remove any existing data that references it. This prevents orphaned relationship data from reappearing later.

  1. Identify objects that currently use the relationship:

    1. Get an access token created with the fr:idm:* scope.

    2. Run a REST API request to query for objects where the relationship property is present:

      Show request

      The following example returns all managed users with the property reports:

      $ curl \
--header "Authorization: Bearer <access-token>" \ (1)
--header "Accept-API-Version: resource=2.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/user?_queryFilter=/reports+pr" (2)
      1 Replace <access-token> with the access token created in step 1a.
      2 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.

      The pr operator means "present", so this query finds all users where the custom property has a value.

  2. Update or remove the data on the existing objects so they no longer reference the relationship.

  3. Run a reconciliation to ensure the data is cleaned up across the system.

  4. On the Relationships tab, click more_horiz for the relationship you want to delete, and select delete Delete.

  5. Click Delete to confirm the deletion.

Relationship property reference

Use the following settings in the Relationship Property page to configure a relationship:

Field, option Description

Property Name

A name for the relationship property. For example, a relationship between users and devices might be named assignedDevices on the user side and deviceOwner on the device side.

Label (optional)

An optional human-readable name for the relationship that appears in the UI.

Description (optional)

An optional description for the relationship.

Display Properties (optional)

Properties to display in the Advanced Identity Cloud admin console when viewing related objects. For example, you might select userName and email for a relationship to users, and deviceName for a relationship to devices.

Notify

Select this checkbox if related managed objects should be notified on modification of the property value.

This is typically used for relationships where the related objects have RDVPs that must stay in sync with changes to the relationship.

Notify Self

Select this checkbox if the managed object type that owns the relationship should be notified on modification.

This is typically used for self-referential relationships, such as a user-to-manager relationship where both sides of the relationship reference the same managed object type.

Relationship settings reference

Use the following settings in the Relationship Settings page to configure the source relationship property of the relationship:

Field, option Description

Validate Relationship

Specifies that a relationship between two object types must be validated when the relationship is created. For example, to indicate that a user can’t reference a role if that role doesn’t exist.

When you create a new custom relationship, validation is disabled by default as it involves an expensive query to the relationship that isn’t always required.

Learn more in Validate relationships between objects.

Relationship Properties (optional)

Specifies properties on the relationship itself. It configures the properties._refProperties.properties on the schema.

Use the add button to add properties to the relationship, and then define the property name and label for each property.