Configure authorization

Authorization is the main interface in Admin Essentials for administering and viewing users, groups, and roles. Your permissions determine which views, features, and interactions are available in the UI.

There are two ways to access Authorization: from the Itential Platform home page, navigate to Admin Essentials → Quick Start → Authorization; or click Authorization in the left sidebar to open the accordion menu.

Terminology

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 lets you assign roles directly to users, and administrators can manage user membership through groups. Users may be members 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 is a combination of permissions granted to all roles assigned to the user and to any groups of which the user is a member.

View and filter users

Because users are accounts from an external system, Itential Platform creates a user record when someone has successfully logged in using their 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 is deactivated.
• Grey: User is not logged in.

Filter the Users table by login status using the popover menu in the top-right. Click the vertical ellipsis (⋮) to display two filter toggles: Show Active Users Only and Show Deactivated Users.

Configure role assignments for users

There are two ways to assign users to Roles: directly, or by group membership.

To assign Roles directly to a user:

Configure group membership for users

The external AAA system manages external group memberships; they can’t be edited in Itential Platform. You can only add or remove users from Itential Platform groups within Authorization.

To change the Groups to which a user belongs:

Forced Logout

Administrators can force users to log out from the Authorization interface. Administrators must have permission for the Authorization.forceLogout method.

Select users using the checkboxes, then click Log Out at the top.

Groups

An Itential Platform Group is an account created within Itential Platform. Users are assigned to Itential Platform groups through Authorization, but are assigned to external groups through the external AAA system. An external group comes from an external AAA system such as LDAP and can’t be created within Itential Platform.

Assign groups to roles

External groups can’t be created within Itential Platform. Itential Platform creates the external group record after learning it from the AAA system.

Groups are assigned to roles in two ways: directly, or by membership in another group.

To assign roles directly to a group in Itential Platform:

Assign group membership

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

Identify group members

Roles

A role is a set of permissions assigned to users and groups that grants access to one or more endpoints. Roles are predefined in the pronghorn.json file for each application and assigned to methods and views with the roles property.

Built-in roles

The following built-in roles come with Itential Platform with ready-to-use permissions and access levels that define what actions users can perform.

Endpoints

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

To view endpoints granted to a role:

Custom roles

In addition to built-in roles, administrators can define custom roles for different authorization strategies. Built-in roles are hard-coded in the services and can’t be edited. Users can only use services from their active server profile and can’t add roles for services that aren’t currently running.

Create a custom role

Edit custom role permissions

Delete a custom role

Only custom roles can be deleted.

Export authorization data

You can export a list of Users, Groups, and Roles from the Authorization interface to a CSV file. Use the CSV as a reference to track user roles and group memberships.

To use this export feature, you must have permissions to read and write roles on users and groups, and permission to perform the export.

Service accounts

The Clients view lists clients for service accounts. Click a client to open its details page, which shows the Client ID and a timestamp for when the client secret was generated. Use the toggle at the top to enable or disable the service account. Disabled service accounts can’t authenticate.

For security, editing a service account client requires the service-accounts:read and service-accounts:write roles. To grant users the ability to edit service account client permissions, enable these roles in the relevant groups.

Applications that need a point of entry to interact with Itential Platform APIs are created as Service Accounts in Itential Platform. Using OAuth2 protocols over HTTPS, authorization policies and controls are applied to limit what the requesting application is permitted to do and for how long. The client ID identifies the service account and the secret key provides proof of right-to-access. The client ID and secret key may be distributed to one or more service applications.

Using service accounts to encapsulate applications provides a more secure connection to external systems, uses tokenization to limit access to user data, protects credentials by sharing a client token ID instead of user credentials, and lets third-party services make requests on behalf of users without accessing passwords or other sensitive information.

Service account properties

Example service account configuration:

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

Service account APIs

Error responses

Create a new client for a service account

1

Open the Create dialog

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

2

Select OAuth Client

Select “OAuth Client” from the dropdown menu list.

3

Enter details

Input a unique client name and a brief description, if desired.

4

Save

Click Save. The Authorization Client Details page opens with the Client Secret visible for copying. A timestamp shows when the secret was generated.

5

Save the secret

A bold message reminds you to save the client secret. If you lose the secret, click Regenerate to create a new one; this invalidates the previous secret.

If you leave the Authorization Client Details page and return later via the Clients Collection view (Admin Essentials → Authorization → Clients), the client secret is no longer visible, only the timestamp.

Edit client permissions for service accounts

1

Open Edit Permissions

From the Clients Authorization Details page, click the Edit Permissions button. The Edit User dialog displays.

2

Assign roles

Select the appropriate user role permissions to assign.

3

Save

Click the Save button to retain your changes.

Enable and disable clients for service accounts

Use the toggle at the top of the Client Details page to enable or disable the service account, then click Save. A message banner confirms the state change. Disabled service accounts can’t authenticate.

View, edit, and delete service accounts

To view all service accounts, select Users from the left navigation menu in Admin Essentials, then click the Service Accounts tab. Click the pencil icon to edit a service account’s permissions.

To delete a client, click its name in the Clients list to open the Client Details page. Click the menu button (⋮) in the upper-right corner and select Delete.

View and modify client metadata for service accounts

From the menu button (⋮) in the upper-right corner of the Client Details view, select Metadata. The metadata drawer shows a Created timestamp and the user who created or last updated the client. Click Close to dismiss.

Use OAuth2 in Postman

After creating a service account client, you can use its client_id and client_secret to authenticate Itential Platform API calls in Postman without a username or password.

There are two ways to set this up: using a pre-request script or using a curl command.

Use a pre-request script

1

Add the pre-request script

In Postman, open the Pre-request Script tab and paste the following script. Replace <platform-host>, <client-id>, and <client-secret> with the values from your service account client.

1
const postRequest = {
2
  url: 'https://<platform-host>:3443/oauth/token',
3
  method: 'POST',
4
  timeout: 0,
5
  header: {
6
    "Content-Type": "application/x-www-form-urlencoded"
7
  },
8
  body: {
9
    mode: 'urlencoded',
10
    urlencoded: [
11
      {key: 'client_id', value: '<client-id>'},
12
      {key: 'client_secret', value: '<client-secret>'},
13
      {key: 'grant_type', value: 'client_credentials'},
14
    ]
15
  }
16
};
17
pm.sendRequest(postRequest, function (err, res) {
18
  var responseJson = res.json();
19
  console.log(responseJson.access_token);
20
  pm.globals.set('authToken', responseJson.access_token);
21
});

2

Set the authorization type

On the Authorization tab, set the Auth Type to Bearer Token and enter {{authToken}} as the token value.

3

Send the request

Send any API request. Postman runs the pre-request script first, retrieves a token, and attaches it automatically to the request.

Use a curl command

1

Import the curl command

In Postman, select Import and paste the following curl command. Replace <platform-host>, <client-id>, and <client-secret> with your values.

$
curl --location 'https://<platform-host>/oauth/token' \
>
--header 'Content-Type: application/x-www-form-urlencoded' \
>
--data-urlencode 'client_id=<client-id>' \
>
--data-urlencode 'client_secret=<client-secret>' \
>
--data-urlencode 'grant_type=client_credentials'

2

Configure the request

Select POST as the method, then go to Body and select x-www-form-urlencoded.

3

Send and verify

Send the request. The response includes a token_type of bearer and an access_token you can use in subsequent API calls.