# Managing Users, Groups, Roles, Permission Sets, Permissions, and Advanced Options

In Avantra access control is implemented by means of Permissions contained in Roles which link Users or Groups of Users to Customers, or by means of Permissions contained in Permission Sets assigned to a User directly linked to a Customer.

## Users, Roles, Permission Sets, and Groups

A User in Avantra is basically an account to access the application with a little bit of information attached to it. You may store personal information, like address, phone number, e-mail address, etc. The most important of these attributes is probably the password.

Once you have created a User it is almost worthless, because by default it has no Permission assigned. It can log in to Avantra WebUI, but it can only see its own profile, and log out again.

In order to have a starting point, there are a few Users built-in already, and these Users do have Permissions (by means of assigned built-in Roles).

The purpose of Roles is to link one or more (or even all) of the Permissions available within Avantra (which are listed in Users) on the one hand, and to one or more (or even all) Customers on the other hand.

List of Avantra built-in Users:

Application Root User

  You have created this account during the installation.

  This account has all Permissions (for all Customers) within the Avantra application. The Permissions are defined in the `Super Administrator Role`. This Role cannot be removed from the Application Root User, and the User can neither be modified, locked, or deleted. Also, compliance with the password policy is not verified for this User!

  | We strongly recommend not to use this account for your daily business. Instead, you may create a new User and assign the `Administrator Role`.

unassigned, messenger

  Only used internally in case a Ticket or a Change does not yet have an owner, or a Ticket has been created through a Notification Action.

You are not able to select or modify these Users but you may come across them in Ticket or Change pages.

As mentioned earlier, there are also built-in Roles.

List of Avantra built-in Roles:

Administrator Role

  The `Administrator Role` basically contains all Permissions available in Avantra (as listed in Permissions) except for Receive Notification Messages.

  The `Administrator Role` can be modified or even deleted, and you can add or remove Permissions.

  Also, this role is linked to all Customers, i.e. it is effective automatically for any newly created Customer.

Super Administrator Role

  Contains the same Permissions as the `Administrator Role` but is tightly linked with the User Application Root User, cannot be assigned to any other User, nor can it be modified, duplicated, deleted, etc.

Default Messenger Notification Role

  You should consider this Role as a template for creating your own Roles, in other words, if you want to use it, please duplicate it and change the name accordingly.

  This Role contains the only Permission Receive Notification Messages to allow receiving email Notifications.

There is also a built-in Permission Set:

Customer Representative

  This Permission Set is automatically created once a User is assigned to a Customer, and it is removed automatically once the User is no longer assigned to the Customer.

  A User can only represent one(!) Customer, therefore the Permissions defined in this Permission Set are linked only to the represented Customer.

  The default set of Permissions is View RTM, View Daily Checks, View Availabilities, View Tickets, Call Tickets, View Changes, View Customers, View Systems, View SLRs, and View SLA, i.e. by default a Customer representative has only basic Permissions.

  This Permission Set can not be modified or deleted, but the set of Permissions included can be modified.

It is probably most straightforward to think of Groups as Groups of Users (while you could also think of them as Groups of Roles). Instead of assigning multiple Users to a Role you could also create a Group containing the Users and link this Group to a Role.

Groups may save you some configuration work if you have defined a significant number of Users. If your business is an enterprise or a large Service Provider, you probably have an immediate understanding of how to map your organizational structure to Groups and Roles. You perhaps want to Group all the staff having administrative Permissions.

### Managing Users

| Any actions that change the Permissions of a User, like assigning Roles, Permission Sets, or Groups, as well as changing passwords or locking Users, are only effective if the User logs in next time. But you can log out a User immediately (and by this to force him to log in) as described in section Logout a User or all Users.

### Changing Your Own Password

Select Change Password from the header. Enter the old and new passwords, and push OK.

### Creating a User

Perform the following steps to create a new User:

Procedure: Creating a User

1. Choose Administration User Management from the top-level menu and push the New button.

2. Fill in the User ID, Password, First Name, Last Name, and select a Timezone from the drop-down list. Push the Create button.

3. If the User is supposed to receive email Notifications, you probably want to fill in an Email address as well.

4. You can set the Disable Notifications flag in order to avoid receiving Notification emails even if the User is permitted to.

5. If you have made any changes push the Apply button.

In order to create a User, you need the Edit Users Permission.

Only the user with Administrator Role has permission to change the User ID in Avantra WebUI.

### Changing a User’s Password

Perform the following steps to change a User's password:

1. Choose Administration User Management from the top-level menu, select the desired entry from the list, and push the Open button.

2. Push the Change Password button.

3. Fill in the New Password and Push the Change button.

In order to change a User password, you need the Edit Users Permission.

In order to change your own password, please proceed as described in Changing Your Own Password.

### Assigning/Un-assigning a Customer to a User

