Based on the Authentication mechanism, the Container provides Rundeck with a list of "group" or "role" names that the user belongs to. Rundeck uses this list to determine what access rights the user has. (For more about the role list, refer to Authenticating Users - Container authentication and authorization.)
A Rundeck access control policy grants users and user groups certain privileges to perform actions against rundeck resources like projects, jobs, nodes, commands and API. Every action requested by a user is evaluated by the Rundeck authorization system and logged for reporting and auditing purposes.
Since Rundeck respects the policy definition, you can define role-based authorization to restrict users to only a subset of actions. This enables a self-service type interface, where some users have access to a limited set of executable actions.
Two dimensions of information dictate authorization inside Rundeck:
The remainder of this section will describe how to use the access control policy.
Access to running or modifying Jobs is managed in an access control policy defined using the aclpolicy YAML document. This file contains a number of policy elements that describe what user group is allowed to perform which actions.
Please read over this document for information on how to define it, and how to grant access for certain actions to certain resources:
Policies can be organized into more than one file to help organize access by group or pattern of use. The normal Rundeck install will have generated a policy for the "admin" group. Not all users will need to be given "admin" access level to control and modify all Jobs. More typically, a group of users will be given access to just a subset of Jobs.
Rundeck loads ACL Policy definitions from these locations:
*.aclpolicyfiles found in the rundeck
etcdir, which is either
/etc/rundeck(rpm and debian install defaults), or
The Rundeck server does not need to be restarted for changes to aclpolicy files to take effect.
The files are loaded at startup and are cached. When an authorization request occurs, the policies may be reloaded if the file was modified. A file's contents are cached for at least 60 seconds before checking if they need to be reloaded. Also, the etc directory is only re-scanned for new/removed files after a 60 second delay.
If an authorization request occurs in the context of a specific Project (e.g. "does a user have Run access for a specific Job in this project?") then the Project-level policies created via the API area also used to evaluate the authorization request.
Otherwise, only the policies on the filesystem, and uploaded to the System ACLs API are evaluated for the request.
Added in Rundeck 2.5, the rd-acl tool can help to create, test, and validate your policy files.
File listing: admin.aclpolicy example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
The example policy document above demonstrates the access granted to the users in group "admin".
group can use regular expressions to match multiple users or groups.
Two separate policies define two levels of access control. The first is the "project" context, which allows access to actions on resources within a specific project. The second is the "application" level context, which allows access to things like creating projects, access to projects, managing users, and access to system information.
As described in the aclpolicy-v10(5) definition, access is granted or denied to specific "resources". Resources can take two forms:
For example, you might want to restrict access to a job or jobs within a certain group. This corresponds to specific "job" resources with a "group" property matching a certain pattern.
You might also want to restrict who can create new jobs. Since a new job does not exist yet, you cannot create a rule for this action to apply to an existing job. Which means this corresponds to a generic resource with a "kind" called "job".
In Rundeck 2.8.x and later, Authentication Tokens are given a set of Authorization Roles at generation time, so the access levels for the Token depend on how it was generated.
See: API Token usage instructions.
See below: API Token Authorization.
Rundeck declares a number of actions that can be referenced inside the access control policy document.
The actions and resources are divided into project scope and application scope:
You define application scope rules in the aclpolicy, by declaring this context:
context: application: 'rundeck'
These are the Application scope actions that can be allowed or denied via the aclpolicy:
createaction on a resource type with kind 'project')
readaction on a resource type with kind 'system')
disable_executionsaction on a resource type with kind 'system')
enable_executionsaction on a resource type with kind 'system')
disable_executionsaction on a resource type with kind 'system')
adminaction on a resource type with kind 'system')
adminaction on a resource type of kind 'user')
deleteaction on a specific path within the storage 'storage' type)
The following table summarizes the generic and specific resources and the actions you can restrict in the application scope:
||Create a new project|
||Read system information|
||Enable or disable executions|
||Read system ACL policy files|
||Create system ACL policy files|
||Update system ACL policy files|
||Delete system ACL policy files|
||All access to system ACL policy files|
||Modify user profiles|
||Manage job schedules|
||Create a "user" token|
||Create a "service" token|
||View a project in the project list|
||View and modify project configuration|
||Import archive contents to the project|
||Export the project as an archive|
||Full access to project|
||Read project ACL Policy files|
||Create project ACL Policy files|
||Update project ACL Policy files|
||Delete project ACL Policy files|
||All access to project ACL Policy files|
||Create files in the storage facility|
||Modify files in the storage facility|
||Read files and list directories in the storage facility|
||Delete files in the storage facility|
||Create an API Token with specified roles or username|
API Tokens can be generated if the user has the appropriate authorization on the
apitoken generic resource type.
An API Token with the owner's username, and a subset of the owner's authorization roles.
An API Token which may have a different username than the owner, and may have a different set of authorization roles.
This distinction allows administrators to let some users generate API Tokens which cannot increase their access levels (User Tokens), and other users to generate API Tokens with different access levels in a controlled way.
The authorizations levels are:
generate_user_token: allows the user to generate a User Token.
generate_service_token: allows a user to generate a Service Token (see below).
admin: allows the user to generate a Token with any username and roles.
Example to generate a User Token:
description: Allow "ops_team" members to generate User Tokens for: resource: - equals: kind: apitoken allow: generate_user_token context: application: rundeck by: group: ops_team
To specify what roles and usernames are allowed for a Service Token, the user must also be authorized to
apitoken resource type for a declared set of usernames and roles.
Example to generate a Service Token:
description: Allow "sec_ops" members to generate Service Tokens, for specific usernames and additional roles for: resource: - equals: kind: apitoken allow: generate_service_token apitoken: - allow: create match: username: '(mysql|myservice)' subset: roles: - mysql_api_access - myservice_api_access context: application: rundeck by: group: sec_ops
Service Tokens implicitly allow a subset of the user's own authorization roles and username (
generate_user_token), so the usernames and roles authorized in the ACL Policy must specify any extra roles. When a Service Token is generated, any requested roles not already allowed by
generate_user_token will be checked against the ACL Policy. However, it is best to be explicit in the list of roles you want to allow.
subset: match for
roles: declares that extra roles for the Service Token may only come from this list, but doesn't require the token to have all of the roles. (If you used
contains: it would be the inverse, and grant access only if the extra Service Token roles contained all of those in the
roles: list, i.e. a superset vs. a subset.)
You define project scope rules in the aclpolicy by declaring this context:
context: project: "(regex)"
The regex can match all projects using ".*", or you can simply put the project name.
Note that for projects not matched by an aclpolicy, no actions will be granted to users.
Also note that to hide projects completely from users, you would need to grant or deny the "read" access to the project in the Application Scope.
These are the Project scope actions that can be allowed or denied via the aclpolicy:
The following table summarizes the generic and specific resources and the actions you can restrict in the project scope:
||Create a new Job|
||Read node information|
||Create new node entries|
||Modify node entries|
||Refresh node entry from a URL|
||Read history event information|
||Create arbitrary history event entries|
||Read adhoc execution output|
||Run an adhoc execution|
||Run an adhoc execution as another user|
||Kill an adhoc execution|
||Kill an adhoc execution as another user|
||View a Job, its executions, and read its definition|
||View a Job and its executions|
||Modify a job|
||Delete a job|
||Run a job|
||Run a job as another user|
||Kill a running job|
||Kill a running job as another user|
||Create the matching job|
||Enable/disable the job's schedule|
||Enable/disable the job for execution|
||"rundeck_server", "nodename", ...||
||View the node in the UI (see Node resource properties)|
||Run jobs/adhoc on the node|
Note: see Node resource properties for more node resource properties for authorization.
killAs actions only apply to certain API endpoints, and allow running jobs or adhoc executions or killing executions to be performed with a different username attached as the author of the action. See Rundeck API - Running a Job.
Note: Job deletion requires allowing the 'delete' action both at the generic type and specific resource levels.
Recall that defining rules for a generic resource type is done in this way:
for: resource: - equals: kind: 'project' allow: [create]
Whereas defining rules for specific resources of a certain type is done in this way:
for: job: - equals: name: bob allow: [run]
The properties available are the attributes that are defined on the node, so you can apply authorizations based on tag, osName, hostname, etc. The special
rundeck_server property will be set to "true" for the Rundeck server node only, and "false" for all other nodes.
Any custom attributes can be used as well.
||Name of the node|
||Hostname of the node|
||Description of the node|
||Set of tags. Can use with the
||Operating System name|
||Operating System family, e.g. "unix" or "windows"|
||Operating System version|
||Operating System architecture|
||A value set to "true" if the node is the Rundeck server node|
Below is an example policy document demonstrating policy actions to create limited access for a group of users. Users in the group "restart_user", are allowed to run three jobs in the "adm" group, Restart, stop and start. By allowing
run but not
read, the "stop" and "start" jobs will not be visible. Allowing
view for the 'Restart' job, but not
read, means that the users can view the job, but not its workflow definition, nor can they download the Job definition file.
File listing: restart_user.aclpolicy example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
Below is an example policy to prevent any user on the "remote" group to execute any command or job on the local rundeck server.
If a job is tried to be executed locally, it will fail. Also, the local rundeck server will not appear on the node filter list.
File listing: remote.aclpolicy
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
After defining an aclpolicy file to grant access to a particular group of users, you may find them getting "unauthorized" messages or complaints that certain actions are not possible.
To diagnose this, begin by checking two bits:
rundeck.audit.loglog file. The authorization facility generates fairly low level messages describing how the policy is matched to the user context.
For each entry in the audit log, you'll see all decisions leading up to either a AUTHORIZED or a REJECTED message. It's not uncommon to see REJECTED messages followed by AUTHORIZED. The important thing is to look at the last decision made.