--- title: Adding a custom administrator role description: Use the Administrator Roles page to add custom roles to the environment. component: pingone page_id: pingone:directory:p1_custom_role_add canonical_url: https://docs.pingidentity.com/pingone/directory/p1_custom_role_add.html section_ids: before-you-begin: Before you begin steps: Steps result: Result --- # 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. | | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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](_images/p1-custom-role-add-assign-perms.png) 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.](_images/p1-custom-role-search-perms-identifier.png) Learn more about the identifiers for permissions in [PingOne Permissions by Identifier](https://developer.pingidentity.com/pingone-api/platform/reference/roles-and-permissions-in-pingone/pingone-permissions-by-identifier.html) in the PingOne 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.](_images/p1-missing-permission-message.png) * 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.](_images/p1-custom-roles-filter-to-find-perm.png) 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.](_images/p1-custom-role-filter-results.png) 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.