Assigning a User to a Customer means to make the User a Customer representative. You can then only assign Permission Sets instead of Roles.

A User without Customer assignment usually represents a Service Provider, or it is supposed to to represent more than one Customer.

1. Choose Administration User Management from the top-level menu, select the desired entry or entries from the list (on the Users tab), and choose more Assign Customer.

2. Select the Customer from the list. To unassign choose `---`. Push the OK button.

In order to assign/unassign a Customer, you need the Edit Users Permission.

### Locking/Unlocking a User

You can lock a User in order to prevent him from accessing Avantra WebUI.

In order to lock or unlock a User, perform the following steps:

1. Choose Administration User Management from the top-level menu, select the desired entry or entries from the list (on the Users tab), and push the Lock/Unlock User button.

2. Select Edit Lock/Unlock from the page menu.

3. In order to lock a User, flag the Lock check box and fill in the Lock Reason field. In order to unlock a User, clear the Lock check box and clear the Lock Reason field.

4. Push the OK button

In order to lock/unlock a User, you need the Edit Users Permission.

### Editing User Groups

See the Groups section.

In order to add a User to a Group or to remove a User from a Group you may perform the following steps:

1. Select Administration User Management from the top-level menu. Select the Users tab (if not selected). Open the desired User from the list.

2. Switch to the Membership tab and push the Assign Groups button.

3. Choose one or more Groups and move them to the right frame using the (and ) icons.

4. Push the OK button.

In order to modify the Group assignments of a User, you need the Edit Users Permission.

### Editing User Roles

| If the User is linked to a Customer you need to assign Permission Sets instead, see Editing Permission Sets.

See section Roles.

To link a User to a Role or to unlink a User from a Role, you may perform the following steps:

1. Select Administration User Management from the top-level menu. Select the Users tab (if not selected). Select the desired Users from the list.

2. choose More Assign Roles

3. Choose one or more Roles and move them to the right frame using the (and ) icons.

4. Push the OK button.

In order to modify the Role assignments of a User, you need the Edit Users Permission.

### Editing Permission Sets

See section Permission Sets.

In order to link Users to a Permission Set or to unlink a User from a Permission Set, perform the following steps:

1. Select Administration User Management from the top-level menu. Select the Users tab (if not selected). Select the desired Users and push Open.

2. Switch to the Membership tab and push Assign Permission Set.

3. Choose one or more Permission Sets; and move them to the right frame using the (and ) icons.

4. Push the OK button.

In order to modify the Role assignments of a User, you need the Edit Users Permission.

### Deleting a User

In order to delete a User, perform the following steps:

1. Select Administration User Management from the top-level menu. Select the Users tab (if not selected). Select the desired Users.

2. Push the Delete button. A warning message pops up.

3. Push the Yes button if you are really sure to delete the User.

In order to delete a User you need the Edit Users Permission.

| Users cannot be deleted if they own Solution Documents, Service Level Reports templates or jobs, or shared Dashboards. In this case, you need to reassign these objects to another user before. If a user is deleted, the following information is deleted as well: Information on the administrator user or the deputy of monitored objects, for example, SAP Systems and Servers Information on the user of Notification output channels The following information is reset to the built-in User unassigned: Changes The confirm user of Daily Checks, RealTime Monitoring Checks, and its history

### Viewing All Permissions of a User

This option allows you to see all Permissions a User has per Customer on a single page:

1. Choose Administration User Management from the top-level menu, select the desired entry from the list, and push the Open button.

2. Switch to the Permissions tab.

Please note that processing this list can take some time for Users having the `Administrator Role` assigned.

### Logout a User or all Users

This option allows you to force a logout of a given User. Such an action may be required to enforce a Permission change while the User is logged on. Probably it is more appropriate to ask the User to log out and log in himself.

You can also select to log out all Users except yourself.

1. Select Administration User Management from the top-level menu. Select the Groups tab. Choose More Show Logged on Users.

2. Choose the desired entries and push Force Logout.

In order to log out Users, you need the Edit Users Permission.

### Using Client Certificates for Login

See Using Client Certificates for Login for a description.

### Using an API key for login

You can create an API key in the User profile to authenticate against GraphQL APIs without supplying a password or using a SAML/directory login.

This API key can be used instead of the password in communicating with the Avantra API. Also, it gives access to the resources (which you have permission for) to create automations/connections in Avantra. It is convenient for SAML users configured to have access to an Avantra Server.

This feature is only available in the Enterprise Edition.

## Managing Roles

### Creating a Role

Perform the following steps in order to create a new Role:

1. Select Administration User Management from the top-level menu. Click New on the Roles tab.

2. Fill in the Name of the Role and push the Create button.

3. Open the recently created Role.

4. Enter a brief Description of the Role.

5. Push the Assign Customers button in order to select the Customers you want to link the Permissions to.

