Chapter 2. Role Management

2.1. Role Management

OpenStack uses a role-based access control (RBAC) mechanism to manage access to its resources. Roles define which actions users can perform. By default, there are two predefined roles: a member role that gets attached to a tenant, and an administrative role to enable non-admin users to administer the environment. Note that there are abstract levels of permission, and it is possible to create the roles the administrator needs, and configure services adequately.

2.1.1. View Roles

Use the following command to list the available predefined roles.

$ openstack role list
+----------------------------------+---------------+
| ID                               | Name          |
+----------------------------------+---------------+
| 4fd37c2c993a4acab8e1b5896afb8687 | SwiftOperator |
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_      |
| a0f19c1381c54770ae068456c4411d82 | ResellerAdmin |
| ae49e2b796ea4820ac51637be27650d8 | admin         |
+----------------------------------+---------------+

To get details for a specified role, run:

$ openstack role show admin

Example

$ openstack role show admin
+-----------+----------------------------------+
| Field     | Value                            |
+-----------+----------------------------------+
| domain_id | None                             |
| id        | ae49e2b796ea4820ac51637be27650d8 |
| name      | admin                            |
+-----------+----------------------------------+

2.1.2. Create and Assign a Role

As a cloud administrator, you can create and manage roles on the Keystone client using the following set of commands. Each OpenStack deployment must include at least one project, one user, and one role, linked together. However, users can be members of multiple projects. To assign users to multiple projects, create a role and assign that role to a user-project pair. Note that you can create a user and assign a primary project and default role in the dashboard.

Note

Either the name or ID can be used to specify users, roles, or projects.

  1. Create the new-role role:

    $ openstack role create [ROLE_NAME]

    Example

    $ openstack role create new-role
    +-----------+----------------------------------+
    | Field     | Value                            |
    +-----------+----------------------------------+
    | domain_id | None                             |
    | id        | 880c116b6a55464b99ca8d8d8fe26743 |
    | name      | new-role                         |
    +-----------+----------------------------------+

  2. To assign a user to a project, you must assign the role to a user-project pair. To do this, obtain the user, role, and project names or IDs:

    1. List users:

      $ openstack user list
    2. List roles:

      $ openstack role list
    3. List projects:

      $ openstack project list
  3. Assign a role to a user-project pair.

    openstack role add --project [PROJECT_NAME] --user [USER_ID]  [ROLE_ID]

    Example

    In this example, you assign the admin role to the admin user in the demo project:

    $ openstack role add --project demo --user 895e43465b9643b9aa29df0073572bb2  ae49e2b796ea4820ac51637be27650d8
  4. Verify the role assignment for the user admin:

    $ openstack role assignment list --user [USER_ID]  --project [PROJECT_ID]

    Example

    $ openstack role assignment list --user 895e43465b9643b9aa29df0073572bb2 --project demo
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | Role                             | User                             | Group | Project                          | Domain | Inherited |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | ae49e2b796ea4820ac51637be27650d8 | 895e43465b9643b9aa29df0073572bb2 |       | 7efbdc8b4ab448b8b5aeb9fa5898ce23 |        | False     |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+

2.2. Implied Roles and Domain-specific Roles

2.2.1. Implied roles

In OpenStack, access control is enforced by confirming that a user is assigned to a specific role. Until recently, those roles had to be explicitly assigned to either a user, or to a group in which the user was a member. Identity Service (keystone) has now added the concept of implied role assignments: If a user is explicitly assigned to a role, then the user could be implicitly assigned to additional roles as well.

2.2.2. Inference Rules

Implied assignment is managed by role inference rules. An inference rule is written in the form superior implies subordinate. For example, a rule might state that the admin role implies the _member_ role. As a result, a user assigned to admin for a project would implicitly be assigned to the _member_ role as well.

With implied roles, a user’s role assignments are processed cumulatively, allowing the user to inherit the subordinate roles. This result is dependent on an inference rule being created that specifies this outcome.

2.2.2.1. Keystone Configuration

For keystone to observe implied roles, the infer_roles setting must be enabled in /etc/keystone/keystone.conf:

[token]
infer_roles = true

Implied roles are governed by a defined set of inference rules. These rules determine how a role assignment can result in the implied membership of another role. See Section 2.2.3.1, “Demonstration of Implied Roles” for an example.

2.2.3. Prevent Certain Roles From Being Implied

You can prevent certain roles from being implied onto a user. For example, in /etc/keystone/keystone.conf, you can add a ListOpt of roles:

[assignment]
prohibited_implied_role = admin

This will prevent a user from ever being assigned a role implicitly. Instead, the user will need to be explicitly granted access to that role.

2.2.3.1. Demonstration of Implied Roles

This section describes how to create an inference rule, resulting in an implied role. These rules control how one role can imply membership of another. The example rule used in the following procedure will imply that members of the admin role also have _member_ access:

