From b802ae0d1f234b507d016d2c08aef3f9da8ca2d4 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 14 Mar 2012 17:12:22 +0000 Subject: updating docs to include creating service accts and some general doc cleanup Change-Id: I745e636391f72dce9c142e399f46c0eb586aba8b --- doc/source/configuringservices.rst | 86 ++++++++++-- doc/source/index.rst | 2 +- doc/source/middleware_architecture.rst | 230 --------------------------------- doc/source/middlewarearchitecture.rst | 230 +++++++++++++++++++++++++++++++++ 4 files changed, 303 insertions(+), 245 deletions(-) delete mode 100644 doc/source/middleware_architecture.rst create mode 100644 doc/source/middlewarearchitecture.rst (limited to 'doc') diff --git a/doc/source/configuringservices.rst b/doc/source/configuringservices.rst index b8911570..c8e2f6b0 100644 --- a/doc/source/configuringservices.rst +++ b/doc/source/configuringservices.rst @@ -38,7 +38,7 @@ In general: The middleware will pass those data down to the service as headers. More details on the architecture of that setup is described in -:doc:`middleware_architecture` +:doc:`middlewarearchitecture` Setting up credentials ====================== @@ -51,25 +51,74 @@ need to define an authorization token. This is configured in ``keystone.conf`` file under the section ``[DEFAULT]``. In the sample file provided with the keystone project, the line defining this token is - [DEFAULT] - admin_token = ADMIN + [DEFAULT] + admin_token = ADMIN This configured token is a "shared secret" between keystone and other -openstack services (for example: nova, swift, glance, or horizon), and will -need to be set the same between those services in order for keystone services -to function correctly. +openstack services, and is used by the client to communicate with the API to +create tenants, users, roles, etc. Setting up tenants, users, and roles ------------------------------------ You need to minimally define a tenant, user, and role to link the tenant and user as the most basic set of details to get other services authenticating -and authorizing with keystone. See doc:`configuration` for a walk through on -how to create tenants, users, and roles. +and authorizing with keystone. + +You will also want to create service users for nova, glance, swift, etc. to +be able to use to authenticate users against keystone. The ``auth_token`` +middleware supports using either the shared secret described above as +`admin_token` or users for each service. + +See doc:`configuration` for a walk through on how to create tenants, users, +and roles. Setting up services =================== +Creating Service Users +---------------------- + +To configure the OpenStack services with service users, we need to create +a tenant for all the services, and then users for each of the services. We +then assign those service users an Admin role on the service tenant. This +allows them to validate tokens - and authenticate and authorize other user +requests. + +Create a tenant for the services, typically named 'service' (however, the name can be whatever you choose):: + + keystone tenant-create --name=service + +This returns a UUID of the tenant - keep that, you'll need it when creating +the users and specifying the roles. + +Create service users for nova, glance, swift, and quantum (or whatever +subset is relevant to your deployment):: + + keystone user-create --name=nova \ + --pass=Sekr3tPass \ + --tenant_id=[the uuid of the tenant] \ + --email=nova@nothing.com + +Repeat this for each service you want to enable. Email is a required field +in keystone right now, but not used in relation to the service accounts. Each +of these commands will also return a UUID of the user. Keep those to assign +the Admin role. + +For adding the Admin role to the service accounts, you'll need to know the UUID +of the role you want to add. If you don't have them handy, you can look it +up quickly with:: + + keystone role-list + +Once you have it, assign the service users to the Admin role. This is all +assuming that you've already created the basic roles and settings as described +in :doc:`configuration`:: + + keystone user-role-add --tenant_id=[uuid of the service tenant] \ + --user=[uuid of the service account] \ + --role=[uuid of the Admin role] + Defining Services ----------------- @@ -78,7 +127,15 @@ where relevant API endpoints exist for OpenStack Services. The OpenStack Dashboard, in particular, uses this heavily - and this **must** be configured for the OpenStack Dashboard to properly function. -Here's how we define the services:: +The endpoints for these services are defined in a template, an example of +which is in the project as the file ``etc/default_catalog.templates``. + +Keystone supports two means of defining the services, one is the catalog +template, as described above - in which case everything is detailed in that +template. + +The other is a SQL backend for the catalog service, in which case after +keystone is online, you need to add the services to the catalog:: keystone service-create --name=nova \ --type=compute \ @@ -96,8 +153,6 @@ Here's how we define the services:: --type=object-store \ --description="Swift Service" -The endpoints for these services are defined in a template, an example of -which is in the project as the file ``etc/default_catalog.templates``. Setting Up Middleware ===================== @@ -106,7 +161,8 @@ Keystone Auth-Token Middleware -------------------------------- The Keystone auth_token middleware is a WSGI component that can be inserted in -the WSGI pipeline to handle authenticating tokens with Keystone. +the WSGI pipeline to handle authenticating tokens with Keystone. You can +get more details of the middleware in :doc:`middlewarearchitecture`. Configuring Nova to use Keystone -------------------------------- @@ -273,8 +329,10 @@ Here is an example paste config filter that makes use of the 'admin_user' and service_host = 127.0.0.1 auth_port = 35357 auth_host = 127.0.0.1 - auth_token = ADMIN + auth_token = 012345SECRET99TOKEN012345 admin_user = admin admin_password = keystone123 -It should be noted that when using this option an 'admin' tenant/role relationship is required. The admin user is granted access to to the 'admin' role via the 'admin' tenant. +It should be noted that when using this option an admin tenant/role +relationship is required. The admin user is granted access to to the 'Admin' +role to the 'admin' tenant. diff --git a/doc/source/index.rst b/doc/source/index.rst index 5b0d2ee7..e55cb17b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -63,7 +63,7 @@ Developers Documentation developing architecture - middleware_architecture + middlewarearchitecture api_curl_examples Code Documentation diff --git a/doc/source/middleware_architecture.rst b/doc/source/middleware_architecture.rst deleted file mode 100644 index 9216719b..00000000 --- a/doc/source/middleware_architecture.rst +++ /dev/null @@ -1,230 +0,0 @@ -.. - Copyright 2011-2012 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======================= -Middleware Architecture -======================= - -Abstract -======== - -The Keystone middleware architecture supports a common authentication protocol -in use between the OpenStack projects. By using keystone as a common -authentication and authorization mechanisms, the OpenStack project can plug in -to existing authentication and authorization systems in use by existing -environments. - -In this document, we describe the architecture and responsibilities of the -authentication middleware which acts as the internal API mechanism for -OpenStack projects based on the WSGI standard. - -For the architecture of keystone and its services, please see -:doc:`architecture`. This documentation primarily describes the implementation -in ``keystone/middleware/auth_token.py`` -(:py:class:`keystone.middleware.auth_token.AuthProtocol`) - -Specification Overview -====================== - -'Authentication' is the process of determining that users are who they say they -are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest -Access, public key, token, etc, are used to verify a user's identity. In this -document, we define an ''authentication component'' as a software module that -implements an authentication protocol for an OpenStack service. OpenStack is -using a token based mechanism to represent authentication and authorization. - -At a high level, an authentication middleware component is a proxy that -intercepts HTTP calls from clients and populates HTTP headers in the request -context for other WSGI middleware or applications to use. The general flow -of the middleware processing is: - -* clear any existing authorization headers to prevent forgery -* collect the token from the existing HTTP request headers -* validate the token - - * if valid, populate additional headers representing the identity that has - been authenticated and authorized - * in invalid, or not token present, reject the request (HTTPUnauthorized) - or pass along a header indicating the request is unauthorized (configurable - in the middleware) - * if the keystone service is unavailable to validate the token, reject - the request with HTTPServiceUnavailable. - -.. _authComponent: - -Authentication Component ------------------------- - -Figure 1. Authentication Component - -.. image:: images/graphs_authComp.svg - :width: 100% - :height: 180 - :alt: An Authentication Component - -The middleware may also be configured to operated in a 'delegated mode'. -In this mode, the decision reject an unauthenticated client is delegated to -the OpenStack service, as illustrated in :ref:`authComponentDelegated`. - -Here, requests are forwarded to the OpenStack service with an identity status -message that indicates whether the client's identity has been confirmed or is -indeterminate. It is the OpenStack service that decides whether or not a reject -message should be sent to the client. - -.. _authComponentDelegated: - -Authentication Component (Delegated Mode) ------------------------------------------ - -Figure 2. Authentication Component (Delegated Mode) - -.. image:: images/graphs_authCompDelegate.svg - :width: 100% - :height: 180 - :alt: An Authentication Component (Delegated Mode) - -.. _deployStrategies: - -Deployment Strategy -=================== - -The middleware is intended to be used inline with OpenStack wsgi components, -based on the openstack-common WSGI middleware class. It is typically deployed -as a configuration element in a paste configuration pipeline of other -middleware components, with the pipeline terminating in the service -application. The middleware conforms to the python WSGI standard [PEP-333]_. -In initializing the middleware, a configuration item (which acts like a python -dictionary) is passed to the middleware with relevant configuration options. - -Configuration -------------- - -The middleware is configured within the config file of the main application as -a WSGI component. Example for the auth_token middleware:: - - [app:myService] - paste.app_factory = myService:app_factory - - [pipeline:main] - pipeline = tokenauth myService - - [filter:tokenauth] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://127.0.0.1:5000/ - admin_token = Super999Sekret888Password777 - admin_user = admin - admin_password = SuperSekretPassword - admin_tenant_name = service - ;Uncomment next line and check ip:port to use memcached to cache tokens - ;memcache_servers = 127.0.0.1:11211 - -Configuration Options ---------------------- - -* ``auth_host``: (required) the host providing the keystone service API endpoint - for validating and requesting tokens -* ``admin_token``: either this or the following three options are required. If - set, this is a single shared secret with the keystone configuration used to - validate tokens. -* ``admin_user``, ``admin_password``, ``admin_tenant_name``: if ``admin_token`` - is not set, or invalid, then admin_user, admin_password, and - admin_tenant_name are defined as a service account which is expected to have - been previously configured in Keystone to validate user tokens. - -* ``delay_auth_decision``: (optional, default `0`) (off). If on, the middleware - will not reject invalid auth requests, but will delegate that decision to - downstream WSGI components. -* ``auth_port``: (optional, default `35357`) the port used to validate tokens -* ``auth_protocol``: (optional, default `https`) -* ``auth_uri``: (optional, defaults to `auth_protocol`://`auth_host`:`auth_port`) - -Caching for improved response ------------------------------ - -In order to prevent every service request, the middleware may be configured -to utilize a cache, and the keystone API returns the tokens with an -expiration (configurable in duration on the keystone service). The middleware -supports memcache based caching. - -* ``memcache_servers``: (optonal) if defined, the memcache server(s) to use for - cacheing -* ``token_cache_time``: (optional, default 300 seconds) Only valid if - memcache_servers is defined. - -Exchanging User Information -=========================== - -The middleware expects to find a token representing the user with the header -``X-Auth-Token`` or ``X-Storage-Token``. `X-Storage-Token` is supported for -swift/cloud files and for legacy Rackspace use. If the token isn't present and -the middleware is configured to not delegate auth responsibility, it will -respond to the HTTP request with HTTPUnauthorized, returning the header -``WWW-Authenticate`` with the value `Keystone uri='...'` to indicate where to -request a token. The auth_uri returned is configured with the middleware. - -The authentication middleware extends the HTTP request with the header -``X-Identity-Status``. If a request is successfully authenticated, the value -is set to `Confirmed`. If the middleware is delegating the auth decision to the -service, then the status is set to `Invalid` if the auth request was -unsuccessful. - -Extended the request with additional User Information ------------------------------------------------------ - -:py:class:`keystone.middleware.auth_token.AuthProtocol` extends the request -with additional information if the user has been authenticated. - - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant-Id - The unique, immutable tenant Id - -X-Tenant-Name - The unique, but mutable (it can change) tenant name. - -X-User-Id - The user id of the user used to log in - -X-User-Name - The username used to log in - -X-Roles - The roles associated with that user - -Deprecated additions --------------------- - -X-Tenant - Provides the tenant name. This is to support any legacy implementations - before Keystone switched to an ID/Name schema for tenants. - -X-User - The username used to log in. This is to support any legacy implementations - before Keystone switched to an ID/Name schema for tenants. - -X-Role - The roles associated with that user - -References -========== - -.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface - v1.0.'' http://www.python.org/dev/peps/pep-0333/. diff --git a/doc/source/middlewarearchitecture.rst b/doc/source/middlewarearchitecture.rst new file mode 100644 index 00000000..9216719b --- /dev/null +++ b/doc/source/middlewarearchitecture.rst @@ -0,0 +1,230 @@ +.. + Copyright 2011-2012 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======================= +Middleware Architecture +======================= + +Abstract +======== + +The Keystone middleware architecture supports a common authentication protocol +in use between the OpenStack projects. By using keystone as a common +authentication and authorization mechanisms, the OpenStack project can plug in +to existing authentication and authorization systems in use by existing +environments. + +In this document, we describe the architecture and responsibilities of the +authentication middleware which acts as the internal API mechanism for +OpenStack projects based on the WSGI standard. + +For the architecture of keystone and its services, please see +:doc:`architecture`. This documentation primarily describes the implementation +in ``keystone/middleware/auth_token.py`` +(:py:class:`keystone.middleware.auth_token.AuthProtocol`) + +Specification Overview +====================== + +'Authentication' is the process of determining that users are who they say they +are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest +Access, public key, token, etc, are used to verify a user's identity. In this +document, we define an ''authentication component'' as a software module that +implements an authentication protocol for an OpenStack service. OpenStack is +using a token based mechanism to represent authentication and authorization. + +At a high level, an authentication middleware component is a proxy that +intercepts HTTP calls from clients and populates HTTP headers in the request +context for other WSGI middleware or applications to use. The general flow +of the middleware processing is: + +* clear any existing authorization headers to prevent forgery +* collect the token from the existing HTTP request headers +* validate the token + + * if valid, populate additional headers representing the identity that has + been authenticated and authorized + * in invalid, or not token present, reject the request (HTTPUnauthorized) + or pass along a header indicating the request is unauthorized (configurable + in the middleware) + * if the keystone service is unavailable to validate the token, reject + the request with HTTPServiceUnavailable. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +The middleware may also be configured to operated in a 'delegated mode'. +In this mode, the decision reject an unauthenticated client is delegated to +the OpenStack service, as illustrated in :ref:`authComponentDelegated`. + +Here, requests are forwarded to the OpenStack service with an identity status +message that indicates whether the client's identity has been confirmed or is +indeterminate. It is the OpenStack service that decides whether or not a reject +message should be sent to the client. + +.. _authComponentDelegated: + +Authentication Component (Delegated Mode) +----------------------------------------- + +Figure 2. Authentication Component (Delegated Mode) + +.. image:: images/graphs_authCompDelegate.svg + :width: 100% + :height: 180 + :alt: An Authentication Component (Delegated Mode) + +.. _deployStrategies: + +Deployment Strategy +=================== + +The middleware is intended to be used inline with OpenStack wsgi components, +based on the openstack-common WSGI middleware class. It is typically deployed +as a configuration element in a paste configuration pipeline of other +middleware components, with the pipeline terminating in the service +application. The middleware conforms to the python WSGI standard [PEP-333]_. +In initializing the middleware, a configuration item (which acts like a python +dictionary) is passed to the middleware with relevant configuration options. + +Configuration +------------- + +The middleware is configured within the config file of the main application as +a WSGI component. Example for the auth_token middleware:: + + [app:myService] + paste.app_factory = myService:app_factory + + [pipeline:main] + pipeline = tokenauth myService + + [filter:tokenauth] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = Super999Sekret888Password777 + admin_user = admin + admin_password = SuperSekretPassword + admin_tenant_name = service + ;Uncomment next line and check ip:port to use memcached to cache tokens + ;memcache_servers = 127.0.0.1:11211 + +Configuration Options +--------------------- + +* ``auth_host``: (required) the host providing the keystone service API endpoint + for validating and requesting tokens +* ``admin_token``: either this or the following three options are required. If + set, this is a single shared secret with the keystone configuration used to + validate tokens. +* ``admin_user``, ``admin_password``, ``admin_tenant_name``: if ``admin_token`` + is not set, or invalid, then admin_user, admin_password, and + admin_tenant_name are defined as a service account which is expected to have + been previously configured in Keystone to validate user tokens. + +* ``delay_auth_decision``: (optional, default `0`) (off). If on, the middleware + will not reject invalid auth requests, but will delegate that decision to + downstream WSGI components. +* ``auth_port``: (optional, default `35357`) the port used to validate tokens +* ``auth_protocol``: (optional, default `https`) +* ``auth_uri``: (optional, defaults to `auth_protocol`://`auth_host`:`auth_port`) + +Caching for improved response +----------------------------- + +In order to prevent every service request, the middleware may be configured +to utilize a cache, and the keystone API returns the tokens with an +expiration (configurable in duration on the keystone service). The middleware +supports memcache based caching. + +* ``memcache_servers``: (optonal) if defined, the memcache server(s) to use for + cacheing +* ``token_cache_time``: (optional, default 300 seconds) Only valid if + memcache_servers is defined. + +Exchanging User Information +=========================== + +The middleware expects to find a token representing the user with the header +``X-Auth-Token`` or ``X-Storage-Token``. `X-Storage-Token` is supported for +swift/cloud files and for legacy Rackspace use. If the token isn't present and +the middleware is configured to not delegate auth responsibility, it will +respond to the HTTP request with HTTPUnauthorized, returning the header +``WWW-Authenticate`` with the value `Keystone uri='...'` to indicate where to +request a token. The auth_uri returned is configured with the middleware. + +The authentication middleware extends the HTTP request with the header +``X-Identity-Status``. If a request is successfully authenticated, the value +is set to `Confirmed`. If the middleware is delegating the auth decision to the +service, then the status is set to `Invalid` if the auth request was +unsuccessful. + +Extended the request with additional User Information +----------------------------------------------------- + +:py:class:`keystone.middleware.auth_token.AuthProtocol` extends the request +with additional information if the user has been authenticated. + + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant-Id + The unique, immutable tenant Id + +X-Tenant-Name + The unique, but mutable (it can change) tenant name. + +X-User-Id + The user id of the user used to log in + +X-User-Name + The username used to log in + +X-Roles + The roles associated with that user + +Deprecated additions +-------------------- + +X-Tenant + Provides the tenant name. This is to support any legacy implementations + before Keystone switched to an ID/Name schema for tenants. + +X-User + The username used to log in. This is to support any legacy implementations + before Keystone switched to an ID/Name schema for tenants. + +X-Role + The roles associated with that user + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. -- cgit