PingOne

Adding a custom administrator role

Use the Administrator Roles page to add custom roles to the environment.

Before you begin

You must have one of the following roles to create a custom role:

  • Organization Admin

  • Custom Roles Admin

  • A custom role with permissions equivalent to the Custom Roles Admin

Steps

  1. In the sidebar, click the Ping Identity logo to open the Environments page.

  2. Click the environment in which you want to add the new custom role and click Manage Environment.

  3. Go to Directory > Administrator Roles and click the Custom Roles tab.

  4. Click Add Custom Role.

    If you are creating this role outside of the Administrators environment, the role can be assigned only against resources within this environment or to the entire environment.

  5. From Initial Permissions, select a basis for the new role.

    • Permissions Sets

      • No Permissions: Start building a new role without any permissions included.

      • Essential Permissions: Start building a new role with the minimum set of permissions needed for the role to be usable.

    • Roles

      Select an existing role to use as the basis for the new role. Permissions included in the role are added to the new role. You can add or remove permissions as needed in the following steps. You can use a built-in role or custom role as the basis for a new role.

      You can use only roles that are assigned to you or that confer the permissions needed to assign that role to others.

      Best Practice: Use an existing role as the basis for the new role, then remove the permissions you don’t want the new role to have and add other permissions as needed. If you build a role without any starting permissions, users with that role could have issues accessing required functionality in the admin console. In some cases, the admin console might not load properly.

  6. Enter a Name for the new role.

    The role name must be unique within the environment.

  7. (Optional) Enter a Description for the new role.

    Best Practice: Enter information about the intended use of the role in your description.

  8. In Assignable by, select the roles that are allowed to assign this role to others.

  9. In the Advanced section, you can restrict the role assignment so that it can only be assigned at a particular level.

    For example, if you want a role to be assigned only to manage individual populations in an environment but not the entire environment, select Population.

    If you are creating this role in any environment other than the Administrators environment, you cannot enable the role to be assigned at the Organization level.

  10. Click Next.

  11. Add or remove permissions as needed.

    Leave Automatically include essential permissions (recommended) selected to ensure that your role has the minimum permissions needed to function properly.
    alt A screenshot of the Assign Permissions page with the Organization category expanded

    The Selected Permissions tab lists the permissions that are currently selected for the role. The number in the tab header tells you how many permissions are currently associated with the role. The previous image shows a role with 335 permissions.

    There are several ways to locate permissions you want to add to or remove from the role:

    • Using the Categories list: In the left pane, permissions are organized under top-level categories that mirror the sidebar navigation pane in PingOne. Expand a top-level category to view the related categories and locate the permissions you want to add or remove from this role.

      The first number next to the category name indicates how many permissions in that sub-category are selected for inclusion in the role. The second number indicates the total number of permissions in that category. For example, in the previous screenshot, the current role configuration includes three of the permissions in the Environment category, and that category contains five permissions total. Click a category to view the permissions included in the category, including the permission name and a detailed description of what actions the permission allows the bearer to perform in PingOne.

    • Using the Search functionality: The search looks for your criteria in the permission name or detailed description.

      You can also search for a permission using the permission identifier, for example dir:read:group. The identifier is a three-part, colon-delimited string that represents the category, action, and resource to which the permission applies. For the previously mentioned identifier, dir represents the Directory category, read is the action, and group is the resource.

      alt Screenshot of the dir:read:group permission identifier in the search field of the Edit Permissions page with the Read Group permission in the search results.

      Learn more about the identifiers for permissions in PingOne Permissions by Identifier in the API documentation.

      The string identifier is also used when a user tries to access an environment resource in PingOne, but does not have the appropriate permissions for access. A message uses the string identifier to indicate that they are missing a necessary permission. That string can be sent to an administrator to search for and update the user’s permissions if needed.
      A screenshot of the Users details pane with the Groups tab selected and a message displayed indicating that you can’t view the page because you are missing a permission.

    • Using the Filter: Click the Filter icon to find permissions based on the level at which they apply or the actions they permit.

      alt A screenshot of the permissions filter.

      For example, select Population and Delete to find all permissions that can be applied at the population level and that allow the bearer to delete resources.

      alt A screenshot showing permissions found when selecting Population and Delete from the Filter box.

      Badges below the Search box indicate the filters that are selected. Click the X on a badge to remove the filter condition. Click Clear All to remove all conditions.

    • Using a combination of the search functionality and the filters.

    To find a permission that you want to remove from the role, perform searches and filtering on the Selected Permissions tab. To find a permission you want to add, perform searches and filtering on the All Permissions tab.

  12. Click Next.

    If you included privileged permissions in the role, you are prompted to confirm that you want to include them. Click Continue to include them, or click Cancel to go back and remove them from the role.

    Privileged permissions should be selected sparingly and only after careful consideration of the potential impact.

  13. Review the role on the next page and click Save.

Result

The role is added to the Custom Roles tab on the Administrator Roles page and can now be assigned to users, groups, applications, or connections.