moved notes from README.rst into docs/architecture.rst
This commit is contained in:
Joe Heck
@@ -20,82 +20,184 @@ Keystone Architecture
|
||||
Much of the design is precipitated from the expectation that the auth backends
|
||||
for most deployments will actually be shims in front of existing user systems.
|
||||
|
||||
.........JOEEDIT..........
|
||||
Keystone has two major components: Authentication and a Service Catalog.
|
||||
------------
|
||||
The Services
|
||||
------------
|
||||
|
||||
Authentication
|
||||
--------------
|
||||
Keystone is organized as a group of 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/tenant credentials with the
|
||||
Identity service and, upon success, create and return a token with the Token
|
||||
service.
|
||||
|
||||
In providing a token-based authentication service for OpenStack, keystone
|
||||
has several major concepts:
|
||||
|
||||
Tenant
|
||||
A grouping used in OpenStack to contain relevant OpenStack services. A
|
||||
tenant maps to a Nova "project-id", and in object storage, a tenant can
|
||||
have multiple containers. Depending on the installation, a tenant can
|
||||
represent a customer, account, organization, or project.
|
||||
Identity
|
||||
--------
|
||||
|
||||
User
|
||||
Represents an individual within OpenStack for the purposes of
|
||||
authenticating them to OpenStack services. Users have credentials, and may
|
||||
be assigned to one or more tenants. When authenticated, a token is
|
||||
provided that is specific to a single tenant.
|
||||
The Identity service provides auth credential validation and data about Users,
|
||||
Tenants and Roles, as well as any associated metadata.
|
||||
|
||||
In the basic case all this data is managed by the service, allowing the service
|
||||
to manage all the CRUD associated with the data.
|
||||
|
||||
In other cases, this data is pulled, by varying degrees, from an authoritative
|
||||
backend service. An example of this would be when backending on LDAP. See
|
||||
`LDAP Backend` below for more details.
|
||||
|
||||
Credentials
|
||||
Password or other information that uniquely identifies a User to Keystone
|
||||
for the purposes of providing a token.
|
||||
|
||||
Token
|
||||
A token is an arbitrary bit of text that is used to share authentication
|
||||
with other OpenStack services so that Keystone can provide a central
|
||||
location for authenticating users for access to OpenStack services. A
|
||||
token may be "scoped" or "unscoped". A scoped token represents a user
|
||||
authenticated to a Tenant, where an unscoped token represents just the
|
||||
user.
|
||||
-----
|
||||
|
||||
Tokens are valid for a limited amount of time and may be revoked at any
|
||||
time.
|
||||
The Token service validates and manages Tokens used for authenticating requests
|
||||
once a user/tenant's credentials have already been verified.
|
||||
|
||||
Role
|
||||
A role is a set of permissions to access and use specific operations for
|
||||
a given user when applied to a tenant. Roles are logical groupings of
|
||||
those permissions to enable common permissions to be easily grouped and
|
||||
bound to users associated with a given tenant.
|
||||
|
||||
Service Catalog
|
||||
Catalog
|
||||
-------
|
||||
|
||||
The Catalog service provides an endpoint registry used for endpoint discovery.
|
||||
|
||||
|
||||
Policy
|
||||
------
|
||||
|
||||
The Policy service provides a rule-based authorization engine and the
|
||||
associated rule management interface.
|
||||
|
||||
----------
|
||||
Data Model
|
||||
----------
|
||||
|
||||
Keystone was designed from the ground up to be amenable to multiple styles of
|
||||
backends and 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 tenants
|
||||
* **Tenant**: unit of ownership in openstack, contains one or more users
|
||||
* **Role**: a first-class piece of metadata associated with many user-tenant pairs.
|
||||
* **Token**: identifying credential associated with a user or user and tenant
|
||||
* **Extras**: bucket of key-value metadata associated with a user-tenant 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 Tenants and a many-to-one relationship between Extras and User-Tenant pairs,
|
||||
the actual backend implementations take varying levels of advantage of that
|
||||
functionality.
|
||||
|
||||
|
||||
KVS Backend
|
||||
-----------
|
||||
|
||||
A simple backend interface meant to be further backended on anything that can
|
||||
support primary key lookups, the most trivial implementation being an in-memory
|
||||
dict.
|
||||
|
||||
Supports all features of the general data model.
|
||||
|
||||
|
||||
PAM Backend
|
||||
-----------
|
||||
|
||||
Extra simple backend that uses the current system's PAM service to authenticate,
|
||||
providing a one-to-one relationship between Users and Tenants with the `root`
|
||||
User also having the 'admin' role.
|
||||
|
||||
|
||||
Templated Backend
|
||||
-----------------
|
||||
|
||||
Largely designed for a common use case around service catalogs in the Keystone
|
||||
project, a Catalog backend that simply expands pre-configured templates to
|
||||
provide catalog data.
|
||||
|
||||
Example paste.deploy config (uses $ instead of % to avoid ConfigParser's
|
||||
interpolation)::
|
||||
|
||||
[DEFAULT]
|
||||
catalog.RegionOne.identity.publicURL = http://localhost:$(public_port)s/v2.0
|
||||
catalog.RegionOne.identity.adminURL = http://localhost:$(public_port)s/v2.0
|
||||
catalog.RegionOne.identity.internalURL = http://localhost:$(public_port)s/v2.0
|
||||
catalog.RegionOne.identity.name = 'Identity Service'
|
||||
|
||||
|
||||
----------------
|
||||
Approach to CRUD
|
||||
----------------
|
||||
|
||||
While it is expected that any "real" deployment at a large company will manage
|
||||
their users, tenants and other metadata 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 it is not required that a backend support it.
|
||||
|
||||
|
||||
----------------------------------
|
||||
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 Light 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. Backends included
|
||||
in Keystone Light are:
|
||||
|
||||
|
||||
Trivial True
|
||||
------------
|
||||
|
||||
Allows all actions.
|
||||
|
||||
|
||||
Simple Match
|
||||
------------
|
||||
|
||||
Given a list of matches to check for, simply verify that the credentials
|
||||
contain the matches. For example::
|
||||
|
||||
credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']}
|
||||
|
||||
# An admin only call:
|
||||
policy_api.can_haz(('is_admin:1',), credentials)
|
||||
|
||||
# An admin or owner call:
|
||||
policy_api.can_haz(('is_admin:1', 'user_id:foo'),
|
||||
credentials)
|
||||
|
||||
# A netadmin call:
|
||||
policy_api.can_haz(('roles:nova:netadmin',),
|
||||
credentials)
|
||||
|
||||
|
||||
Credentials are generally built from the user metadata in the 'extras' part
|
||||
of the Identity API. So, adding a 'role' to the user just means adding the role
|
||||
to the user metadata.
|
||||
|
||||
|
||||
Capability RBAC
|
||||
---------------
|
||||
|
||||
Keystone also provides a list of REST API endpoints as a definitive list for
|
||||
an OpenStack installation. Key concepts include:
|
||||
(Not yet implemented.)
|
||||
|
||||
Service
|
||||
An OpenStack service such as nova, swift, glance, or keystone. A service
|
||||
may have one of more endpoints through which users can interact with
|
||||
OpenStack services and resources.
|
||||
Another approach to authorization can be action-based, with a mapping of roles
|
||||
to which capabilities are allowed for that role. For example::
|
||||
|
||||
Endpoint
|
||||
A network accessible address (typically a URL) that represents the API
|
||||
interface to an OpenStack service. Endpoints may also be grouped into
|
||||
templates which represent a group of consumable OpenStack services
|
||||
available across regions.
|
||||
credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']}
|
||||
|
||||
Template
|
||||
A collection of endpoints representing a set of consumable OpenStack
|
||||
service endpoints.
|
||||
# add a policy
|
||||
policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',))
|
||||
|
||||
Components of Keystone
|
||||
----------------------
|
||||
policy_api.can_haz(('action:nova:add_network',), credentials)
|
||||
|
||||
Keystone includes a command-line interface which interacts with the Keystone
|
||||
API for administrating keystone and related services.
|
||||
|
||||
* keystone - runs both keystone-admin and keystone-service
|
||||
* keystone-admin - the administrative API for manipulating keystone
|
||||
* keystone-service - the user oriented API for authentication
|
||||
* keystone-manage - the command line interface to manipulate keystone
|
||||
|
||||
Keystone also includes WSGI middelware to provide authentication support
|
||||
for Nova and Swift.
|
||||
|
||||
Keystone uses a built-in SQLite datastore - and may use an external LDAP
|
||||
service to authenticate users instead of using stored credentials.
|
||||
In the backend this would look up the policy for 'action:nova:add_network' and
|
||||
then do what is effectively a 'Simple Match' style match against the creds.
|
||||
|
||||
@@ -107,3 +107,17 @@ or the `OpenStack Integration Testing Project`_.
|
||||
.. _devstack: http://devstack.org/
|
||||
.. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci
|
||||
.. _OpenStack Integration Testing Project: https://github.com/openstack/tempest
|
||||
|
||||
Building the Documentation
|
||||
==========================
|
||||
|
||||
The documentation is all generated with Sphinx from within the docs directory.
|
||||
To generate the full set of HTML documentation:
|
||||
|
||||
cd docs
|
||||
make autodoc
|
||||
make html
|
||||
make man
|
||||
|
||||
the results are in the docs/build/html and docs/build/man directories
|
||||
respectively.
|
||||
|
||||
Reference in New Issue
Block a user