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
- RPM install:
- Launcher install:
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.
Authorizing a certain action on a resource
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:
- Look for policies matching the username or group for the user
- Look for a context matching the environment of the given resource
- either a specific project by name
- or the application level
- Look for a Type rule for the type of resource
- either a specific resource by its named type
- or the generic "resource"
- Iterate through the rules for the type
- if a rule matches, and allows the action, mark it and continue.
- if a rule matches and denies the action, return DENIED, and stop
- If it was DENIED, return DENIED. If it was marked, return ALLOWED. Otherwise if no rules matched, return REJECTED.
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:
- Access control on resources other than Jobs can now be declared
- Project level access control is now supported
- "Deny" rules can now be declared
- Application level access control is also supported, replacing the Role mapping
The Rundeck server no longer uses role-mapping and instead defers to the aclpolicy for all authorizations.
In version 1.5
group:now support regular expression matching
- legacy XML support has been removed
rules:section in yaml support has been removed
In version 3.1
notByclause as a negative variant of
In version 3.4
- Add support for
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.
The aclpolicy markup by example
An example policy document.
description: Yaml Policy 1 context: # declares the context of the ACL project: '.*' # applies to projects matching a regex. for: resource: - equals: kind: job allow: '*' job: - allow: '*' - match: group: 'group1/.*' deny: '*' by: username: 'yml_usr_1' group: ['yml_group_1','group2'] urn: '_urn_'
An .aclpolicy supports multiple policy definitions in the form of YAML documents using 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.
urn entries that declare who or what 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
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 by: urn: 'project:MyProject' by: urn: 'user:some.user' by: urn: 'group:some.group'
You can specify a username or group exact match (which will not evaluate as a Regular expression) with a
urn using the supported URN formats:
group:GROUP- matches a group name exactly
user:USER- matches a username exactly
The other use for the
urn is to define ACL Policies that apply to some subjects which do not correspond to users, the primary usage is to define a policy for a Project, using a URN format like:
project:NAMEto match a Project by name
notBy is a variation of the
by clause that only works on
deny, it follow the same pattern using
urn entries but in this case, the policy applies to any subject not matched.
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. As above, a
urn can be used for an exact match instead of a Regular Expression match for username or group.
notBy: username: 'bob' notBy: #using a regular expression username: 'dev\d+' notBy: group: [test,qa,prod] notBy: #using a regular expression group: 'dev_team_(alpha|beta|gamma)' notBy: username: - simon - frank notBy: urn: - user:simon - group:qa
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.
Example Admin policy
This document grants full permissions to an 'admin' group:
description: Admin project level access control. Applies to resources within a specific project. context: project: '.*' # all projects for: resource: - equals: kind: job allow: [create] # allow create jobs - equals: kind: node allow: [read,create,update,refresh] # allow refresh node sources - equals: kind: event allow: [read,create] # allow read/create events adhoc: - allow: [read,run,runAs,kill,killAs] # allow running/killing adhoc jobs job: - allow: [create,read,update,delete,run,runAs,kill,killAs] # allow create/read/write/delete/run/kill of all jobs node: - allow: [read,run] # allow read/run for nodes by: group: admin --- description: Admin Application level access control, applies to creating/deleting projects, admin of user profiles, viewing projects and reading system information. context: application: 'rundeck' for: resource: - equals: kind: project allow: [create] # allow create of projects - equals: kind: system allow: [read,enable_executions,disable_executions,admin] # allow read of system info, enable/disable all executions - equals: kind: system_acl allow: [read,create,update,delete,admin] # allow modifying system ACL files - equals: kind: user allow: [admin] # allow modify user profiles project: - match: name: '.*' allow: [read,import,export,configure,delete,admin] # allow full access of all projects or use 'admin' project_acl: - match: name: '.*' allow: [read,create,update,delete,admin] # allow modifying project-specific ACL files storage: - allow: [read,create,update,delete] # allow access for /ssh-key/* storage content by: group: admin