Rundeck can be configured to use several mechanisms to authenticate a user, and determine the user’s authorized roles.

Primarily these are:

For the default installation (Executable War, RPM, Deb), the Servlet Container is Jetty, and the default security mechanism is JAAS, so you are free to use what ever JAAS provider you feel is suitable for your environment. See JAAS and specifically for Jetty, JAAS for Jetty.

If you use the Rundeck war file with a different container, such as Tomcat, refer to Container authentication and authorization below.

Single Sign On

See Security > Single Sign On.

Jetty and JAAS authentication

Rundeck has three basic JAAS modules.

  1. PropertyFileLoginModule
  2. LDAP
  3. PAM

By default a new installation uses the method.

Each method determines whether the user is authenticated, and what roles they have.

The list of roles can be accepted as-is (default), or you can add a prefix to them using the following config in


These instructions explain how to manage user credentials for Rundeck using a text file containing usernames, passwords and role definitions. Usually this file is called

The default Rundeck installation handles user authentication via JAAS using the file. This file is created at the time that you install the server.


  • Executable War: $RDECK_BASE/server/config/
  • RPM/DEB: /etc/rundeck/

Assuming it wasn’t modified, your file will probably look something like this:

Adding additional users

You may wish to have additional users with various privileges rather than giving out role accounts to groups. You may also want to avoid having the passwords in plaintext within the configuration file.

To accomplish this, you’ll need a properly hashed or encrypted password to use in the config. Rundeck has a built in command line utility to encrypt passwords. The default encryption service is the Jetty password utility.

In this example, we’ll setup a new user named “jsmith”, with a password of “mypass”:

obfuscate: OBF:1xfd1zt11uha1ugg1zsp1xfp
md5: MD5:a029d0df84eb5549c641e04a9ef389e5
crypt: CRYPT:jsnDAc2Xk4W4o

Then add this to the file with a line like so:

jsmith: MD5:a029d0df84eb5549c641e04a9ef389e5,user,admin

Then restart Rundeck to ensure it picks up the change and you’re done.

There is also a password encrypter utility user interface in the Rundeck application that can be used to generate encrypted passwords. Click the gear icon and then “Password Utility” to use that interface.

Hot Reloading the file

If you want your changes to the file to be picked up without having to restart Rundeck change the module specified in the JAAS config file from org.eclipse.jetty.jaas.spi.PropertyFileLoginModule to org.rundeck.jaas.jetty.ReloadablePropertyFileLoginModule

The refresh interval for checking the file is 5 seconds. This is not configurable.

For example, the following configuration uses the non-reloadable

