Keystone Architecture¶

Services¶

Keystone is organized as a group of internal services exposed on one or many endpoints. Many of these services are used in a combined fashion by the frontend. For example, an authenticate call will validate user/project credentials with the Identity service and, upon success, create and return a token with the Token service.

Application Construction¶

Keystone is an HTTP front-end to several services. Since the Rocky release Keystone uses the Flask-RESTful library to provide a REST API interface to these services.

Keystone defines functions related to Flask-RESTful in keystone.server.flask.common. Keystone creates API resources which inherit from class keystone.server.flask.common.ResourceBase and exposes methods for each supported HTTP methods GET, PUT , POST, PATCH and DELETE. For example, the User resource will look like:

class UserResource(ks_flask.ResourceBase):
    collection_key = 'users'
    member_key = 'user'
    get_member_from_driver = PROVIDERS.deferred_provider_lookup(
        api='identity_api', method='get_user')

    def get(self, user_id=None):
        """Get a user resource or list users.
        GET/HEAD /v3/users
        GET/HEAD /v3/users/{user_id}
        """
        ...

    def post(self):
        """Create a user.
        POST /v3/users
        """
        ...

class UserChangePasswordResource(ks_flask.ResourceBase):
    @ks_flask.unenforced_api
     def post(self, user_id):
         ...

Routes for each API resource are defined by classes which inherit from keystone.server.flask.common.APIBase. For example, the UserAPI will look like:

