Managing Users and Groups via REST

Introduction

In nevisAdmin 4, it is possible to restrict access to various functions by defining permissions for users and groups of users. Users and groups can be configured in two ways:

• Via User Management and Group Management features in UI.
• Via the file-based REST API. This is the recommended approach, see below for further information.
• Via the low-level REST API, see Managing Individual Users and Groups via REST.

info

When using Active Directory Integration, users and their group memberships are retrieved from Active Directory. In nevisAdmin 4, you then only have to specify the mapping between Active Directory groups and nevisAdmin 4 groups. This is documented below.

You can manage project- and inventory-level permissions in the GUI, see Editing Project Permissions and Editing Inventory Permissions. There is currently no GUI support for managing users and groups or for setting tenant-level permissions.

User Types

Users in nevisAdmin 4 can be one of these types:

• LDAP users: Users that were created from a successful authentication against an LDAP directory, such as Active Directory.
• Local users: Users that were created via file or via the low-level REST API.
• SAML users: Users that were created from a successful authentication against a SAML IDP, such as Azure Active Directory.

Groups

The purpose of having groups is to manage permissions in an easier way.

Instead of assigning permissions to users individually, it is highly recommended that you assign permissions to groups, and then add the users to the group.

Groups can be used to model roles. As a simple example, create the groups DEVELOPERSand OPERATORS:

• Give the DEVELOPERSpermission to modify projects and deploy to development inventories.
• Give the OPERATORS permission to modify and deploy to production inventories.

Managing Users and Groups via File

Via REST API you can get a file containing all the local users and groups within nevisAdmin 4. With this file you can modify existing groups and users, delete them, create new ones and add or remove permissions to them. The file also eases setting permissions from user and group perspective. Permissions are set by user or group, not by project or inventory.

To manage permissions from project or inventory perspective, see Editing Project Permissions and Inventory Settings Screen.

File Format

The inventory file uses YAML syntax. To get familiar with the YAML syntax, use one of the many tutorials available online.

In YAML, indentation is a crucial part of the syntax and is done with spaces. If tab stops are used, this leads to syntax errors in YAML.

The file is divided into two main sections: localUsers and groups.

File sections

localUsers:
  <user 1>
  <user 2>
  ...

groups:
  <group 1>
  <group 2>
  ...

localUsers

In the example below, you can see how to define a user within the localUserslist:

User example

john:
  email: [email protected]
  givenName: John
  familyName: Doe
  password: mysecretpassword
  globalPermissions:
    - "VIEW_PROJECT"
  tenantPermissions:
    DEV:
      - "MODIFY_PROJECT"
  projectPermissions:
    DEV-SIVEN-MASTER:
      - "ADMIN_PROJECT"
  inventoryPermissions:
    DEV-SIVEN-INVENTORY:
      - "DEPLOY_INVENTORY"

The password of the local admin user cannot be changed using this service. To change the local admin user password, see the chapter Protecting the Default admin Account.

These are the possible attributes that you can define for a user:

• userKey: The identifier of each user in the list john in the example above)
• email: Optional attribute
• givenName: Optional attribute
• familyName: Optional attribute
• password: Only required if you want to create a new user or change the password of an existing user.
• globalPermissions: Optional attribute, only in case of having at least one permission. Contains a list of permissions the user has assigned for the whole application.
• tenantPermissions:Optional attribute, only in case of having at least one permission on a tenant. Contains the tenants (tenant keys) and the list of permissions on each tenant.
• projectPermissions:Optional attribute, only in case of having at least one permission on a tenant. Contains the projects (project keys) and the list of permissions on each project.
• inventoryPermissions:Optional attribute, only in case of having at least one permission on a tenant. Contains the inventories (inventory keys) and the list of permissions on each inventory.

And these are the actions you can perform with the list of users:

• Create user: Adds a new user to the list and uploads the file again. Set the password to the new user to create it successfully.
• Update user: Modifies the values of a user from the list and uploads the file again.
• Change password of user: Adds the password attribute with the value of the new password to an already existing user and uploads the file again.
• Delete user: Removes the whole a user from the list and uploads the file again with the identityDeletionparameter set to true.
• Add permission to user: Adds a permission to a user from the list and uploads the file again.
• Delete permission from user: Removes a permission from a user in the list and uploads the file again.

groups

In the example below, you can see how a group from the groups list should look in the file:

Group example

DEVS:
  description: "Group of developers"
  ldapDNs:
    - "ou=admin4-devs,o=Siven,c=ch"
  localUsers:
    - "john"
  globalPermissions:
    - "VIEW_PROJECT"
    - "VIEW_INVENTORY"
  tenantPermissions:
    DEV:
      - "CREATE_PROJECT"
      - "CREATE_INVENTORY"
  projectPermissions:
    DEV-SIVEN-MASTER:
      - "MODIFY_PROJECT"
  inventoryPermissions:
    DEV-SIVEN-INVENTORY:
      - "DEPLOY_INVENTORY"

These are the possible attributes that you can define for a group:

• groupKey: The identifier of each group in the list (DEVS in the example above).
• description: Optional attribute.
• ldapDNs: Optional attribute. List of LDAP DNs.
• localUsers: Optional attribute, only in case of having at least one user in the group. List of local users in the group (use ldapDNs to add LDAP users to a group).
• globalPermissions: Optional attribute, only in case of having at least one permission. Contains a list of permissions the group has assigned for the whole application.
• tenantPermissions: Optional attribute, only in case of having at least one permission on a tenant. Contains the tenants (tenant keys) and the list of permissions on each tenant.
• projectPermissions: Optional attribute, only in case of having at least one permission on a project. Contains the projects (project keys) and the list of permissions on each project.
• inventoryPermissions: Optional attribute, only in case of having at least one permission on an inventory. Contains the inventories (inventory keys) and the list of permissions on each inventory.