2.2.3.1.1. Assign a Role to the User
  1. Retrieve the ID of a user that will have the _member_ role implied. For example:

    $ openstack user show User1
    +---------------------+----------------------------------+
    | Field               | Value                            |
    +---------------------+----------------------------------+
    | domain_id           | default                          |
    | enabled             | True                             |
    | id                  | ce803dd127c9489199c89ce3b68d39b4 |
    | name                | User1                            |
    | options             | {}                               |
    | password_expires_at | None                             |
    +---------------------+----------------------------------+
  2. Retrieve the ID of the demo project:

    $ openstack project show demo
    +-------------+----------------------------------+
    | Field       | Value                            |
    +-------------+----------------------------------+
    | description | default tenant                   |
    | domain_id   | default                          |
    | enabled     | True                             |
    | id          | 2717ebc905e449b5975449c370edac69 |
    | is_domain   | False                            |
    | name        | demo                             |
    | parent_id   | default                          |
    +-------------+----------------------------------+
  3. Retrieve the ID of the admin role:

    $ openstack role show admin
    +-----------+----------------------------------+
    | Field     | Value                            |
    +-----------+----------------------------------+
    | domain_id | None                             |
    | id        | 9b821b2920544be7a4d8f71fa99fcd35 |
    | name      | admin                            |
    +-----------+----------------------------------+
  4. Give the User1 user admin privileges to the demo project:

    $ openstack role add --user User1 --project demo admin
  5. Confirm the admin role assignment:

    $ openstack role assignment list --user User1 --project demo --effective
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | Role                             | User                             | Group | Project                          | Domain | Inherited |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | 9b821b2920544be7a4d8f71fa99fcd35 | ce803dd127c9489199c89ce3b68d39b4 |       | 2717ebc905e449b5975449c370edac69 |        | False     |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
2.2.3.1.2. Create the Inference Rule

Now that you have granted the admin role to User1, run the following steps to create the inference rule:

  1. First, confirm User1’s current role membership:

    $ openstack role assignment list --user User1 --project demo --effective
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | Role                             | User                             | Group | Project                          | Domain | Inherited |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | 9b821b2920544be7a4d8f71fa99fcd35 | ce803dd127c9489199c89ce3b68d39b4 |       | 2717ebc905e449b5975449c370edac69 |        | False     |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
  2. Retrieve the list of role IDs:

    $ openstack role list
    +----------------------------------+---------------+
    | ID                               | Name          |
    +----------------------------------+---------------+
    | 9b821b2920544be7a4d8f71fa99fcd35 | admin         |
    | 9fe2ff9ee4384b1894a90878d3e92bab | _member_      |
    | ea199fe4293745719c2afd3402ed7b95 | ResellerAdmin |
    | fe8eba5dfd1e4f4a854ad20a150d995e | SwiftOperator |
    +----------------------------------+---------------+
  3. Create the inference rule. These are currently created using curl. This example uses the IDs of the roles returned in the previous step. It also runs the command using the admin_token in keystone.conf:

    source overcloudrc
    export OS_TOKEN=`grep ^admin_token /etc/keystone/keystone.conf | awk -F'=' '{print $2}'`
    curl -X PUT  -H "X-Auth-Token: $OS_TOKEN" -H "Content-type: application/json" $OS_AUTH_URL/roles/9b821b2920544be7a4d8f71fa99fcd35/implies/9fe2ff9ee4384b1894a90878d3e92bab
  4. Review the results using the CLI. In this example, User1 has received implied access to the _member_ role, as indicated by ID 9fe2ff9ee4384b1894a90878d3e92bab:

    source overcloudrc
    # openstack role assignment list --user User1 --project demo --effective
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | Role                             | User                             | Group | Project                          | Domain | Inherited |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
    | 9b821b2920544be7a4d8f71fa99fcd35 | ce803dd127c9489199c89ce3b68d39b4 |       | 2717ebc905e449b5975449c370edac69 |        | False     |
    | 9fe2ff9ee4384b1894a90878d3e92bab | ce803dd127c9489199c89ce3b68d39b4 |       | 2717ebc905e449b5975449c370edac69 |        | False     |
    +----------------------------------+----------------------------------+-------+----------------------------------+--------+-----------+
  5. Review your inference rules using curl:

    source overcloudrc
    export OS_TOKEN=`grep ^admin_token /etc/keystone/keystone.conf | awk -F'=' '{print $2}'`
    curl -s -H "X-Auth-Token: $OS_TOKEN" $OS_AUTH_URL/role_inferences | python -mjson.tool
    {
        "role_inferences": [
            {
                "implies": [
                    {
                        "id": "9fe2ff9ee4384b1894a90878d3e92bab",
                        "links": {
                            "self": "https://osp.lab.local:5000/v3/roles/9fe2ff9ee4384b1894a90878d3e92bab"
                        },
                        "name": "_member_"
                    }
                ],
                "prior_role": {
                    "id": "9b821b2920544be7a4d8f71fa99fcd35",
                    "links": {
                        "self": "https://osp.lab.local:5000/v3/roles/9b821b2920544be7a4d8f71fa99fcd35"
                    },
                    "name": "admin"
                }
            }
        ]
    }

2.2.4. Domain-Specific Roles

Domain-specific roles grant you more granular control when defining rules for roles, allowing the roles to act as aliases for the existing prior roles. Note that you cannot have a global role implying a domain-specific role. As a result, if you list the effective role assignments of a user in a project, the domain-specific roles will not be present.

Domain-specific roles can be created by a user who administers their keystone domain; they do not have to be administrators of the OpenStack deployment. This means that a domain-specific role definition can be limited to a specific domain.

Note

Domain-specific roles cannot be used to scope a token. This can only be done with global roles.

2.2.4.1. Using Domain-Specific Roles

This example describes how to create a domain specific role and review its effect.

  1. Create a domain:

    $ openstack domain create corp01
  2. Create a role that specifies a domain (note that this parameter is distinct from --domain):

    $ openstack role create operators --role-domain domain-corp01