6. Switch to the Permissions tab. Push Assign in order to choose the Permissions included in this Role.

7. Push Apply.

Up to now, this Role is only an empty container. You have to link it with Users (and/or Groups), add Permissions to it, and also link it to Customers. If you link to the Customer Root, the permissions of the role will be applied to all customers, including newly created ones.

You need the Edit Roles Permission to perform this action.

### Editing Role Users

See Editing User Roles.

### Copy a Role

The Copy function is provided just for your convenience. If you have an existing Role with, for example, a well-defined set of Permissions, and you want the same set of Permissions to be assigned to a different combination of Users and Customers, you can simply duplicate the Role, change its name, and modify the User and Customer assignment.

Perform the following steps in order to duplicate a Role:

1. Select Administration User Management from the top-level menu. Select the Roles tab.

2. choose More Copy.

3. Enter a new Name and push Copy.

4. You probably want to change the Users and Customers assigned to the Role, or even the Permissions.

You need the Edit Roles Permission to perform this action.

### Delete a Role

Perform the following steps in order to delete a Role:

1. Select Administration User Management from the top-level menu. Select the Roles tab.

2. Choose the desired entry and push Delete.

You need the Edit Roles Permission to perform this action.

## Managing Permission Sets

### Creating a Permission Set

Perform the following steps in order to create a new Permission Set:

1. Select Administration User Management from the top-level menu. Click New on the Permission Sets tab.

2. Fill in the Name of the Permission Set, and optional Description and choose a Customer.

   | This field does not link any Permissions to the selected Customer. It defines only Users having the Permission Edit Roles for this Customer are allowed to modify the Permission Set record, and only Users having the Permission View Roles for this Customer are allowed to view the Permission Set record.

   Push the Create button.

3. Open the recently created Permission Set.

4. Switch to the Permissions tab. Push Assign in order to choose the Permissions included in this Permission Set.

5. Push Apply.

You need the Edit Roles Permission to perform this action.

### Delete a Permission Set

Perform the following steps in order to delete a Permission Set:

1. Select Administration User Management from the top-level menu. Select the Permission Sets tab.

2. Choose the desired entry and push Delete.

You need the Edit Roles Permission to perform this action.

## Managing Groups

Managing Groups is very similar to the management of Users and Roles

You need the Edit Groups Permission for Group management.

### Creating a Group

Procedure: Creating an empty Group

1. Select Administration User Management from the top-level menu. Click New on the Groups tab.

2. Fill in the Name and optionally a Description of the Group.

3. Push the Create button.

4. Switch to the Users and Roles tab. Push Assign Users and Assign Roles in order to assign Users and Roles.

### Deleting a Group

1. Select Administration User Management from the top-level menu. Select the Groups tab.

2. Choose the desired entry and push Delete.

## Defining a Password Policy

Avantra allows you to force your Users to define passwords of a certain strength, as well as to change their passwords on a regular basis.

For this purpose, you can define that passwords

- have to be at least of a certain length (min 12 characters) or

- expire after a defined number of days or

- have to be different from the previous password or

- must contain at least one lowercase letter

- must contain at least one uppercase letter

- must contain at least one numerical character or

