Doc: Improve service token

This patch extends a bit the documentation for the service token
configuration, since there have been complains about its clarity and
completeness.

Related-Bug: #2004555
Change-Id: Id89497d068c1644e4615fc0fb85c4d1a139ecc19
This commit is contained in:
Gorka Eguileor 2023-05-17 13:42:41 +02:00
parent 456b6399be
commit 1101402b8f

View File

@ -2,6 +2,15 @@
Using service tokens Using service tokens
==================== ====================
.. warning::
For all OpenStack releases after 2023-05-10, it is **required** that Nova be
configured to send a service token to Cinder and Cinder to receive it. This
is required by the fix for `CVE-2023-2088
<https://nvd.nist.gov/vuln/detail/CVE-2023-2088>`_. See
`OSSA-2023-003 <https://security.openstack.org/ossa/OSSA-2023-003.html>`_
for details.
When a user initiates a request whose processing involves multiple services When a user initiates a request whose processing involves multiple services
(for example, a boot-from-volume request to the Compute Service will require (for example, a boot-from-volume request to the Compute Service will require
processing by the Block Storage Service, and may require processing by the processing by the Block Storage Service, and may require processing by the
@ -52,33 +61,123 @@ the user:
Configuration Configuration
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
To configure Cinder to send a "service token" along with the user's To configure an OpenStack service that supports Service Tokens, like Nova and
token when it makes a request to another service, you must do the Cinder, to send a "service token" along with the user's token when it makes a
following: request to another service, you must do the following:
1. Find the ``[service_user]`` section in the Cinder configuration 1. Configure the "sender" services to send the token when calling other
file (usually ``/etc/cinder/cinder.conf``, though it may be in a OpenStack services.
different location in your installation). 2. Configure each service's user to have a service role in Keystone.
3. Configure the "receiver" services to expect the token and validate it
appropriately on reception.
2. In that section, set ``send_service_user_token = true``. Send service token
^^^^^^^^^^^^^^^^^^
3. Also in that section, fill in the appropriate configuration for To send the token we need to add to our configuration file the
your service user (``username``, ``project_name``, etc.) ``[service_user]`` section and fill it in with the appropriate configuration
for your service user (``username``, ``project_name``, etc.) and set the
``send_service_user_token`` option to ``true`` to tell the service to send the
token.
4. If Cinder is going to receive service tokens from other services The configuration for the service user is basically the normal keystone user
it needs to have two options configured in the configuration like we would have in the ``[keystone_authtoken]`` section, but
``[keystone_authtoken]`` section of the configuration file: without the 2 configuration options we'll see in one of the next subsection to
configure the reception of service tokens.
``service_token_roles`` In most cases we would use the same user we do in ``[keystone_authtoken]``, for
The value is a list of roles; the service user passing the service example for the nova configuration we would have something like this:
token must have at least one of these roles or the token will be
rejected. The default value is ``service``.
``service_token_roles_required`` .. code-block:: ini
This is a boolean; the default value is ``False``. It governs whether
the keystone middleware used by the receiving service will pay any [service_user]
attention to the ``service_token_roles`` setting. It should be set send_service_user_token = True
to ``True``.
# Copy following options from [keystone_authtoken] section
project_domain_name = Default
project_name = service
user_domain_name = Default
password = abc123
username = nova
auth_url = http://192.168.121.66/identity
auth_type = password
Service role
^^^^^^^^^^^^
A service role is nothing more than a Keystone role that allows a deployment to
identify a service without the need to make them admins, that way there is no
change in the privileges but we are able to identify that the request is
coming from another service and not a user.
The default service role is ``service``, but we can use a different name or
even have multiple service roles. For simplicity's sake we recommend having
just one, ``service``.
We need to make sure that the user configured in the ``[service_user]`` section
for a project has a service role.
Assuming our users are ``nova`` and ``cinder`` from the ``service`` project and
the service role is going to be the default ``service``, we first check
`if the role exists or not
<https://docs.openstack.org/keystone/latest/admin/cli-manage-projects-users-and-roles.html#view-role-details>`_:
.. code-block:: bash
$ openstack role show service
If it doesn't, we need `to create it
<https://docs.openstack.org/keystone/latest/admin/cli-manage-projects-users-and-roles.html#create-a-role>`_
.. code-block:: bash
$ openstack role create service
Check if the users have the roles assigned or not:
.. code-block:: bash
$ openstack role assignment list --user cinder --project service --names
$ openstack role assignment list --user nova --project service --names
And if they are not we `assign the role to those users
<https://docs.openstack.org/keystone/latest/admin/cli-manage-projects-users-and-roles.html#assign-a-role>`_
.. code-block:: bash
$ openstack role add --user cinder --project service service
$ openstack role add --user nova --project service service
More information on creating service users can be found in `the Keystone
documentation <https://docs.openstack.org/keystone/latest/admin/manage-services.html>`_
Receive service token
^^^^^^^^^^^^^^^^^^^^^
Now we need to make the services validate the service token on reception, this
part is crucial.
The 2 configuration options in ``[keystone_authoken]`` related to receiving
service tokens are ``service_token_roles`` and
``service_token_roles_required``.
The ``service_token_roles`` contains a list of roles that we consider to belong
to services. The service user must belong to at least one of them to be
considered a valid service token. The value defaults to ``service``, so we
don't need to set it if that's the value we are using.
Now we need to tell the keystone middleware to actually validate the service
token and confirm that it's not only a valid token, but that it has one of the
roles set in ``service_token_roles``. We do this by setting
``service_token_roles_required`` to ``true``.
So we would have something like this in our ``[keystone_authtoken]`` section:
.. code-block:: ini
[keystone_authtoken]
service_token_roles = service
service_token_roles_required = true
.. _service-token-troubleshooting: .. _service-token-troubleshooting:
@ -96,7 +195,7 @@ Identity Service (Keystone).
section above. section above.
.. note:: .. note::
As of the Train release, Glance does not have the ability to pass As of the 2023.1 release, Glance does not have the ability to pass
service tokens. It can receive them, though. The place where you may service tokens. It can receive them, though. The place where you may
still see a long running failure is when Glance is using a backend that still see a long running failure is when Glance is using a backend that
requires Keystone validation (for example, the Swift backend) and the requires Keystone validation (for example, the Swift backend) and the