RDpropertyfilelogin {
    org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required

This configuration would enable hot reloading:

RDpropertyfilelogin {
    org.rundeck.jaas.jetty.ReloadablePropertyFileLoginModule required


LDAP and Active Directory configurations are created in the same way, but your LDAP structure may be different than Active Directory’s structure.

Rundeck includes two JAAS login modules you can use for LDAP directory authentication:

These are an enhanced version of the default Jetty JAAS Ldap login module that caches authorization results for a period of time.

JAAS supports evaluating MD5 and CRYPT password hashes.

You must change some configuration values to change the authentication module to use.


Configuring LDAP consists of defining a JAAS config file (e.g. “jaas-ldap.conf”), and changing the server startup script to use this file and use the correct Login Module configuration inside it.

Step 1: Setup the LDAP login module configuration file

Create a jaas-ldap.conf file in the same directory as the jaas-loginmodule.conf file.

  • RPM/Deb install: /etc/rundeck/
  • Executable War install: $RDECK_BASE/server/config

Make sure the name of your Login Module configuration is the same as you use in the next step. The Login Module configuration is defined like this:

Where “myloginmodule” is the name.

Step 2: Specify login module

To override the default JAAS configuration file, you will need to supply the Rundeck server with the proper path to the new one, and a Java system property to identify the new login module by name.

The JAAS configuration file location is specified differently between the Executable War and the RPM/Deb.

For the Executable War: the Java system property is used to identify the name of the config file, which must be located in the $RDECK_BASE/server/config dir.

You can simply specify the system properties on the java commandline:

Otherwise, if you are starting the Executable War via the supplied rundeckd script, you can modify the RDECK_JVM value in the $RDECK_BASE/etc/profile file to add two JVM arguments:

Note: more information about using the Executable War and useful properties are under Getting Started - Executable War Options.

For the RPM/Deb installation: the absolute path to the JAAS config file must be specified with the property.

Declare RDECK_JVM_OPTS in /etc/sysconfig/rundeckd (rpm) or /etc/default/rundeckd (deb):

Step 3: Restart rundeckd

Step 4: Attempt to logon

If everything was configured correctly, you will be able to access Rundeck using your AD credentials. If something did not go smoothly, look at /var/log/rundeck/service.log for stack traces that may indicate what is wrong. To make troubleshooting easier, you may want to add the -Dcom.dtolabs.rundeck.jetty.jaas.LEVEL=DEBUG Java system property to the RDECK_JVM environment variable above, to have enable DEBUG logging for the authentication module.

Login module configuration

Here is an example configuration file for the JettyCachingLdapLoginModule:

The JettyCachingLdapLoginModule has these configuration properties:

“true/false” - turn on or off debug output
The LDAP context factory class, e.g. “com.sun.jndi.ldap.LdapCtxFactory”
ldap URL for the server, e.g. “ldap://server:389”
Optional. If not using “binding” authentication, set this to the root DN that should bind, e.g. “cn=Manager,dc=example,dc=com”
password for root DN. Note: The bindDn and bindPassword must escape any special characters with \ character. Special characters include \ (backslash), as well as ! (exclamation).
Authentication method, e.g. “simple”
“true/false” - if true, bind as the user that is authenticating, otherwise bind as the manager and perform a search to verify user password. NOTE: This module can only verify passwords hashed with MD5 or CRYPT. If your LDAP directory contains other hashes you’ll likely need to set this to true to be able to authenticate.
“true/false” - if true and forceBindingLogin is true, then role membership searches will be performed in the root context, rather than in the bound user context.
base DN to search for users, example: “ou=People,dc=test1,dc=example,dc=com”
Attribute name for username, used when searching for user role membership by DN, default “uid”.
Attribute name to identify user by username, default “cn”.
Attribute name for user password, default “userPassword”.
Attribute name for user object class, default “inetOrgPerson”.
Base DN for role membership search, e.g. “ou=Groups,dc=test1,dc=example,dc=com”.
Attribute name for role name, default “roleName”.
Attribute name for a role that would contain a user’s DN, default “uniqueMember”.
Attribute name for a role that would contain a user’s username. If set, this overrides the roleMemberAttribute behavior.
Object class for role, default “groupOfUniqueNames”.
Prefix string to remove from role names before returning to the application, e.g. “rundeck_”.
Duration that authorization should be cached, in milliseconds. Default “0”. A value of “0” indicates no caching should be used.
“true/false” - if true, output cache statistics to the log.
Comma-separated list of role names. All of the given role names will be automatically added to authenticated users. You can use this to provide a “default” role or roles for all users.
Read timeout value (ms). Default: 0 (no timeout)
Connect timeout value (ms). Default: 0 (no timeout)
“true/false” - Default: false. If true, will resolve all nested groups for authenticated users. For the first user to login after a fresh start it will take a couple of seconds longer, this is when the cache of all nested groups is built. This will happen as often as the cache is refreshed. Uses the cacheDurationMillis for cache timeout.

The JettyCombinedLdapLoginModule is extends the previous module, so is configured in almost exactly the same way, but adds these additional configuration options:

Do not look up role membership via LDAP. May be used with storePass and combined with another login module for authorization roles. (See JettyRolePropertyFileLoginModule)
Store the user/password for use by subsequent login module.
Clear the user/password that was stored after login is successful. (This would prevent any subsequent login modules from re-using the stored credentials. Set it to false if you want to continue using the credentials.)
Use the stored user/password for authentication, and do not attempt to use other mechanism (e.g. login callback).
Try to use the stored user/password for authentication, if it fails then proceed with normal mechanism.

Combining LDAP with other modules

Use the JettyCombinedLdapLoginModule to do LDAP authentication, then combine it with the JettyRolePropertyFileLoginModule (or some other module) to supply the authorization roles.

The first module should set storePass="true", and the second module should set useFirstPass="true" or tryFirstPass="true".

Finally, see the section Multiple Authentication Modules about the appropriate configuration Flag to use.

The PAM section is a useful comparison as it uses the same method to combine modules.

Active Directory

Here is an example configuration for Active Directory. The string sAMAccountName refers to the short user name and is valid in a default Active Directory installation, but may vary in some environments.

Communicating over secure ldap (ldaps://)

The default port for communicating with active directory is 389, which is insecure. The secure port is 636, but the LoginModule describe above requires that the AD certificate or organizations CA certificate be placed in a truststore. The truststore provided with rundeck /etc/rundeck/ssl/truststore is used for the local communication between the cli tools and the rundeck server.

Before you can establish trust, you need to get the CA certificate. Typically, this would require a request to the organization’s security officer to have them send you the certificate. It’s also often found publicly if your organization does secure transactions.

Another option is to interrogate the secure ldap endpoint with openssl. The example below shows a connection to on port 443. The first certificate is the machine and that last is the CA. Pick the last certificate.

note that for Active Directory, the host would be the Active Directory server and port 636. note Certificates are PEM encoded and start with —–BEGIN CERTIFICATE—– end with —–END CERTIFICATE—– inclusive.

depth=1 C = US, O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU = Terms of use at (c)09, CN = VeriSign Class 3 Secure Server CA - G2
verify error:num=20:unable to get local issuer certificate
verify return:0
Certificate chain
 0 s:/C=US/ST=California/L=San Jose/O=PayPal, Inc./OU=Information Systems/
   i:/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at (c)09/CN=VeriSign Class 3 Secure Server CA - G2
 1 s:/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at (c)09/CN=VeriSign Class 3 Secure Server CA - G2
   i:/C=US/O=VeriSign, Inc./OU=Class 3 Public Primary Certification Authority - G2/OU=(c) 1998 VeriSign, Inc. - For authorized use only/OU=VeriSign Trust Network
Server certificate
subject=/C=US/ST=California/L=San Jose/O=PayPal, Inc./OU=Information Systems/
issuer=/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at (c)09/CN=VeriSign Class 3 Secure Server CA - G2
No client certificate CA names sent
SSL handshake has read 3039 bytes and written 401 bytes
New, TLSv1/SSLv3, Cipher is DES-CBC3-SHA
Server public key is 1024 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
    Protocol  : TLSv1
    Cipher    : DES-CBC3-SHA
    Session-ID: A8AAA4F22E9A4B3F12F76303464643525178846D96CA0BC0B81F35368BF55B89
    Master-Key: 9F767B91FC2450E291CBB21E3438CA9A73FE8D5B825AD98F821F5EB912C088DFB66FCBF2D53591E2D1ED77E9B6A22504
    Key-Arg   : None
    PSK identity: None
    PSK identity hint: None
    Start Time: 1295242116
    Timeout   : 300 (sec)
    Verify return code: 20 (unable to get local issuer certificate)

Once a certificate has been obtained. There are two options for adding the certificate. The first involves updating the truststore for the JRE. If that is not possible or not desirable, then one can set the truststore to be used by the jvm, using any arbitrary truststore that contains the appropriate certificate.

Both options require importing a certificate. The following would import a certificate called, AD.cert into the /etc/rundeck/ssl/truststore.

To add the certificate to the JRE, locate the file $JAVA_HOME/lib/security/cacerts and run

To verify your CA has been added, run keytool list and look for CompanyAD in the output.

Refer to: for more information how how to import a certificate.

Finally, in your ldap-activedirectory.conf be sure to change the providerUrl to be ldaps://ad-server. Including the port is optional as the default is 686.


Rundeck includes a PAM JAAS login module, which uses libpam4j to authenticate.

In order for Rundeck to have the necessary permissions to check user credentials, the user that runs the Rundeck process must be in the shadow group.
This can be done with the command:

$ sudo addgroup rundeck shadow

On debian based systems you need to install libpam4j :

This module can work with existing properties-file based authorization roles by enabling shared credentials between the modules, and introducing a Property file module that can be used only for authorization.


  • org.rundeck.jaas.jetty.JettyPamLoginModule authenticates via PAM, can add a default set of roles to authenticated users, and can use local unix group membership for role info.
  • org.rundeck.jaas.jetty.JettyAuthPropertyFileLoginModule authenticates via property file, but does not supply user authorization information.
  • org.rundeck.jaas.jetty.JettyRolePropertyFileLoginModule does not authenticate and only uses authorization roles from a property file. Can be combined with previous modules.

sample jaas config:

When combining the two login modules, note that the storePass and useFirstPass are set to true, allowing the two modules to share the user information necessary for the second module to load the user roles.

Common configuration properties:

These JAAS configuration properties are used by all of the Jetty PAM modules:

  • useFirstPass
  • tryFirstPass
  • storePass
  • clearPass
  • debug


Configuration properties:

  • serviceName - name of the PAM service configuration to use. (Required). Example: “sshd”.
  • useUnixGroups - true/false. If true, the unix Groups defined for the user will be included as authorization roles. Default: false.
  • supplementalRoles - a comma-separated list of additional user roles to add to any authenticated user. Example: ‘user,readonly’


This module does not authenticate, and requires that useFirstPass or tryFirstPass is set to true, and that a previous module has storePass set to true.

It then looks the username up in the Properties file, and applies any roles for the matching user, if found.

Configuration properties:

  • file - path to a Java Property formatted file in the format defined under
  • caseInsensitive - true/false. If true, usernames are converted to lowercase before being looked up in the property file, otherwise they are compared as entered. Default: true.

Note that since the user password is not used for authentication, you can have a dummy value in the password field of the file, but some value is required in that position.

Example properties file with dummy passwords and roles:

admin: -,user,admin
user1: -,user,readonly


This module provides authentication in the same way as the mechanism, but does not use any of the role names found in the file. It can be combined with JettyRolePropertyFileLoginModule by using storePass=true.

Configuration properties:

  • hotReload - hotReload="true" enables the ability to modify the user list specified by file without having to restart Rundeck. The refresh interval for checking the file is 5 seconds. This is not configurable.
  • file - path to a Java Property formatted file in the format defined under

Multiple Authentication Modules

JAAS configurations can contain multiple LoginModule definitions, which are processed in order and according to the logic of the configuration Flag.

In your config file, separate the LoginModule definitions with a ; and be sure to select the appropriate Flag for the module, one of required, requisite, sufficient, or optional.

The full syntax and the description of how these Flags work is described in more detail under the JAAS Configuration Documentation.

Here is an example combining an LDAP module flagged as sufficient, and a flat file config flagged as required:

Based on the flags, JAAS would attempt the following for authentication:

  1. Check username/pass against LDAP
  2. If auth succeeds, finish with successful authentication
  3. If auth fails, continue to the next module
  4. Check username/pass against the properties file
  5. If auth succeeds, finish with successful authentication
  6. If auth fails, finish with failed authentication

Jaas Authorization Testing

If you would like to test your Jaas configuration without restarting Rundeck every time you make a change to your Jaas configuration, you can execute the command:

$ java -jar -Drundeck.jaaslogin=true$LOGIN_MODULE_NAME -Drdeck.base=$RD_BASE_DIR rundeck.war --testauth


$ java -jar -Drundeck.jaaslogin=true -Drdeck.base=/etc/rundeck rundeck.war --testauth
$ Checking file: /etc/rundeck/server/config/jaas-loginmodule.conf
$ Checking login module: RDpropertyfilelogin
$ Enter user name: admin
$ Enter password admin <-- This is masked in actual use
$ Login Succeeded!  

The Jaas configuration file you are testing against will be printed out, along with the name of the login module you are testing.
You will be prompted to enter a username and password. These will be compared against your current Jaas configuration.
If the login is successful you will see: Login Succeeded!
If the login fails a stacktrace will be printed out which will contain the details about the failure.

Container authentication and authorization

Container Authentication provides the Servlet context used by Rundeck with a few mechanisms to determine what roles the user has.


JAAS authentication modules define a “Principal” that represents the authenticated user, and which can list the “roles” the user has.

The Container also provides a query mechanism isUserInRole.

Both of these methods are used by default, although they can be disabled with the following configuration flags in

Preauthenticated Mode

Preauthenticated Mode using AJP with apache and tomcat


“Preauthenticated” means that the Servlet Container (e.g. Tomcat) is not being used for authentication/authorization. The user name and role list are provided to Rundeck from another system, usually a reverse proxy set up “in front” of the Rundeck web application, such as Apache HTTPD. Rundeck accepts the “REMOTE_USER” as the username, and allows a configurable Request Attribute to contain the list of user roles.

Note: If you use this method, make sure that only your proxy has direct access to the ports Rundeck is listening on (e.g. firewall them), otherwise you are opening access to rundeck without requiring authentication.

This method can be enabled with this config in

This configuration requires some additional setup to enable:

  1. Apache HTTPD and Tomcat must be configured to communicate so that a list of User Roles is sent to Tomcat as a request Attribute with the given “attributeName”.

For Tomcat and Apache HTTPd with mod_proxy_ajp, here are some additional instructions:

  1. Modify the tomcat server.xml, and make sure to set tomcatAuthentication="false" on the AJP connector:

     <Connector port="8009" protocol="AJP/1.3" redirectPort="4440" tomcatAuthentication="false"/>
  2. Configure Apache to perform the necessary authentication, and to pass an environment variable named “REMOTE_USER_GROUPS”, the value should be all colon-separated e.g.: “user:admin:ops” (or using the delimiter you have configured.)

Here is an example using just mod_proxy_ajp, and passing a static list of roles. A real solution should use mod_lookup_identity:

<Location /rundeck>
    ProxyPass  ajp://localhost:8009/rundeck

    AuthType basic
    AuthName "private area"
    AuthBasicProvider file

    AuthUserFile /etc/httpd/users.htpasswd
    SetEnv AJP_REMOTE_USER_GROUPS "admin:testrole1:testrole2"
    Require valid-user

Note: mod_proxy_ajp requires prefixing the environment variable with “AJP_”, but mod_jk can pass the environment variable directly.

Once authenticated via Apache, you should be able to access rundeck. You might see a page saying “You have no authorized access to projects”, and then “(User roles: role1, role2, …)” with a list of all of the user roles seen by Rundeck. This page just means that there are no aclpolicy files that match those roles, but the apache->tomcat authorization is still working correctly. At this point, move on to Access Control Policy to set up access control for the listed roles.

If the “User roles:” part is blank, then it may not be working correctly.

Preauthenticated Mode using headers

If you have a proxy sitting in front of your Rundeck installation that authenticates your users, you can send the authenticated user and groups to Rundeck via HTTP headers. Set the following properties in your file.,

The attributeName property is the name of the request attribute which stores the user groups for the request. The forwarded headers will be put into this attribute. This attribute must be set for this method to work properly.

The userNameHeader property is the name of the header from which to obtain the authenticated user name.

The userRolesHeader property is the name of the header from which to obtain the list of user roles. The roles should be delimited by the delimiter specified in the delimiter property.

Preauthenticated mode logout redirection

If you are running preauthenticated mode and wish to redirect to a custom logout url on user logout, set the following properties:

# Redirect to upstream logout url