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 the file-based REST API. This is the recommended approach, see below for further information.
• Via the low-level REST API, see Managing In

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. 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 of two types: ldapor local.

• 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.

Groups

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

Instead of assigning permissions to users in

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

• Give the DEVELOPERS permission 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]

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

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 localUsers list:

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 local admin user's password 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:

• email:

• givenName:

• familyName:

• password:

• globalPermissions:

• tenantPermissions:

• projectPermissions:

• inventoryPermissions:

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 identityDeletion parameter 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 groupslist 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:

• description:

• ldapDNs:

• localUsers:

• globalPermissions:

• tenantPermissions:

• projectPermissions:

• inventoryPermissions:

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 localUsers list of a group list and uploads the file again.
• Delete user from group: Removes a userKey from the localUsers list 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 identityDeletion parameter 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
ADMIN_TENANT	Global, tenant	Distributes permissions of a given tenant to other users.
MODIFY_TENANT	Global, tenant	Creates, updates and deletes tenant 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"
    - "DEPLOY_INVENTORY"
    - "MODIFY_INVENTORY"
    - "MODIFY_PROJECT"
    - "VIEW_INVENTORY"
    - "VIEW_PROJECT"

It is technically possible to delete the default local admin user. We do not recommend this, because this user may be useful in the future to 'rescue' your installation, for example if LDAP authentication stops working or if, for some reason, permissions were wrongly set.

Instead, we recommend you to completely rely on Active Directory for instructions.

Downloading and Uploading the File via REST

Suggested workflow

1. Download the file.
2. Modify the just downloaded file.
3. Immediately after finishing your modifications, upload the file back to nevisAdmin 4.

To prevent losing any user or group data, working this way is highly recommended. Old files will most probably contain outdated data of users and groups. Therefore, uploading such a file will end up in unwanted changes (for example, user and group data updated by old values, or permissions removed and added wrongly). If you follow the suggested workflow, you apply your changes to a recently downloaded version of the file. This will prevent such unintended changes.

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.

Preparation: Login to get 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.

Get users and groups 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):

Upload users and groups 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