class UserAPI(ks_flask.APIBase):
    _name = 'users'
    _import_name = __name__
    resources = [UserResource]
    resource_mapping = [
        ks_flask.construct_resource_map(
            resource=UserChangePasswordResource,
            url='/users/<string:user_id>/password',
            resource_kwargs={},
            rel='user_change_password',
            path_vars={'user_id': json_home.Parameters.USER_ID}
        ),
     ...

The methods _add_resources() or _add_mapped_resources() in keystone.server.flask.common.APIBase bind the resources with the APIs. Within each API, one or more managers are loaded (for example, see keystone.catalog.core.Manager), which are thin wrapper classes which load the appropriate service driver based on the keystone configuration.

• Assignment

  • keystone.api.role_assignments

  • keystone.api.role_inferences

  • keystone.api.roles

  • keystone.api.os_inherit

  • keystone.api.system

• Authentication

  • keystone.api.auth

  • keystone.api.ec2tokens

  • keystone.api.s3tokens

• Catalog

  • keystone.api.endpoints

  • keystone.api.os_ep_filter

  • keystone.api.regions

  • keystone.api.services

• Credentials

  • keystone.api.credentials

• Federation

  • keystone.api.os_federation

• Identity

  • keystone.api.groups

  • keystone.api.users

• Limits

  • keystone.api.registered_limits

  • keystone.api.limits

• Oauth1

  • keystone.api.os_oauth1

• Policy

  • keystone.api.policy

• Resource

  • keystone.api.domains

  • keystone.api.projects

• Revoke

  • keystone.api.os_revoke

• Trust

  • keystone.api.trusts

Service Backends¶

Each of the services can be configured to use a backend to allow keystone to fit a variety of environments and needs. The backend for each service is defined in the keystone.conf file with the key driver under a group associated with each service.

A general class exists under each backend to provide an abstract base class for any implementations, identifying the expected service implementations. The abstract base classes are stored in the service’s backends directory as base.py. The corresponding drivers for the services are:

• keystone.assignment.backends.base.AssignmentDriverBase

• keystone.assignment.role_backends.base.RoleDriverBase

• keystone.auth.plugins.base.AuthMethodHandler

• keystone.catalog.backends.base.CatalogDriverBase

• keystone.credential.backends.base.CredentialDriverBase

• keystone.endpoint_policy.backends.base.EndpointPolicyDriverBase

• keystone.federation.backends.base.FederationDriverBase

• keystone.identity.backends.base.IdentityDriverBase

• keystone.identity.mapping_backends.base.MappingDriverBase

• keystone.identity.shadow_backends.base.ShadowUsersDriverBase

• keystone.oauth1.backends.base.Oauth1DriverBase

• keystone.policy.backends.base.PolicyDriverBase

• keystone.resource.backends.base.ResourceDriverBase

• keystone.resource.config_backends.base.DomainConfigDriverBase

• keystone.revoke.backends.base.RevokeDriverBase

• keystone.token.providers.base.Provider

• keystone.trust.backends.base.TrustDriverBase

If you implement a backend driver for one of the keystone services, you’re expected to subclass from these classes.

[DEFAULT]
catalog.RegionOne.identity.publicURL = http://localhost:$(public_port)s/v3
catalog.RegionOne.identity.adminURL = http://localhost:$(public_port)s/v3
catalog.RegionOne.identity.internalURL = http://localhost:$(public_port)s/v3
catalog.RegionOne.identity.name = 'Identity Service'

Data Model¶

Keystone was designed from the ground up to be amenable to multiple styles of backends. As such, many of the methods and data types will happily accept more data than they know what to do with and pass them on to a backend.

There are a few main data types:

• User: has account credentials, is associated with one or more projects or domains

• Group: a collection of users, is associated with one or more projects or domains

• Project: unit of ownership in OpenStack, contains one or more users

• Domain: unit of ownership in OpenStack, contains users, groups and projects

• Role: a first-class piece of metadata associated with many user-project pairs.

• Token: identifying credential associated with a user or user and project

• Extras: bucket of key-value metadata associated with a user-project pair.

• Rule: describes a set of requirements for performing an action.

While the general data model allows a many-to-many relationship between users and groups to projects and domains; the actual backend implementations take varying levels of advantage of that functionality.

Approach to CRUD¶

While it is expected that any “real” deployment at a large company will manage their users and groups in their existing user systems, a variety of CRUD operations are provided for the sake of development and testing.

CRUD is treated as an extension or additional feature to the core feature set, in that a backend is not required to support it. It is expected that backends for services that don’t support the CRUD operations will raise a keystone.exception.NotImplemented.

Approach to Authorization (Policy)¶

Various components in the system require that different actions are allowed based on whether the user is authorized to perform that action.

For the purposes of keystone there are only a couple levels of authorization being checked for:

• Require that the performing user is considered an admin.

• Require that the performing user matches the user being referenced.

Other systems wishing to use the policy engine will require additional styles of checks and will possibly write completely custom backends. By default, keystone leverages policy enforcement that is maintained in oslo.policy.

credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']}

# An admin only call:
policy_api.enforce(('is_admin:1',), credentials)

# An admin or owner call:
policy_api.enforce(('is_admin:1', 'user_id:foo'), credentials)

# A netadmin call:
policy_api.enforce(('roles:nova:netadmin',), credentials)

credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']}

# add a policy
policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',))

policy_api.enforce(('action:nova:add_network',), credentials)

Approach to Authentication¶

Keystone provides several authentication plugins that inherit from keystone.auth.plugins.base. The following is a list of available plugins.

• keystone.auth.plugins.external.Base

• keystone.auth.plugins.mapped.Mapped

• keystone.auth.plugins.oauth1.OAuth

• keystone.auth.plugins.password.Password

• keystone.auth.plugins.token.Token

• keystone.auth.plugins.totp.TOTP

In the most basic plugin password, two pieces of information are required to authenticate with keystone, a bit of Resource information and a bit of Identity.

Take the following call POST data for instance:

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "0ca8f6",
                    "password": "secretsecret"
                }
            }
        },
        "scope": {
            "project": {
                "id": "263fd9"
            }
        }
    }
}

The user (ID of 0ca8f6) is attempting to retrieve a token that is scoped to project (ID of 263fd9).

To perform the same call with names instead of IDs, we now need to supply information about the domain. This is because usernames are only unique within a given domain, but user IDs are supposed to be unique across the deployment. Thus, the auth request looks like the following:

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "domain": {
                        "name": "acme"
                    }
                    "name": "userA",
                    "password": "secretsecret"
                }
            }
        },
        "scope": {
            "project": {
                "domain": {
                    "id": "1789d1"
                },
                "name": "project-x"
            }
        }
    }
}

For both the user and the project portion, we must supply either a domain ID or a domain name, in order to properly determine the correct user and project.

Alternatively, if we wanted to represent this as environment variables for a command line, it would be:

$ export OS_PROJECT_DOMAIN_ID=1789d1
$ export OS_USER_DOMAIN_NAME=acme
$ export OS_USERNAME=userA
$ export OS_PASSWORD=secretsecret
$ export OS_PROJECT_NAME=project-x

Note that the project the user is attempting to access must be in the same domain as the user.