Keystone Authentication

Searchlight should be integrated with keystone. Setting this up is relatively straightforward, as the keystone distribution includes the necessary middleware. Once you have installed keystone and edited your configuration files, users will need to have an authenticated keystone token in all API requests. The keystone integration will allow both active denial of requests from unauthenticated users and will also allow proper search result filtering.

Danger

If the API is not configured with keystone, all data indexed by searchlight is at risk of being accessed by unauthorized users.

Configuring the searchlight services to use keystone

Keystone is integrated with searchlight through the use of middleware. The default configuration files for the Searchlight API use a single piece of middleware called unauthenticated-context, which generates a request context containing blank authentication information. In order to configure Searchlight to use Keystone, the authtoken and context middleware must be deployed in place of the unauthenticated-context middleware. The authtoken middleware performs the authentication token validation and retrieves actual user authentication information. It can be found in the keystone distribution. For more information, please refer to the Keystone documentation on the auth_token middleware: https://docs.openstack.org/keystonemiddleware/latest/middlewarearchitecture.html

api-paste.ini

First, ensure that declarations for the middleware exist in the api-paste.ini file. Here is an example for authtoken:

[pipeline:searchlight-keystone]
pipeline = authtoken context rootapp

[filter:authtoken]
paste.filter_factory = keystonemiddleware.auth_token:filter_factory
delay_auth_decision = true

searchlight.conf

You must then update the main searchlight.conf configuration file to enable the keystone application pipeline.

Set flavor to keystone in the paste_deploy group:

[paste_deploy]
flavor = keystone

Set keystone_authtoken options. The following sets the searchlight service user as the user for performing policy API authentication checks. The actual options and values in this section will need to be set according to your environment:

[keystone_authtoken]
auth_url = http://127.0.0.1:5000
auth_type = password
project_domain_id = default
project_name = service
user_domain_id = default
password = <SERVICE_PASSWORD>
username = searchlight

Note

For development and unit testing, it is recommended to also set revocation_cache_timeout = 10 under the keystone_authtoken group.

Set service_credentials options. Searchlight plugins may make API calls to other services to index their data. Prior to doing this, it will get a valid token based on the integration account credentials:

[service_credentials]
# These are needed to make API calls to other services when indexing
auth_type = password
username = searchlight
password = <SERVICE_PASSWORD>
user_domain_id = default
project_domain_id = default
project_name = service
auth_url = http://127.0.0.1:5000

# If resource_plugin.include_region_name is set, this value will be
# the default value for the 'region_name' field on all documents
# os_region_name =

For keystone v2 development:

[service_credentials]
auth_type = v2password
username = searchlight
tenant_name = service
password = <SERVICE_PASSWORD>
auth_url = http://127.0.0.1:35357/v2.0

# If resource_plugin.include_region_name is set, this value will be
# the default value for the 'region_name' field on all documents
# os_region_name =

Service integration account

Some of the above configuration implicitly uses a searchlight service user. If you intend to use this user, it must have been created and registered with keystone. Typically, this is done with the following commands (v3 keystone):

$ openstack project create --or-show service --property domain=default
$ openstack user create searchlight --password <SERVICE_PASSWORD> --project service
$ openstack role add admin --project service --user searchlight

For more information on keystone service accounts, see:

https://docs.openstack.org/keystone/latest/admin/manage-services.html#create-service-users

Policy restriction

Searchlight uses the oslo policy library to allow control over the level of access a user has based on their authenticated roles. Policy rules are defined in a configuration file (by default, etc/policy.json). By default, all operations are allowed.

https://docs.openstack.org/oslo.policy/latest/reference/index.html rule formatting.

During the last few cycles concerns were raised about the scope of the admin role within OpenStack. Many services consider any token scoped with the admin role to have access to resources within any project. With the introduction of keystone v3 it is possible to create users with the admin role on a particular project, but not with the intention of them seeing resources in other projects.

Keystone added two configuration options called admin_project_name and admin_project_domain_name to attempt to address this. If a request is authenticated against a the project whose name is admin_project_name in the admin_project_domain_name domain, a flag is set on the authentication response headers indicating that the user is authenticated against the administrative project. This can then be supported by the policy rule (in Searchlight’s policy.json):

"is_admin_context": "role:admin and is_admin_project:True"

Since devstack configures keystone to support those options, this is the default in Searchlight. To maintain backwards compatibility, if your keystone is not configured to set these options, any token with the admin role will be assumed to have administrative powers (this approach has been taken by other OpenStack services).

For more history see https://bugs.launchpad.net/keystone/+bug/968696.

Access to operations

It is possible to restrict access to functionality by setting rules for query, facets or plugins_info. For instance, to restrict facet listing to administrators and disable plugin information for all users:

"facets": "role:admin",
"plugins_info": "!"

Where a request is disallowed on this basis, the user will receive a 403 Forbidden response.

Note that policy rules are applied on the fly; no server restart is required. Policy rules denying access to operations take precedence over the per-resource access described below.

Access to resources

It is possible to disable access to individual plugins. For instance, the following restricts access to Nova servers to admins, and disables access entirely to Glance images:

"resource:OS::Nova::Server": "role:admin",
"resource:OS::Glance::Image": "!",

Note

At current plugins still apply RBAC separately from policy rules. We aim to bring the two closer together in a later patch.

When resources are restricted in this way resources will be excluded from the search (which may result in empty search results). No Forbidden response will be returned.

Service policy controls

If configured, Searchlight can consult service policy files (e.g. that used to configure the nova API). Each resource is configured with a policy target it will check if possible. Policy file paths can either be absolute or relative to service_policy_path (which itself can be relative to the current working directory or left blank). The actual filepath used will be determined by oslo.config using the same logic as for other config files (for logging, searchlight’s policy file etc). With the following configuration stanza:

[service_policies]
service_policy_files=compute:nova-policy.json
service_policy_path=/etc/searchlight/

And with the following contents in nova-policy.json (which might be a symlink to an existing nova policy file, a copy or a separate file):

{
    "is_admin": "role: admin",
    "os_compute_api:servers:index": "rule:is_admin"
}

Only requests with the admin role assigned will be allowed to search or facet Nova servers.

Policy files are configured per service, not per resource type. If files are in different directories absolute paths should be used, and service_policy_path left unset.

Note

Policy rules are always more restrictive. If a rule in Searchlight’s policy.json would allow access but a service policy file would disallow it (or vice versa), the more restrictive rule will be used.