From 22c3f8067ed7e480e5d06c67677a4f60d740a10d Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 14:14:09 -0800 Subject: moved notes from README.rst into docs/architecture.rst --- docs/source/architecture.rst | 228 +++++++++++++++++++++++++++++++------------ docs/source/developing.rst | 14 +++ 2 files changed, 179 insertions(+), 63 deletions(-) (limited to 'docs/source') diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 21d9b895..b308a9e5 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -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. - -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 ---------------- +----- + +The Token service validates and manages Tokens used for authenticating requests +once a user/tenant's credentials have already been verified. + + +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. -Keystone also provides a list of REST API endpoints as a definitive list for -an OpenStack installation. Key concepts include: +Example paste.deploy config (uses $ instead of % to avoid ConfigParser's +interpolation):: -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. + [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 +--------------- -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. +(Not yet implemented.) -Template - A collection of endpoints representing a set of consumable OpenStack - service endpoints. +Another approach to authorization can be action-based, with a mapping of roles +to which capabilities are allowed for that role. For example:: -Components of Keystone ----------------------- + credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']} -Keystone includes a command-line interface which interacts with the Keystone -API for administrating keystone and related services. + # add a policy + policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',)) -* 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 + policy_api.can_haz(('action:nova:add_network',), credentials) -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. diff --git a/docs/source/developing.rst b/docs/source/developing.rst index b19fec24..48ba2873 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -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. -- cgit