Default Roles¶
Primer¶
Like most OpenStack services, keystone protects its API using role-based access control (RBAC).
Users can access different APIs depending on the roles they have on a project, domain, or system, which we refer to as scope.
As of the Rocky release, keystone provides three roles called admin,
member, and reader by default. Operators can grant these roles to any
actor (e.g., group or user) on any scope (e.g., system, domain, or project).
If you need a refresher on authorization scopes and token types, please refer
to the token guide. The following sections describe how each default role
behaves with keystone’s API across different scopes. Additionally, other
service developers can use this document as a guide for implementing similar
patterns in their services.
Default roles and behaviors across scopes allow operators to delegate more functionality to their team, auditors, customers, and users without maintaining custom policies.
In addition to admin, member, and reader role, from 2023.2 (Bobcat)
release keystone will provide the service and manager roles by default
as well. Operators can use the service role for service to service API
calls instead of using admin role for the same. The service role will be
separate from admin, member, reader and will not implicate any of
these roles.
Operators can give the manager role to users to within a domain to enable
self-service management of users, groups, projects and role assignments within
their domain.
Roles Definitions¶
The default roles provided by keystone via keystone-manage bootstrap
(except for the service role) are related through role implications. The
admin role implies the manager role, the manager implies the
member role, and the member role implies the reader role. These
implications mean users with the admin role automatically have the
manager, member and reader roles. Additionally, users with the
manager role automatically have the member and reader roles. Users
with the member role automatically have the reader role. Implying roles
reduces role assignments and forms a natural hierarchy between the default
roles. It also reduces the complexity of default policies by making check
strings short. For example, a policy that requires reader can be expressed
as:
"identity:list_foo": "role:reader"
Instead of:
"identity:list_foo": "role:admin or role:manager or role:member or role:reader"
Reader¶
Warning
While it’s possible to use the reader role to perform audits, we highly
recommend assessing the viability of using reader for auditing from the
perspective of the compliance target you’re pursuing.
The reader role is the least-privileged role within the role hierarchy
described here. As such, OpenStack development teams, by default, do not
advocate exposing sensitive information to users with the reader role,
regardless of the scope. We have noted the need for a formal, read-only,
role that is useful for inspecting all applicable resources within a
particular scope, but it shouldn’t be implemented as the lowest level of
authorization. This work will come in a subsequent release where we support
an elevated read-only role, that implies reader, but also exposes
sensitive information, where applicable.
This will allow operators to grant third-party auditors a permissive role for viewing sensitive information, specifically for compliance targets that require it.
The reader role provides read-only access to resources within the system, a
domain, or a project. Depending on the assignment scope, two users with the
reader role can expect different API behaviors. For example, a user with
the reader role on the system can list all projects within the deployment.
A user with the reader role on a domain can only list projects within their
domain.
By analyzing the scope of a role assignment, we increase the re-usability of
the reader role and provide greater functionality without introducing more
roles. For example, to accomplish this without analyzing assignment scope, you
would need system-reader, domain-reader, and project-reader roles
in addition to custom policies for each service.
It’s imperative to note that reader is the least authoritative role in the
hierarchy because assignments using admin or member ultimately include
the reader role. We document this explicitly so that reader roles are not
overloaded with read-only access to sensitive information. For example, a deployment
pursuing a specific compliance target may want to leverage the reader role
to perform the audit. If the audit requires the auditor to evaluate sensitive
information, like license keys or administrative metadata, within a given
scope, auditors shouldn’t expect to perform these operations with the
reader role. We justify this design decision because sensitive information
should be explicitly protected, and not implicitly exposed.
The reader role should be implemented and used from the perspective of
least-privilege, which may or may not fulfill your auditing use case.
Member¶
Within keystone, there isn’t a distinct advantage to having the member role
instead of the reader role. The member role is more applicable to other
services. The member role works nicely for introducing granularity between
admin and reader roles. Other services might write default policies
that require the member role to create resources, but the admin role to
delete them. For example, users with reader on a project could list
instance, users with member on a project can list and create instances, and
users with admin on a project can list, create, and delete instances.
Service developers can use the member role to provide more flexibility
between admin and reader on different scopes.
Manager¶
The manager role takes a special place in keystone. It sits between the
admin and member role, allowing limited identity management while being
clearly differentiated from the admin role both in terms of purpose and
privileges. The manager role is meant to be assigned in a domain scope and
enables users to manage identity assets in a whole domain including users,
projects, groups and role assignments. This enables identity self-service
management capabilities for users within a domain without the need to assign
the most privileged admin role to them.
The keystone default policies include a special rule that specifies the list of
roles a user with the manager role is be able to assign and revoke within
the domain scope. This prevents such user from escalating their own privileges
or those of others beyond manager and for this purpose the list excludes
the admin role. The list can be adjusted by cloud administrators via policy
definitions in case the role model differs. For example, if a new role is
introduced for a specific cloud environment, the list can be adjusted to allow
users with the manager role to also assign it.
Other services might write default policies to enable the manager role to
have more privileged managing rights or cross-project privileges in a domain.
Admin¶
We reserve the admin role for the most privileged operations within a given
scope. It is important to note that having admin on a project, domain, or
the system carries separate authorization and are not transitive. For example,
users with admin on the system should be able to manage every aspect of the
deployment because they’re operators. Users with admin on a project
shouldn’t be able to manage things outside the project because it would violate
the tenancy of their role assignment (this doesn’t apply consistently since
services are addressing this individually at their own pace).
Service¶
We reserve the service role for Service-to-service communication. The aim
of a service role is to allow a service to communicate with another service
and possibly be granted elevated privileges by the service receiving the
request. Before the introduction of the service role, a service had to be
granted the admin role in order to have elevated privileges, which gave a
service powers way beyond what was necessary. With the service role in
place, we can now allow all service-to-service APIs to default to the
service role only. For example, a policy that requires
service can be expressed as:
"identity:create_foo": "role:service"
There might be exception service-to-service APIs which project think are
useful to be used by admin or non-admin user then they can take the
exceptional decision to default them to user role and service role. For
example, a policy that requires service and admin can be expressed as:
"identity:create_foo": "role:service or role:admin"
Note
Unlike the other default roles, the service role is not a member
of a role hierarchy. It is a standalone role.
Note
As of the Train release, keystone applies the following personas consistently across its API.
System Personas¶
This section describes authorization personas typically used for operators and deployers. You can find all users with system role assignments using the following query:
$ openstack role assignment list --names --system all
+--------+------------------------+------------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+------------------------+------------------------+---------+--------+--------+-----------+
| admin | | system-admins@Default | | | all | False |
| admin | admin@Default | | | | all | False |
| admin | operator@Default | | | | all | False |
| reader | | system-support@Default | | | all | False |
| admin | operator@Default | | | | all | False |
| member | system-support@Default | | | | all | False |
+--------+------------------------+------------------------+---------+--------+--------+-----------+
System Administrators¶
System administrators are allowed to manage every resource in keystone. System administrators are typically operators and cloud administrators. They can control resources that ultimately affect the behavior of the deployment. For example, they can add or remove services and endpoints in the catalog, create new domains, add federated mappings, and clean up stale resources, like a user’s application credentials or trusts.
You can find system administrators in your deployment with the following assignments:
$ openstack role assignment list --names --system all --role admin
+-------+------------------+-----------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+-------+------------------+-----------------------+---------+--------+--------+-----------+
| admin | | system-admins@Default | | | all | False |
| admin | admin@Default | | | | all | False |
| admin | operator@Default | | | | all | False |
+-------+------------------+-----------------------+---------+--------+--------+-----------+
System Members & System Readers¶
In keystone, system members and system readers are very similar and have the same authorization. Users with these roles on the system can view all resources within keystone. They can list role assignments, users, projects, and group memberships, among other resources.
The system reader persona is useful for members of a support team or auditors if the audit doesn’t require access to sensitive information. You can find system members and system readers in your deployment with the following assignments:
$ openstack role assignment list --names --system all --role member --role reader
+--------+------------------------+------------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+------------------------+------------------------+---------+--------+--------+-----------+
| reader | | system-support@Default | | | all | False |
| admin | operator@Default | | | | all | False |
| member | system-support@Default | | | | all | False |
+--------+------------------------+------------------------+---------+--------+--------+-----------+
Warning
Filtering system role assignments is currently broken and is being tracked as a bug.
Domain Personas¶
This section describes authorization personas for people who manage their own domains, which contain projects, users, and groups. You can find all users with role assignments on a specific domain using the following query:
$ openstack role assignment list --names --domain foobar
+---------+-----------------+----------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+---------+-----------------+----------------------+---------+--------+--------+-----------+
| reader | support@Default | | | foobar | | False |
| admin | jsmith@Default | | | foobar | | False |
| admin | | foobar-admins@foobar | | foobar | | False |
| manager | alice@foobar | | | foobar | | False |
| member | jdoe@foobar | | | foobar | | False |
+---------+-----------------+----------------------+---------+--------+--------+-----------+
Domain Administrators¶
Domain administrators can manage most aspects of the domain or its contents. These users can create new projects and users within their domain. They can inspect the role assignments users have on projects within their domain.
Domain administrators aren’t allowed to access system-specific resources or resources outside their domain. Users that need control over project, group, and user creation are a great fit for domain administrators.
You can find domain administrators in your deployment with the following role assignment:
$ openstack role assignment list --names --domain foobar --role admin
+-------+----------------+----------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+-------+----------------+----------------------+---------+--------+--------+-----------+
| admin | jsmith@Default | | | foobar | | False |
| admin | | foobar-admins@foobar | | foobar | | False |
+-------+----------------+----------------------+---------+--------+--------+-----------+
Domain Managers¶
Domain managers can only manage specific resources related to identity management within their domain. This includes creating new users, projects and groups as well as updating and deleting them. They can also assign and revoke roles between those or in relation to the domain. Furthermore, they can inspect role assignments within the domain.
Domain managers cannot change any aspects of the domain itself. The role
assignments they can apply within their domain is limited to a specific list of
applicable roles and in the default configuration, this excludes the admin
role to prevent privilege escalation.
You can find domain managers in your deployment with the following role assignment:
$ openstack role assignment list --names --domain foobar --role manager
+---------+-----------------+----------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+---------+-----------------+----------------------+---------+--------+--------+-----------+
| manager | alice@foobar | | | foobar | | False |
+---------+-----------------+----------------------+---------+--------+--------+-----------+
Domain Members & Domain Readers¶
Domain members and domain readers have the same relationship as system members and system readers. They’re allowed to view resources and information about their domain. They aren’t allowed to access system-specific information or information about projects, groups, and users outside their domain.
The domain member and domain reader use-cases are great for support teams, monitoring the details of an account, or auditing resources within a domain assuming the audit doesn’t validate sensitive information. You can find domain members and domain readers with the following role assignments:
$ openstack role assignment list --names --role member --domain foobar
+--------+-------------+-------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+-------------+-------+---------+--------+--------+-----------+
| member | jdoe@foobar | | | foobar | | False |
+--------+-------------+-------+---------+--------+--------+-----------+
$ openstack role assignment list --names --role reader --domain foobar
+--------+-----------------+-------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+-----------------+-------+---------+--------+--------+-----------+
| reader | support@Default | | | foobar | | False |
+--------+-----------------+-------+---------+--------+--------+-----------+
Project Personas¶
This section describes authorization personas for users operating within a project. These personas are commonly used by end users. You can find all users with role assignments on a specific project using the following query:
$ openstack role assignment list --names --project production
+--------+----------------+----------------------------+-------------------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+----------------+----------------------------+-------------------+--------+--------+-----------+
| admin | jsmith@Default | | production@foobar | | | False |
| admin | | production-admins@foobar | production@foobar | | | False |
| member | | foobar-operators@Default | production@foobar | | | False |
| reader | alice@Default | | production@foobar | | | False |
| reader | | production-support@Default | production@foobar | | | False |
+--------+----------------+----------------------------+-------------------+--------+--------+-----------+
Project Administrators¶
Project administrators can only view and modify data within the project they have authorization on. They’re able to view information about their projects and set tags on their projects. They’re not allowed to view system or domain resources, as that would violate the tenancy of their role assignment. Since the majority of the resources in keystone’s API are system and domain-specific, project administrators don’t have much authorization.
You can find project administrators in your deployment with the following role assignment:
$ openstack role assignment list --names --project production --role admin
+-------+----------------+--------------------------+-------------------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+-------+----------------+--------------------------+-------------------+--------+--------+-----------+
| admin | jsmith@Default | | production@foobar | | | False |
| admin | | production-admins@foobar | production@foobar | | | False |
+-------+----------------+--------------------------+-------------------+--------+--------+-----------+
Project Members & Project Readers¶
Project members and project readers can discover information about their projects. They can access important information like resource limits for their project, but they’re not allowed to view information outside their project or view system-specific information.
You can find project members and project readers in your deployment with the following role assignments:
$ openstack role assignment list --names --project production --role member
+--------+------+--------------------------+-------------------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+------+--------------------------+-------------------+--------+--------+-----------+
| member | | foobar-operators@Default | production@foobar | | | False |
+--------+------+--------------------------+-------------------+--------+--------+-----------+
$ openstack role assignment list --names --project production --role reader
+--------+---------------+----------------------------+-------------------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+---------------+----------------------------+-------------------+--------+--------+-----------+
| reader | alice@Default | | production@foobar | | | False |
| reader | | production-support@Default | production@foobar | | | False |
+--------+---------------+----------------------------+-------------------+--------+--------+-----------+
Writing Policies¶
If the granularity provided above doesn’t meet your specific use-case, you can still override policies and maintain them manually. You can read more about how to do that in oslo.policy usage documentation.
