Roles

A role is a bundle of permissions assigned to users and/or groups. Roles are pre-defined in the pronghorn.json file for each application and assigned to methods/tasks and views with the roles property. Custom roles can be created within your installation by navigating to Authorization > Roles.

Built-In Roles

The following is a list of built-in roles within IAP.

• admin
• apiread
• apiwrite
• support
• operations/operator
• engineering
• taskread
• taskwrite
• authorization
• read-only

Endpoints

A role grants permission to access one or more endpoints. Endpoints are defined by the applications and IAP. There are essentially two types of endpoints.

A role may be assigned to any number of users or groups. This provides access to all endpoints granted to the role. The final permission set for a user is a combination of permissions granted to all the roles assigned to a user, or to any groups in which the user is a member.

Managing Roles

In addition to built-in roles defined by applications, IAP allows administrators to define custom roles for an installation to allow for different authorization strategies. Built-in roles are hard coded in the services (or in IAP) and are not user-editable. Users can only utilize services from their active server profile, and cannot add roles for services that are currently not running.

To manage roles within IAP:

1. Login to IAP as an administrator (a user with the Pronghorn.admin Role).
2. Navigate to Admin Essentials > Quick Start > Authorization.
3. Select the Roles menu option. A table list displays. There is a role for each application installed in the system.
4. Click the View icon to open a role and show an advanced view.
   • You can view all API Methods (endpoints) and UI Views for a role.
   • You can filter and/or sort using the Method and Source fields.

Figure 1: Authorization Roles

Figure 2: View Role

Configuring Role Assignments

Groups are assigned to roles in two ways:

• Directly.
• By membership in another group.

To assign roles directly to a group in IAP:

1. In the left-side navigation panel, select Groups.
2. Select a group to open it for viewing or editing.
3. In the Edit Group modal, locate the role you wish to assign.
4. Filter the list by typing in the Name or Source text field.
5. Add or remove a role assignment by selecting the checkbox.

Roles which are assigned by other groups are grayed out (disabled). This indicates the assignment is inherited.

Inspecting a Built-In Role

To inspect a built-in role:

1. In the left-side navigation panel, select Roles.
2. Optionally, type in the search box to sort/filter a role.
3. Click the View icon next to a role to open the View Role modal and show the list of all endpoints granted to the role.

Creating a Custom Role

Use a unique name when creating a custom role.

1. Click the plus (+) sign from the top toolbar in Admin Essentials to open the Create dialog.
2. Select Role from the dropdown menu.
3. Give the new custom role a name (required).
4. Give the new custom role a description (optional).
5. Select the appropriate API endpoints and UI Views in the Edit Role modal. Refer to Managing Custom Role Permissions below.
6. Click Save to finalize your changes. The custom role appears in the Authorization: Roles table view and will display as Custom under the Type column.

Figure 3: Create Custom Role

Figure 4: Assign Custom Role API Endpoints and UI Views

Managing Custom Role Permissions

To manage and edit custom roles permissions:

1. Select Roles from the menu in the left navbar.
2. Type the name of the Custom role in the search bar under the Role column header.
3. Select the desired role from the results list.
4. Click the stacked dots menu icon and select Edit. The endpoints for the selected custom role will display in the Edit Role modal, with tabs for API Methods and UI Views, respectively.
5. Update the role name, if needed.
6. Update the role description, if needed.
7. Locate the permissions you would like to grant or remove.
   • Filter the list by typing in the search box.
   • Add or remove permitted endpoints by selecting the checkbox.
8. Click Save to finalize your changes.

Figure 10: Edit Custom Role

Deleting a Custom Role

⚠ Caution: This is a hard delete. Deleting a custom role will remove references to the role from all users and groups assigned to it.

As with any other modifications, only custom roles may be deleted.

1. Locate the custom role you wish to delete. Filter the list using the filter fields in the column header.
2. Click the stacked dots menu icon and click Delete for the role.
3. Confirm the deletion.

Custom Applications and Built-In Roles

Built-in application roles along with endpoints are defined in the pronghorn.json file. The following excerpt from a pronghorn.json file is provided as an example.

{
    "roles": [
        "admin",
        "engineering",
        "support",
        "apiread",
        "authorization"
    ],
    "methods": [
        {
            "name": "getTasksList",
            "roles": [
                "admin",
                "engineering",
                "support"
            ]
        }
    ],
    "views": [
        {
            "path": "/edit",
            "roles": [
                "admin",
                "engineering"
            ]
        }
    ]
}

In the preceding example, five (5) built-in roles were defined. The getTasksList method is granted to three of them. In contrast, the /edit view is granted to only two.

The declarations will be ingested at application load time and cached in the IAP database to assist with various queries. At application load time, the roles that are cached for the application will be replaced with the roles and permissions defined in pronghorn.json.

If pronghorn.json is inconsistent in its role names, warnings will appear in the IAP logs at application load time.

Note: If an application is upgraded and the new version no longer declares a role, it will be deleted and references to it will be removed from all users and groups. Additionally, role names are the identifier for application roles. Renaming a role is effectively the same as deleting it and declaring a new one. In each case, some users may lose access to your application. Therefore, removal or renaming of existing roles is considered a breaking change.