Jump to content

Portal:Cloud VPS/Admin/Openstack roles and policy

From Wikitech
As of June 2023, Openstack's approach to auth (especially for Keystone) is in transition. There's some chance this will stabilize by version C or D, at which point this document will need to be revised.

Key concepts

There is a general overview about the OpenStack rbac model at https://docs.openstack.org/keystone/latest/admin/service-api-protection.html. That document is unfortunately largely aspirational; many projects are not implemeting the spec as described there, and the spec itself is likely to change in the next version or two.

Project Roles

Access in OpenStack is managed by assigning a user a role in a project or domain. Existing role assignments can be viewed like this:

# openstack role assignment list --user andrew --project testlabs
| Role                             | User   | Group | Project  | Domain | System | Inherited |
| 38676f30eaeb44518bf7e144a73c8da6 | andrew |       | testlabs |        |        | False     |
| f75a3c410bca4e96a1cf6ac103b0ccaf | andrew |       | testlabs |        |        | False     |

Every role has both a name and an ID; to decode role IDs you can list them like this:

root@cloudcontrol1005:~# openstack role list
| ID                               | Name             |
| 1102f4ff63c3435793d0e4340bf4b04e | glanceadmin      |
| 23422ff79766425ca6592e088ac5654e | heat_stack_owner |
| 2cd63d467f754404bf3746fe63ee0698 | admin            |
| 38676f30eaeb44518bf7e144a73c8da6 | member           |
| 906f1588626d4d0993629ea3928b6fb4 | designateadmin   |
| b2167363f0f343a58867e1cdf2c0d3a1 | service          |
| c64eb1ef52934ecfafe41779031e262c | heat_stack_user  |
| f3bebf5f4b6f40fa91f3614431f2c283 | keystonevalidate |
| f75a3c410bca4e96a1cf6ac103b0ccaf | reader           |

The cloud-vps OpenStack deployments have three basic roles, which correspond to the recommended default roles described in the upstream documentation. They are:

  • Reader: Users with the 'reader' role in a project will have ssh access to VMs and sudo rights in that project by default. They will only have read-only access to most OpenStack resources; for example they cannot create or delete VMs. Prior to 2023 this role was called 'user'.
  • Member: A User with the 'member' role will have all the rights that a 'reader' has, plus the ability to alter project-local OpenStack resources (e.g. create or delete VMs. Prior to 2023 this role was called 'projectadmin'.
  • Admin: The admin role provides access to additional OpenStack resources that are unavailable to members. For example, WMCS policy has some specific actions disabled for non-admins (e.g. creating Neutron networks.) Currently, the Admin role also conveys the ability to act on global resources and create and delete projects; this is handled inconsistently in code and is a bit of a mess currently, see Scope below for details.

Domain Roles

Unless you are installing or troubleshooting an orchestration system, you should not need to think about domains much.

In an OpenStack context, the term 'domain' is unrelated to DNS. DNS domains are typically referred to as 'zones'.

An OpenStack domain is a resource container, similar to a project. For cloud-vps purposes, domains are used as containers to contain projects; the vast majority of our projects are stored in the 'default' project.

Roles can be assigned to domains with an --inherited flag, which applies the assignment to every project within that domain. For instance, this assignment gives user 'andrew' the 'admin' right in every project in the default domain:

root@cloudcontrol1005:~# openstack role assignment list --user andrew --domain default
| Role                             | User   | Group | Project | Domain  | System | Inherited |
| 2cd63d467f754404bf3746fe63ee0698 | andrew |       |         | default |        | True      |

Domains are also used by orchestration systems (e.g. Heat and Magnum) where we need to delegate project creation/deletion rights to an otherwise untrusted service user.


During the last few years (starting approximately with OpenStack Xena) some projects started to add an optional second role dimension called 'scope'. The idea is that a 3-term rbac system (user, project, role) would be replaced with a 4-term syste (user, project, role, scope) in order to provide more granular control to the actions previously handled by the 'admin' role.

The addition of scope remains optional in config files (via enforce_scope flag) and is widely regarded as a mistake. We will probably never enable scope enforcement as it is unlikely to ever be enforced in upstream code and in some cases is in the process of being ripped out.


Each OpenStack endpoint has a policy rule that determines which role is required to access the endpoint. The default settings for these policies are scattered here and there throughout code, but in every project they can be customized via an entry in the policy.yaml file. Each project has its own, for example the nova custom policy rules are in /etc/nova/policy.yaml

We seek to conform with default policies as much as possible, but in some cases we override policies either to disable features that don't work in our stack, or (more often) to open public access to read-only endpoints that we want to make more public.

policy.yaml CANNOT override default scope requirements for a policy rule, which is just one more reason why policy scope is difficult to work with.

Historically Keystone has also had the concept of an 'admin API' which runs on a separate port and provides access to different endpoints. Some keystone code still checks to ensure that a request has the magic admin flag as part of enforcement; this check cannot be overridden in policy.yaml. This is generally regarded as broken, legacy code but it's good to be aware of the risk if an endpoint seems to be misbehaving.


There's a small set of regression tests in the script wmcs-policy-tests.py. It can be run on any cloudcontrol, and all tests should pass. Please start by testing this if you sense a breakage in auth and please file a bug if you find an auth issue that is not tested there.

See also

Using the OpenStack CLI

Related tasks

https://phabricator.wikimedia.org/T330759 Modernize openstack RBAC

https://phabricator.wikimedia.org/T276018 Investigate new roles and policies in openstack Xena