User management

This will help you manage Rudder users and their permissions.

Most of the configuration can be done directly in the web application from an account with the administrator role. It requires the user-management plugin to be installed. You can add, remove and chose the permissions of user accounts.

The accounts are stored in a file on the server which can also be edited directly.

General configuration

This section covers common options which are not configurable through the Web interface.

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.

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

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

Configuration of the users using a configuration file

This sections the configuration of Rudder users directly in the configuration, equivalent to what the user management interface does.


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">
  <user name="alice"  password="xxxxxxx" role="administrator"/>
  <user name="bob"    password="xxxxxxx" role="administration_only, node_read"/>
  <user name="custom" password="xxxxxxx" role="node_read,node_write,configuration_read,rule_read,rule_edit,directive_read,technique_read"/>

The name and password attributes are mandatory (non empty) for the user tags. The role attribute can be omitted but the user will have no permission, and only valid attributes are recognized.

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


The authentication tag should have a "hash" attribute, making "password" attributes on every user expect hashed passwords. Not specifying a hash attribute will fallback to plain text passwords, but it is strongly advised not to do so for security reasons.

The algorithm to be 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



htpasswd -nBC 12 "" | tr -d ':\n' | sed 's/$2y/$2b/'

Highly recommended



read mypass; echo -n $mypass | md5sum

Unsecure, should not be used

"sha" or "sha1"


read mypass; echo -n $mypass | shasum

Unsecure, should not be used

"sha256" or "sha-256"


read mypass; echo -n $mypass | sha256sum

Unsecure, should not be used

"sha512" or "sha-512"


read mypass; echo -n $mypass | sha512sum

Unsecure, should not be used

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 hashed password:

<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"/>

Externally-authenticated users

It expects the same format as regular file-based users, but in this case "name" will be the login used to connect to the external provider and the 'password' field will be ignored and should be set to "LDAP/OpenID/etc." to make it clear that this Rudder installation uses external provider to log users in.

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

Authorization management

For every user you can define an access level, allowing it to access different pages or to perform different actions depending on its level.

You can also build custom roles with whatever permission you want, using a type and a level as specified in the user-management plugin’s documentation.

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

← Agent administration Maintenance procedures →