Appendix A. The policy.json file

A simple rule might look like this:

"compute:get_all" : ""

The target is "compute:get_all", the "list all instances" API of the Compute service. The rule is an empty string meaning "always". This policy allows anybody to list instances.

You can also decline permission to use an API:

"compute:shelve": "!"

The exclamation mark stands for "never" or "nobody", which effectively disables the Compute API "shelve an instance".

Many APIs can only be called by admin users. This can be expressed by the rule "role:admin". The following policy ensures that only administrators can create new users in the Identity database:

"identity:create_user" : "role:admin"

You can limit APIs to any role. For example, the Orchestration service defines a role named heat_stack_user. Whoever has this role isn't allowed to create stacks:

"stacks:create": "not role:heat_stack_user"

This rule makes use of the boolean operator not. More complex rules can be built using operators and, or and parentheses.

You can define aliases for rules:

"deny_stack_user": "not role:heat_stack_user"

The policy engine understands that "deny_stack_user" is not an API and consequently interprets it as an alias. The stack creation policy above can then be written as:

"stacks:create": "rule:deny_stack_user"

This is taken verbatim from /etc/heat/policy.json.

Rules can compare API attributes to object attributes. For example:

"compute:start" : "user_id:%(user_id)s"

states that only the owner of an instance can start it up. The user_id string before the colon is an API attribute, namely the user ID of the API user. It is compared with the user ID of the object (in this case, an instance); more precisely, it is compared with the user_id field of that object in the database. If the two values are equal, permission is granted.

An admin user always has permission to call APIs. This is how /etc/keystone/policy.json makes this policy explicit:

"admin_required": "role:admin or is_admin:1",
"owner" : "user_id:%(user_id)s",
"admin_or_owner": "rule:admin_required or rule:owner",
"identity:change_password": "rule:admin_or_owner"

The first line defines an alias for "user is an admin user". The is_admin flag is only used when setting up the Identity service for the first time. It indicates that the user has admin privileges granted by the service token (--os-token parameter of the keystone command line client).

The second line creates an alias for "user owns the object" by comparing the API's user ID with the object's user ID.

Line 3 defines a third alias admin_or_owner, combining the two first aliases with the Boolean operator or.

Line 4 sets up the policy that a password can only be modified by its owner or an admin user.

As a final example, let's examine a more complex rule:

"identity:ec2_delete_credential": "rule:admin_required or
             (rule:owner and user_id:%(target.credential.user_id)s)"
    

This rule determines who can use the Identity API "delete EC2 credential". Here, boolean operators and parentheses combine three simpler rules. admin_required and owner are the same aliases as in the previous example. user_id:%(target.credential.user_id)s compares the API user with the user ID of the credential object associated with the target.

A policy.json file consists of policies and aliases of the form target:rule or alias:definition, separated by commas and enclosed in curly braces:

 {
       "alias 1" : "definition 1",
       "alias 2" : "definition 2",
       ...
       "target 1" : "rule 1",
       "target 2" : "rule 2",
       ....
}

Targets are APIs and are written "service:API" or simply "API". For example, "compute:create" or "add_image".

Rules determine whether the API call is allowed.

Rules can be:

Special checks are

Developers can define additional special checks.

Two values are compared in the following way:

"value1 : value2"

Possible values are

API attributes can be project_id, user_id or domain_id.

Target object attributes are fields from the object description in the database. For example in the case of the "compute:start" API, the object is the instance to be started. The policy for starting instances could use the %(project_id)sattribute, that is the project that owns the instance. The trailing s indicates this is a string.

is_admin indicates that administrative privileges are granted via the admin token mechanism (the --os-token option of the keystone command). The admin token allows initialisation of the identity database before the admin role exists.

The alias construct exists for convenience. An alias is short name for a complex or hard to understand rule. It is defined in the same way as a policy:

alias name : alias definition

Once an alias is defined, use the rule keyword to use it in a policy rule.

You may encounter older policy.json files that feature a different syntax, where JavaScript arrays are used instead of boolean operators. For example, the EC2 credentials rule above would have been written as follows:

"identity:ec2_delete_credential": [ [ "rule:admin_required ],
             [ "rule:owner", "user_id:%(target.credential.user_id)s)" ] ]
    

The rule is an array of arrays. The innermost arrays are or'ed together, whereas elements inside the innermost arrays are and'ed.

While the old syntax is still supported, we recommend using the newer, more intuitive syntax.