User management

Rudder user management allows to define:

identification: which users exists on Rudder and what is their login identifier. A user must be declared before having any access to Rudder,
authentication: what means of authentication is used to assess that an user is who he claims to be,
authorization: what set of actions the user can do in Rudder, from seeing pages to changing data or using APIs.

Defaults authentication and authorization capabilities are limited, file-based configured and simple. These capabilities can be extended through several plugins:

authentication backends plugin allows to rely on LDAP/AD and OAUTH2/OpenID Connect to authenticate users,
user-management plugin allows to extend authorization granularity, define custom roles and have an UI for user management.
api-authorization plugin allows to extend API authorization granularity and to allow users to get personal API token corresponding to their authorization.

You can consult these plugin documentations for the corresponding details. In that part of the documentation, we will focus of user management without these plugins by directly editing the corresponding configuration files.

Configuration files related to user authentication and authorizations

In Rudder, authentication providers and user/role credentials are defined separately:

authentication providers are configured in the /opt/rudder/etc/rudder-web.properties main configuration file. Change to that file require a restart of Rudder.
user/role credentials are configured in the /opt/rudder/etc/rudder-users.xml file. Changes in that file only require a reload action, either thanks to the UI or via an API call, when the user-management plugin is installed, but they require a restart of Rudder without it.

Their content and modification are detailed in the following sections.

Authentication providers configuration

Authentication providers define what mean of authentications will be used to check a user authentication claim. They are configured in the /opt/rudder/etc/rudder-web.properties main configuration file, in the rudder.auth.provider property. Other rudder.auth.* properties are linked to authentication providers. Without the authentication backends plugin, only the file provider is available and used by default. This provider is a password-based authentication, for which the password hashes are stored in the rudder-users.xml file detailed below.

Configuring an external authentication provider for Rudder

If you are operating on a corporate network or want to have your users in a centralized database, you can enable external authentication for Rudder users. Rudder supports LDAP/Active Directory, OAUTHv2 and OpenID Connect authentication providers.

External authentication requires the Authentication backends plugin to be installed. Read the plugin’s documentation to enable and configure your external authentication.

Take care of the following limitation of the current process: only authentication is delegated to LDAP, NOT authorizations. So you still have to declare user’s authorizations in Rudder.

A user whose authentication is accepted by the external provider but not declared in Rudder is considered to have no rights at all (and so will only see a reduced version of Rudder homepage, with no action nor tabs available).

User and role configuration file

/opt/rudder/etc/rudder-users.xml is the main configuration file for managing users and roles in Rudder. More precisely, it allows to:

list each user allowed to access Rudder, along with his granted permissions to see or do things in Rudder. In the case of the default file authentication provider, it also allows to store user password hash.
define custom-roles which are a way to give a name to a set of permissions so that it can be reused in user credential definition,
define general properties like user login case-sensitivity, or the hash algorithm used for passwords.

Without the user-managedment plugin, every modification of this file should be followed by a restart of the Rudder web application to be taken into account (systemctl restart rudder-jetty).

File format

The credentials of a user are defined in the XML file /opt/rudder/etc/rudder-users.xml. This file expects the following format:

<authentication hash="bcrypt" case-sensitivity="true">
  <custom-roles>
    <role name="NodeAccess" permissions="node_read,node_write" />
    <role name="RuleAccess" permissions="rule_read,rule_edit" />
    <role name="SecurityDashboards" permissions="cve_read,system-update_read" />
  </custom-roles>
  <user name="alice"  password="xxxxxxx" permissions="administrator"/>
  <user name="bob"    password="xxxxxxx" permissions="administration_only, node_read"/>
  <user name="custom1" password="xxxxxxx" permissions="node_read,node_write,rule_read,rule_edit,directive_read,technique_read"/>
  <user name="custom2" password="xxxxxxx" permissions="NodeAccess,RuleAccess,directive_read,technique_read"/>
  <user name="audit"  password="xxxxxxx" permissions="SecurityDashboards"/>
</authentication>

<custom-role>

custom-role section is optional and only available with the user-management plugin. It allows to define new named roles. See the plugin documentation for more information.

<user>

The user tag allows to declare a known user in Rudder.

The name attributes is mandatory (non-empty). It defines the login that the user will use to connect to Rudder.

The password attribute is optional. It stores the user’s password hash when the file authentication provider is used.

The permissions attribute is optional. It lists granted permissions to the user.

Login case-sensitivity

Logins are case-sensitive by default. To change this behavior yon can modify the parameter case-sensitivity to false in /opt/rudder/etc/rudder-users.xml, then restart the application (systemctl restart rudder-jetty).

This option can be used to get consistent authentication constraints on login with an external authentication provider, typically with an Active Directory based authentication.

When you change the case-sensitivity, make sure there is no potential conflicts between logins, otherwise all conflicting users will be ignored from Rudder.

Passwords

The authentication tag should have a "hash" attribute, making "password" attributes on every user expect hashed passwords. Not specifying a hash attribute will fall back to bcrypt passwords, but it is strongly advised to always specify the algorithm used. There is no guaranty that this default will remain at that value, which may lead to version upgrade inconveniences.

The algorithm used to create the hash (and verify it during authentication) depend on the value of the hash attribute. The possible values, the corresponding algorithm and the Linux shell command need to obtain the hash of the "secret" password for this algorithm are listed here:

Table 1. Hashed passwords algorithms list
Value	Algorithm	Linux command to hash the password	Note
"bcrypt"	bcrypt	`htpasswd -nBC 12 "" \| tr -d ':\n' \| sed 's/$2y/$2b/'`	Highly recommended
"md5"	md5	`read mypass; echo -n $mypass \| md5sum`	Unsecure, should not be used
"sha" or "sha1"	sha1	`read mypass; echo -n $mypass \| shasum`	Unsecure, should not be used
"sha256" or "sha-256"	sha256	`read mypass; echo -n $mypass \| sha256sum`	Unsecure, should not be used
"sha512" or "sha-512"	sha512	`read mypass; echo -n $mypass \| sha512sum`	Unsecure, should not be used

Example 1. BCrypt parameters

By default, RUDDER uses bcrypt with 2b as version and the cost set to 12. If you want to change the cost value, you need to set it in the rudder.bcrypt.cost property in /opt/rudder/etc/rudder-web.properties.

When using the suggested commands to hash a password, you must enter the command, then type your password, and hit return. The hash will then be displayed in your terminal. This avoids storing the password in your shell history.

Here is an example of authentication file with the secret password hashed using bcrypt for user carol:

<authentication hash="bcrypt" case-sensitivity="true">
  <!-- In this example, the hashed password is: "secret", hashed as a bcrypt value -->
  <user name="carol" password="$2b$12$C5QXJEHER1vwriBe7s7FROpfMmeKc9.Lz.n68SOYsxagQIsJARv.S" role="administrator"/>
</authentication>

User roles and fine-grained authorizations

For every user you can define a set of permissions (roles or individual rights), allowing it to access different pages or to perform different operations in Rudder.

To ease management of authorization, you can also build custom roles with their own permission list of individual rights and roles. See user-management plugin’s documentation for more information on that topic.

Defining and using different roles in Rudder require the User-management plugin.

When the user-management plugin is not used, only the administrator roles is available.

← Agent administration Maintenance procedures →