User management

Change the users authorized to connect to the application. You can define authorization level for each user

Configuration of the users using a XML file


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



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



read mypass; echo -n $mypass | md5sum

"sha" or "sha1"


read mypass; echo -n $mypass | shasum

"sha256" or "sha-256"


read mypass; echo -n $mypass | sha256sum

"sha512" or "sha-512"


read mypass; echo -n $mypass | sha512sum

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="sha256">

  <!-- In this example, the hashed password is: "secret", hashed as a sha256 value -->
  <user name="carol" password="2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b" role="administrator"/>


Configuring an LDAP 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 LDAP authentication for Rudder users.

LDAP authentification requires the plugin Authentication backends to be installed. Check the plugin’s documentation to enable and configure your LDAP authentification.

LDAP is only for 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 the Rudder user file (rudder-users.xml).

A user whose authentication is accepted by LDAP but not declared in the rudder-users.xml file 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).

The credentials of a user are defined in the XML file /opt/rudder/etc/rudder-users.xml. It expects the same format as regular file-based user login, but in this case "name" will be the login used to connect to LDAP and the 'password' field will be ignored and should be set to "LDAP" to make it clear that this Rudder installation uses LDAP 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.

Roles can match different types of users

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

Going further

Rudder aims at integrating with your IT system transparently, so it can’t force its own authentication system.

To meet this need, Rudder relies on the modular authentication system Spring Security that allows to easily integrate with databases or an enterprise SSO like CAS, OpenID or SPNEGO. The documentation for this integration is not yet available, but don’t hesitate to reach us on this topic.

← Agent administration Maintenance procedures →