From cddbde13847297ad59bfdcde6e58755af525bb19 Mon Sep 17 00:00:00 2001 From: Dolph Mathews Date: Thu, 19 Sep 2013 10:23:24 -0500 Subject: [PATCH] Rewrite README.rst Most of the content in the README is unmaintained and out of date, and can be replaced by references to documentation that *is* more properly maintained. This patch replaces most of the contents of the README with low maintenance links. Fixes-Bug: 1227734 Change-Id: I4d63d971f94329197bd7001682d0d655901457f0 --- README.rst | 223 ++++++------------------------------------------- doc/README.rst | 9 ++ 2 files changed, 36 insertions(+), 196 deletions(-) create mode 100644 doc/README.rst diff --git a/README.rst b/README.rst index 9e7e8ce8aa..cb32e1350b 100644 --- a/README.rst +++ b/README.rst @@ -1,216 +1,47 @@ -======== -Keystone -======== +================== +OpenStack Keystone +================== -Keystone is an OpenStack project that provides Identity, Token, Catalog and -Policy services for use specifically by projects in the OpenStack family. +Keystone provides authentication, authorization and service discovery +mechanisms via HTTP primarily for use by projects in the OpenStack family. It +is most commonly deployed as an HTTP interface to existing identity systems, +such as LDAP. -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. +Developer documentation, the source of which is in ``doc/source/``, is +published at: + http://keystone.openstack.org/ ------------ -Development ------------ +The API specification is available at: + https://github.com/openstack/identity-api -Setting up a development environment ------------------------------------- +The API documentation is available at: -Please see the documentation under ``doc/source/`` for development setup -(``doc/source/setup.rst``) and configuration -(``doc/source/configuration.rst``). + http://api.openstack.org/api-ref-identity.html +The canonical client library is available at: -Building the Documentation --------------------------- + https://github.com/openstack/python-keystoneclient -The documentation is all generated with Sphinx from within the doc directory. -To generate the full set of HTML documentation:: +Documentation for cloud administrators is available at: - tox -evenv python setup.py build_sphinx + http://docs.openstack.org/ -the results are in the ``doc/build/html`` and ``doc/build/man`` directories -respectively. +The source of documentation for cloud administrators is available at: + https://github.com/openstack/openstack-manuals ------------- -The Services ------------- +Information about our team meeting is available at: -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. + https://wiki.openstack.org/wiki/Meetings/KeystoneMeeting +Bugs and feature requests are tracked on Launchpad at: -Identity --------- + https://bugs.launchpad.net/keystone -The Identity service provides auth credential validation and data about Users, -Tenants and Roles, as well as any associated metadata. +Future design work is tracked at: -In the basic case all this data is managed by the service, allowing the service -to manage all the CRUD associated with the data. + https://blueprints.launchpad.net/keystone -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. - - -Token ------ - -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. - -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 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 are: - - -Rules ------ - -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.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 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 ---------------- - -(Not yet implemented.) - -Another approach to authorization can be action-based, with a mapping of roles -to which capabilities are allowed for that role. For example:: - - 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) - - -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. - - ----------------------------------- -Dependencies ----------------------------------- - -Ensure an OpenSSL version of 1.0+ is installed. +For information on contributing to Keystone, see ``CONTRIBUTING.rst``. diff --git a/doc/README.rst b/doc/README.rst new file mode 100644 index 0000000000..50a0a3ea3e --- /dev/null +++ b/doc/README.rst @@ -0,0 +1,9 @@ +Building Docs +============= + +Developer documentation is generated using Sphinx. To build this documentation, +run the following from the root of the repository:: + + $ python setup.py build_sphinx + +The documentation will be built at ``doc/build/``.