- must contain at least one special character (i.e. `! " # $ % & ' ( ) * @ + , - . / : ; < > ? [ \ ] ^ _ ` { | } ~`) or

- must not contain the user ID or

- must not contain the user’s first, middle, or last name or

- must not contain more than two sequential characters, e.g., `YYY`

- can only be changed by an authorized User (i.e., Users cannot change their own passwords) or

- any combination of the above.

By default, Avantra requires passwords to have a minimum length of 12 characters. However, you can choose to increase this, but you cannot set a shorter length.

When a user needs to change their password, the new password is checked against a list of commonly used passwords to exclude easily compromised variants. Also Avantra custom vocabulary is added to the dictionary (e.g., passwords cannot contain the word 'avantra')

| To enable the password check, tick the correspondent checkbox in the password policy parameters

In order to activate the password policy, you need the Edit Customizing Permission. Please perform the following steps:

1. Select Administration Settings from the top-level menu and switch to the Customizing tab.

2. Set flags to (or remove from) the check boxes of the policy that is appropriate for you. Fill in values in the fields (if applicable).

3. Push Apply.

Once you have changed the policy, there may be Users with passwords that do not comply with the new policy. When these Users log in, they still can use their old password. Once they have logged in they get a 1 day grace period and are requested to adapt the password to the current policy (there is a corresponding message in the status area). If they refuse to do so, they are no longer able to log in once the expiration date has passed.

If password expiration is activated, Users will be notified in the status area to change their passwords, starting nine days in advance. If they refuse to do so, they are no longer able to log in once the expiration date has passed.

## Advanced User Management Options

Avantra WebUI allows you to use external services for user management. Microsoft Active Directory and the SAML 2.0 (Security Assertion Markup Language 2.0) are supported.

The following features are supported:

- Authentication including optional automatic user creation

- Authorization, i.e. mapping AD groups or SAML attributes to Avantra roles and groups

More information can be found in the following two Avantra knowledge base documents:

- Active Directory Integration

- SAML Integration

### Working with Active Directory

Procedure: Configure Active Directory Server

1. Select Administration User Management from the top-level menu. Select the External User Directory tab.

2. Activate the check box Enable Active Directory.

3. Enter the name of your AD domain, for example, `company.com`.

4. Enable the Auto detect AD Server check box to let Avantra WebUI automatically detect the AD server, which is recommended. If you enable this option, the Active Directory Host and Port fields will be disabled. When you click on Test Connection, Avantra WebUI will show you the auto-detected host.

   In case auto-detection does not work, fill in the Active Directory Host and Port fields. You can leave the field Port blank to use the default port.

5. Enable Use LDAPS (recommended) which is highly recommended. This makes sure that no credentials will be sent in clear text.

6. For testing purposes, you might need to ignore SSL certificate errors, for example, if the CA cannot be found in Avantra WebUI’s Java keystore. For production environments, it is recommended to not check the Ignore SSL Certificate issues and instead fix possible SSL issues.

   Possible own CA certificates must be added to the file `<your-jre>/lib/security/cacerts` and Avantra WebUI must be restarted. This can be done with the following commands:

       cd <bin-dir-of-your-jdk>
       keytool -list -keystore cacerts
       keytool -keystore cacerts -importcert -alias <yourCAAlias> -file <your-certificate.cer>
       keytool -list -keystore cacerts

7. Avantra tries to detect the Base DN (also called naming context). If Avantra is not able to determine the correct base DN, you can specify it here.

8. Use the Test Connection to test the connection to your Active Directory.

9. Optionally, enter an AD user and password, which is only used under rare circumstances to configure authorization by AD and authentication by SAML.

10. Use the Test Login to test login to your Active Directory and to read the Active Directory user memberOf field. Avantra does not store the user and password provided in this Test Login dialog.

11. Active Directory server is now set up.

12. To manually create users managed by Active Directory, Select Administration User Management from the top-level menu. Click New on the Users tab. Then fill in exactly the same User ID as used in Active Directory. Press Next to continue.

    To automatically create AD-managed users, proceed to the next section.

13. From the list of options to set the password for the new user, choose Active Directory user.

14. Add roles and groups to the newly created user, as described in Users, Roles, Permission Sets, and Groups.

| Please note that locally defined users will continue to work with local passwords. Avantra WebUI will always first check if there is a locally defined user, before going to the Active Directory.

Procedure: Configure AD User Synchronization and Authorization

1. Select Administration User Management from the top-level menu. Select the External User Directory tab.

2. Configure the Active Directory Server as described above in 'Configure Active Directory Server'.

3. Enable the Activate AD Credentials Check check box to activate username and password validation against your Active Directory.

4. Enable the Activate automatic User creation check box to automatically create users in Avantra the first time they log in. If this check box is not checked, users must be created manually before they can log in.

5. Enable the Activate automatic User permission synchronization check box to automatically assign permissions to users when they log in to Avantra. More detailed information about user permission synchronization can be found in the solution document Active Directory Integration.

### Integrate SAML based authentication

You can have several SAML configurations in Avantra. To see the list of existing configurations or to create a new one, go to Administration User Management in the top-level menu and select the SAML tab.

In the SAML Configurations table, you can see the names of the configurations, the number of linked users, the time of the last modification, and the status. Using the buttons in the toolbar, you can create a new SAML configuration, change the status of the existing ones or delete a configuration.

Double-clicking on the SAML configuration opens its properties.

Procedure: Configure SAML

1. Define a name for your IDP. This name appears on the Avantra WebUI login dialog as an alternative login option.

2. Upload the IDP metadata XML file of your IDP. If you don’t have such an IDP metadata XML file, fill in the IDP-related fields.

3. Set Avantra Service Provider Name. This name must be registered in your IDP.

4. To manually create users managed by SAML, Select Administration User Management from the top-level menu. Click New on the Users tab. Then fill in exactly the same User ID as used in SAML. Press Next to continue. From the list of options to set the password for the new user, choose SAML user. Press Create User to create the user.

5. Add roles and groups to the newly created user, as described in Users, Roles, Permission Sets, and Groups.

Procedure: Configure IDP Managed User Synchronization and Authorization

1. Enable the Activate automatic User creation check box to automatically create users the first time they log in to Avantra WebUI. If this check box is not enabled, users must be created manually before they can log in.

2. Enable the Activate IDP managed Authorization check box to automatically manage permissions in Avantra WebUI based on SAML attributes or settings. More detailed information about SAML-based user permission can be found in the solution document SAML Integration.