Authorization

Authorization is the main interface in Admin Essentials to administer and view users, groups, and roles. Please note that available views, features, and interactions in the UI are limited based on user permissions.

There are two pathways to access Authorization:

• From the Itential Platform home page, you can navigate to Admin Essentials → Quick Start → Authorization.
• Another way is to click Authorization in the left sidebar to open the accordion menu.

Figure 1: Authorization

Terminology

A list of terms related to Itential Platform users, groups, and roles are defined in the following table.

Users

A user is an entity that comes from an external AAA System such as LDAP. All operations within Itential Platform are associated with a user. Itential Platform provides the ability to assign roles directly to users. Also, with Itential Platform groups, administrators are able to manage user membership. Users may be a member of any number of groups and through group membership may be assigned any number of roles.

User roles, whether directly assigned or inherited from a group, determine what the user can see and do within Itential Platform. The final permission set of a user will be a combination of permissions granted to all the roles assigned to the user, or to any groups in which the user is a member.

Viewing & Filtering Users

Because users are accounts from an external system, Itential Platform will create a user record when someone has successfully logged in using the user’s AAA system credentials.

To view the Authorization → Users table, you must have permission for the authorization.getAccounts method. This allows you to access the page, view the list of users, and see their login status.

The indicator circles under the Active column header denote the login status of each user:

●   Blue - User is currently logged in.

●   Red - User who is deactivated.

●   Grey - User who is not logged in.

The Users table can be filtered by login status using the popover menu in the top-right. Click the vertical ellipsis (⋮) to display two filter toggles that:

• Show Active Users Only - Only recently active users are shown in the table.
• Show Deactivated Users - Only deactivated users are shown in the table.

Figure 2: User Status Indicators

Configuring Role Assignments for Users

There are two ways to assign users to Roles:

• Directly
• By groups membership

To assign Roles directly to a user:

1. Locate the user you wish to assign. Alternately, you can filter the user list by typing in the username column header search box.
2. Add or remove role assignments using the checkbox. You can filter the roles list by typing in the Search field.
3. Click Close when done.

Figure 3: User Roles

Configuring Group Membership for Users

External group memberships for users are managed by the external AAA system and cannot be edited in Itential Platform. A user may only be added or removed from Itential Platform Groups within Authorization. Addition or removal of AAA groups must be performed in the AAA system and will be noticed by Itential Platform the next time the user logs in.

To change the Groups to which a user belongs:

1. Click the Groups tab option.
2. Find the group in the list. You can filter the list by typing in the column header textbox.
3. Add or remove group membership using the checkbox.
4. Click Close when done.

Figure 4: User Groups

Forced Logout

Itential allows administrators to forcefully logout all or selected users with from the Authorization interface. Admins must have permission for the Authorization.forceLogout method.

Click the checkboxes to select users and then click the Log Out button icon at the top to forcefully log out all selected users.

Figure 5: Forced Logout

Groups

An Itential Platform Group is an account created within the Itential Platform system. Users are assigned to Itential Platform groups through Authorization. In contrast, users are assigned to external groups within the external AAA system. Users cannot be assigned to external groups using Itential Platform. An external group is an account that comes from an external AAA System such as LDAP. An external group cannot be created within Itential Platform.

Assigning Groups to Roles

External groups cannot be created within Itential Platform. Instead, Itential Platform will create the external group record once it has been learned from the AAA system.

Groups are assigned to roles in two ways:

• Directly
• By membership in another group

To assign roles directly to a group in Itential Platform:

1. Select Authorization → Groups from the navbar on the left. A list of defined groups is displayed.
2. Locate the group you wish to assign to a role. Alternately, you can filter the user list by typing in the Name column header search box.
3. Click the eye icon at the end of the table row to open the View Group dialog. The Roles tab displays by default.
4. In the Edit Group modal, locate the role you wish to assign.
5. Filter the list by typing in the Name or Source search bar.
6. Add or remove a role assignment by selecting the checkbox.
7. Click Close when done.

Figure 6: Group Roles

