This document describes the YAML format for ACL Policy definition files.
Multiple aclpolicy files can be stored in the same directory, helping the management of each set of rules. This reduces the complexity of each file. The default path is
Policy files are parsed using YAML and while the structure is rigid, additional information can be added and safely ignored. So creating arbitrary elements for documentation or organizational purposes is gracefully parsed.
The resulting file must be a valid yaml file.
For more information about the exact resources and actions you need to authorize for the Rundeck application, see the Administration Guide - Authorization.
The aclpolicy describes actions that are allowed or denied on certain resources.
The method for determining whether a user has access to perform such an action happens essentially in this way:
Thus to allow an action, there has to be a matching rule that allows it, and no matching rule that denies it.
The YAML format has changed since version 1.2 to address several issues:
The Rundeck server no longer uses role-mapping and instead defers to the aclpolicy for all authorizations.
group:now support regular expression matching
rules:section in yaml support has been removed
Note: The XML format from Rundeck 1.3 and earlier is no longer supported. As well, the YAML format from 1.2 is now only partially supported.
If you are upgrading from Rundeck 1.3 or earlier, you will have to modify your *.aclpolicy files.
If you have XML formatted files, you will need to remove and replace them with a YAML document in the format described below. A full, admin-level ACL is described at the end of this document.
If you have YAML formatted files, you will also need to upgrade them slightly.
An example policy document.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
An .aclpolicy supports multiple policy definitions in the form of YAML documents usign the
--- separator. There are four elements that make a policy definition:
It's recommended that this description be short and descriptive as it appears in the log output.
context section declares the scope of the ensuing policy description.
context can contain one of two things:
project: declares the name of the project(s) for which the policy applies. Its value is a String, and can be a regular expression, for which the project name must match to apply.
If you declare an
application section, its only supported value is
rundeck, as: context: application: 'rundeck'
This declares that the policy document describes access control at the application level, rather than for at a project level. You can then declare access control on actions such as creating Projects.
Note that to provide a full "admin" level access control for a user or group, then two policies must be defined, for application level as well as for project level.
NOTE if you are upgrading a yaml 1.2 format document, you will need to add a
for section declares a set of resource types, each containing a sequence of matching rules which allow or deny certain actions.
Resource types declare the type of a specific resource for the match, and the generic "resource" is used to declare rules for all resources of a certain type.
for is an entry for any of these resource types:
job- a Rundeck Job
node- a Node resource
adhoc- an Ad-hoc execution
project- a Project
resource- indicates rules for all resources of a certain kind
Within each type section is a sequence of rules. Recall that in YAML, a sequence is defined using multiple
- indicators, or within
] and separated by commas.
- a - b
[ a, b ]
Type rules are in the form:
matching*: property: value allow: actions deny: actions
Each rule has one or more of these Action entries:
allow- (List or String) - the actions allowed
deny- (List or String) - the actions denied
It also has one or more of these "Matching" entries:
match- (List or String) - regular expression matches
equals- (String) - equality matches
contains- (List or String) - superset membership matches
subset- (List or String) - subset membership matches
Each Matching entry is composed of
property: value, which declare what property of the resource to test, and what value or values to apply the matching rule to.
For example, to declare a rule for a resource with a "name" property of "bob" exactly, use
equals: name: bob allow: [action1, action2] deny: action3
For regular expression matching, use
match: name: 'bob|sam'
For set membership matches, such as matching a Node that must have three different tags, you can use
contains: tags: [a,b,c]
contains allow a list of property values, and all of them must match the resource's property for the rule to match. This allows the basic boolean AND logic. For OR logic, you can simply declare another rule in the sequence since all rules are checked (except in the case of an explicit deny).
subset match allows a list of property values, and will fail if the resource has any values not included in the subset.
group entries that declare who the policy applies to.
Each entry can contain a single string, or a sequence of strings to define multiple entries.
Regular expressions are supported in the username or group.
A single match will result in further evaluation of the policy.
by: username: 'bob' by: #using a regular expression username: 'dev\d+' by: group: [test,qa,prod] by: #using a regular expression group: 'dev_team_(alpha|beta|gamma)' by: username: - simon - frank
The actions element can be either a single value, or a list of values. A single value takes the form:
And a list takes the form:
Note that the single tick marks are optional according to the yaml specification.
Possible values are limitless so it requires an understanding of the job definition you're trying to run. The best way to understand what the actions are is to look at the rundeck-audit.log. This will show all the options as they're being evaluated.
This document grants full permissions to an 'admin' role:
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