And these are the actions you can perform with the list of groups:

• Create group: Adds new group to the list and uploads the file again.
• Update a group: Modifies the values of a group from the list and uploads the file again.
• Add user to group: Adds a new userKey to the localUserslist of a group list and uploads the file again.
• Delete user from group: Removes a userKey from the localUserslist of a group and uploads the file again.
• Delete group: Removes the whole a group from the list and uploads the file again with the identityDeletionparameter set to true.
• Add permission to group: Adds a permission to a group from the list and uploads the file again.
• Delete permission from group: Removes a permission from a group in the list and uploads the file again.

Permissions Table

The table below lists all operations that are supported by nevisAdmin 4, and the scope for which they are valid (global, tenant, project or inventory).

Operation	Scope	Description
SUPER_ADMIN	Global
CREATE_USER	Global
MODIFY_USER	Global
ADMIN_TENANT	Global, tenant	Distributes permissions of a given tenant to other users.
MODIFY_TENANT	Global, tenant	Creates, updates and deletes tenant (global) constants, secrets and files.
VIEW_SECRET_CONTENT_TENANT	Global, tenant	Views the content of tenant secrets.
CREATE_PROJECT	Global, tenant
CREATE_INVENTORY	Global, tenant
VIEW_PROJECT	Global, tenant, project
MODIFY_PROJECT	Global, tenant, project
ADMIN_PROJECT	Global, tenant, project	Distributes permissions of a given project to other users.
VIEW_INVENTORY	Global, tenant, inventory
MODIFY_INVENTORY	Global, tenant, inventory
ADMIN_INVENTORY	Global, tenant, inventory	Distributes permissions of a given inventory to other users.
DEPLOY_INVENTORY	Global, tenant, inventory
VIEW_SECRET_CONTENT_INVENTORY	Global, tenant, inventory	Views the content of inventory secrets.

Configuring Additional Administrator Users

The default adminaccount has all the permissions from the table above as global permissions. You can grant the same permissions to other users or to a group.

Here is an example configuration snippet for a group called ADMINS, which contains users that are memberOf the LDAP group admin4-admins:

  ADMINS:
    description: "Group of administrators"
    ldapDNs:
      - "ou=admin4-admins,o=Siven,c=ch"
    globalPermissions:
      - "SUPER_ADMIN"
      - "ADMIN_INVENTORY"
      - "ADMIN_PROJECT"
      - "ADMIN_TENANT"
      - "CREATE_INVENTORY"
      - "CREATE_PROJECT"
      - "CREATE_USER"
      - "DEPLOY_INVENTORY"
      - "MODIFY_INVENTORY"
      - "MODIFY_PROJECT"
      - "MODIFY_USER"
      - "VIEW_INVENTORY"
      - "VIEW_PROJECT"
      - "VIEW_SECRET_CONTENT_TENANT"
      - "VIEW_SECRET_CONTENT_INVENTORY"

It is technically possible to delete the default local admin user. We do not recommend this, because the admin user also has an important role in the encryption and decryption of secrets. If you delete it, you might lose access to all of your secrets. Also, this user may be useful in the future to rescue your installation, if, for example LDAP authentication stops working or permissions were set incorrectly.

Instead, we recommend you to completely rely on Active Directory for instructions (LDAP) users and groups for authentication and permissions. If you go that route, you can disable login for users within the local realm. This effectively disables the admin user, but you can quickly re-enable it by turning the local realm back on. See Active Directory Integration for instructions.

Downloading and Uploading the Identities File via REST

Suggested workflow

1. Download the Identities file.
2. Modify the file you just downloaded.
3. After finishing your modifications, upload the file back to nevisAdmin 4.

We recommend that you only edit and upload up-to-date Identities files that you download directly before before working with them. Old files are likely to contain outdated data of users and groups. Uploading such files can cause unwanted changes, for example, user and group data being updated by old values, or permissions getting removed and added incorrectly.

Execute the following steps to work with the file containing the users and groups within nevisAdmin 4:

1. Log in to get the authentication token.

   export NEVISADMIN_URL=http://localhost:9080
   export ADMIN_USER=admin
   export ADMIN_PASSWORD=admin
   # for https, you can add the -k flag to all curl commands to skip certificate verification
   export AUTH_RESPONSE=$(curl -v -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d "{\"userKey\":\"${ADMIN_USER}\",\"password\":\"${ADMIN_PASSWORD}\"}" "$NEVISADMIN_URL/nevisadmin/api/v1/login?tokenType=bearer")
   export TOKEN=$(echo $AUTH_RESPONSE | sed -nE 's/.*"token" : "(.*)" }/\1/p')

2. Download the file.

   curl --header "Accept: text/yaml" --header "Authorization: Bearer $TOKEN" --request GET $NEVISADMIN_URL/nevisadmin/api/v1/identities -o identities.yml

3. Modify the file.

4. Upload the file back to nevisAdmin 4 (change IDENTITY_DELETION to true to allow deletion of users and groups missing in the file):

   export FILE_NAME=identities.yml
   export FILE_PATH=C:/Users/john/Desktop/MyFolder/$FILE_NAME
   export IDENTITY_DELETION=false
   curl --header "Content-Type: multipart/form-data" --header "Authorization: Bearer $TOKEN" --request PUT -F "yamlFile=@$FILE_PATH" $NEVISADMIN_URL/nevisadmin/api/v1/identities?identityDeletion=$IDENTITY_DELETION