Assigning Group Membership

Itential Platform groups and external groups can be given membership to an Itential Platform group; however, neither group can be given membership to an external group.

To assign group membership:

1. Select Authorization → Groups from the navbar on the left. A list of defined groups is displayed.
2. Locate the group in the list. You can filter the list by typing in the Search field.
3. Select the group in the list to view by clicking the eye icon at the end of the table row.
4. From the Edit Group modal, select the Groups tab .
5. Add or remove group membership by selecting the checkbox.
6. Click Close when done.

Identifying Group Members

To view group members:

1. Select the Members tab on the Edit Group modal to display the members list of users that are direct members of a group. There is no indicator for inherited memberships.
2. Locate the member username in the list. You can filter the list by typing in the Search bar.
3. Click Close when done.

Roles

A role is a bundle of permissions assigned to users and groups, granting permission to access one or more endpoints. Roles are pre-defined in the pronghorn.json file for each application and assigned to methods and views with the roles property.

Built-In Roles

The following list of built-in roles come with Itential Platform, and offer a set of ready-to-use permissions and access levels that pre-define what actions users can perform within the Platform.

Endpoints

Endpoints are defined by each application in the Platform. There are essentially two types of endpoints:

Since the Platform comes with several built-in roles that offer a set of ready-to-use permissions and access levels, a role may be assigned to any number of users or groups to provide access to the endpoints granted to that role.

To view endpoints granted to a role:

1. Select Roles from the left-side navigation menu. A table list displays. There is a role for each application installed in the system.
2. Optionally, type in the search bar to sort/filter by role, application associated with the role, or by description.
3. Click the view icon for your desired role to open the View Role modal, which shows all the API Methods and UI Views for a role. You can sort and filter using the Method and Source fields.

Figure 7: View Role API Methods

Figure 8: View Role UI Views

Custom Roles

In addition to built-in roles defined by applications, Itential Platform 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 Itential Platform) 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.

Creating Custom Roles

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, and then 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 9: Create Custom Role

Figure 10: Assign Custom Role API Endpoints and UI Views

Editing Custom Role Permissions

To edit custom role 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 11: Edit Custom Role

Deleting a Custom Role

As with other custom 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 the custom role has been deleted from the Roles table view.

Exporting Authorization Data

Customers have the ability to export a list of Users, Groups, and Roles from the Authorization interface into a CSV-formatted file, which can be named and saved to a download folder on your system. The CSV data, in turn, can be used as a reference list (data report) to help track what role a user belongs to and see the groups to which each user belongs.

To utilize this export feature you:

• Must have assigned permissions to read/write roles on user and group entities.
• Must have assigned permissions to perform the export.

To export your authorization data:

1. Navigate to Admin Essentials → Authorization.
2. Click the export icon. A confirmation dialog displays.
3. Click the Download button. A copy of a CSV-formatted file is downloaded to your system.
4. Go to the location where the CSV file is saved.
5. Open the CSV file in your spreadsheet application of choice (e.g., Microsoft Excel, Google Sheets, Smartsheet, etc). In our example, Microsoft Excel is used.

Figure 12: Export Authorization Data

Figure 13: Authorization Data File

The items in the CSV file and what they represent are reference below.

Authorization Clients

The Authorization Clients view displays a list of clients for Service Accounts. Click on the Clients name in the list to open the Client Details page, which displays the Client ID and a timestamp identifying the date and time a Client Secret was generated. Use the toggle switch located at the top to enable (turn on) or disable (turn off) the Service Account. Authentication is not permitted against disabled Service Accounts.

For security reasons, the ability to edit a Service Account client is protected by the service-accounts:read and service-accounts:write Cloud application roles. To grant a user the right to edit client permissions for a Service Account, you must enable these roles in the groups whose users need to create or modify Service Accounts.

Figure 14: Authorization Clients

Figure 15: Client Details

Service Accounts

Applications that need a point of entry to interact with Itential Platform APIs in order to perform tasks are created as Service Accounts in Itential Platform. Using OAuth2 protocols that work over HTTPS to send a client token ID and secret key, authorization policies and controls are applied to limit what the requesting application is permitted to do and for how long. The client ID is used to identify the Service Account and the secret key is used to provide proof of right-to-access. Most notably, the client ID and secret key associated with a Service Account may be distributed to one or more Service Applications.

There are several benefits to encapsulating applications as Service Accounts in Itential Platform. This functionality:

• Provides a more secure way to connect Itential Platform to external systems via one set of login information.
• Uses tokenization to give limited access to user data across applications and devices.
• Protects user data by providing access via client token ID without revealing user credentials.
• Allows third-party services to make requests on behalf of a user without accessing passwords and other sensitive information.

Service Account Properties

Service account properties and a sample configuration are referenced below.

Example Service Account Configuration

"accountData" : {
  "name": "Service Account Hello",
  "description": "This is a service account",
  "client_id": "638e17011ba61d5e222a16ab",
  "client_secret": "94367284-b12a-4858-b6c1-0bb11f1f126b",
  "grant_type": "xxxxx.yyyyy.zzzzz"
}

Service Account APIs

Listed below are the four CRUD APIs with admin-level permissions used to support and manage service accounts.

Error Responses

The codes below indicate whether the HTTP request for a service account has been successfully executed or not.

Creating a New Client for a Service Account

To create a new client for a service account in Admin Essentials:

1. Click the + sign on the toolbar to open the global Create dialog.

2. Select "OAuth Client" from the dropdown menu list.

3. Input a unique client name and a brief description, if desired (Figure 1)

   Figure 16: Create New Client
   

4. Click the Save button. The Authorization Client Details page displays with the Client Secret visible so the adminisrator can copy it to clipboard. A timestamp identifying the date and time the Client Secret was generated is also displayed (Figure 2).

   Figure 17: Client Details and Client Secret
   

5. A message to save the client secret displays in bold beneath the timestamp. If the secret is lost, use the Regenerate button to create a new one and invalidate the old one (Figure 3).

   Figure 18: Regenerate Client Secret
   

6. If a user leaves the Authorization Client Details page and later returns via the Clients Collection view (Admin Essentials → Authorization → Clients), they will not be able to see the client secret (Figure 4). They will, however, see the client secret timestamp.

   Figure 19: Client Secret Masked
   

Editing Client Permissions for Service Accounts

From the Clients Authorization Details page:

1. Click the Edit Permissions button (Figure 5). The Edit User dialog displays.

   Figure 20: Edit Permissions
   

2. Select the appropriate user role permissions to assign (Figure 6).

3. Click the Save button to retain your changes.

   Figure 21: Edit Client User Role Permissions
   

Enable/Disable Clients for Service Accounts

Use the toggle switch located at the top of the Client Details page to enable (turn on) or disable (turn off) the Service Account. Click the Save button to retain your changes. A message banner displays to inform users when the enable/disable state is activated for the Service Account. Authentication is not permitted against disabled Service Accounts.

Figure 22: Enable (Toggle On) Service Account Client

Figure 23: Disable (Toggle Off) Service Account Client

Viewing, Editing & Deleting Service Accounts

To view all Service Accounts on the system, select Users from the left navigation menu in Admin Essentials and then click the Service Accounts tab. From this table view, you can also click the pencil icon to edit the permissions associated with a Service Account.

Figure 24: Service Accounts Tab

To delete a client associated with a Service Account, click on the Clients name in the list to open the Client Details page (Figure 10). Next, clicked the menu button (⋮) in the upper-right corner of the page to open the menu dialog (Figure 11). Select the Delete option to remove the client.

Figure 25: Authorization Clients List

Figure 26: Client Menu Button

Viewing & Modifying Client Metadata for Service Accounts

From the menu button (⋮) in the upper-right corner of the Client Details view, select the Metadata option (Figure 11). In the metadata drawer that opens, you will see a Created field with a date timestamp and the user that created/updated the client. Click the Close button to remove the current window from the screen (Figure 12).

Figure 27: Client Metadata