From 6b38e3ceb62515f1d28078d2f36b72548023521c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Tue, 24 Jan 2012 09:43:06 -0800 Subject: moving in all the original docs from keystone --- docs/source/adminAPI_curl_examples.rst | 387 +++++++++++++++ docs/source/architecture.rst | 97 ++++ docs/source/backends.rst | 188 ++++++++ docs/source/configuration.rst | 100 ++++ docs/source/configuringservices.rst | 333 +++++++++++++ docs/source/controllingservers.rst | 288 +++++++++++ docs/source/endpoints.rst | 430 +++++++++++++++++ docs/source/extensions.rst | 183 +++++++ docs/source/images/305.svg | 158 ++++++ docs/source/images/authComp.svg | 174 +++++++ docs/source/images/both.svg | 135 ++++++ docs/source/images/graphs_305.svg | 41 ++ docs/source/images/graphs_authComp.svg | 48 ++ docs/source/images/graphs_authCompDelegate.svg | 53 +++ docs/source/images/graphs_both.svg | 36 ++ docs/source/images/graphs_delegate_accept.svg | 52 ++ .../images/graphs_delegate_forbiden_basic.svg | 53 +++ .../images/graphs_delegate_forbiden_proxy.svg | 52 ++ .../source/images/graphs_delegate_reject_basic.svg | 55 +++ .../source/images/graphs_delegate_reject_oauth.svg | 56 +++ .../images/graphs_delegate_unimplemented.svg | 53 +++ docs/source/images/graphs_mapper.svg | 73 +++ docs/source/images/graphs_proxyAuth.svg | 51 ++ docs/source/images/graphs_separate.svg | 30 ++ docs/source/images/graphs_standard_accept.svg | 51 ++ docs/source/images/graphs_standard_reject.svg | 39 ++ docs/source/images/graphs_together.svg | 24 + docs/source/images/images_layouts.svg | 200 ++++++++ docs/source/images/layouts.svg | 215 +++++++++ docs/source/images/mapper.svg | 237 +++++++++ docs/source/images/proxyAuth.svg | 238 +++++++++ docs/source/middleware.rst | 169 +++++++ docs/source/middleware_architecture.rst | 529 +++++++++++++++++++++ docs/source/migration.rst | 126 +++++ docs/source/nova-api-paste.rst | 142 ++++++ docs/source/releases.rst | 36 ++ docs/source/serviceAPI_curl_examples.rst | 69 +++ docs/source/services.rst | 92 ++++ docs/source/ssl.rst | 118 +++++ docs/source/usingkeystone.rst | 28 ++ 40 files changed, 5439 insertions(+) create mode 100644 docs/source/adminAPI_curl_examples.rst create mode 100644 docs/source/architecture.rst create mode 100644 docs/source/backends.rst create mode 100644 docs/source/configuration.rst create mode 100644 docs/source/configuringservices.rst create mode 100644 docs/source/controllingservers.rst create mode 100644 docs/source/endpoints.rst create mode 100644 docs/source/extensions.rst create mode 100644 docs/source/images/305.svg create mode 100644 docs/source/images/authComp.svg create mode 100644 docs/source/images/both.svg create mode 100644 docs/source/images/graphs_305.svg create mode 100644 docs/source/images/graphs_authComp.svg create mode 100644 docs/source/images/graphs_authCompDelegate.svg create mode 100644 docs/source/images/graphs_both.svg create mode 100644 docs/source/images/graphs_delegate_accept.svg create mode 100644 docs/source/images/graphs_delegate_forbiden_basic.svg create mode 100644 docs/source/images/graphs_delegate_forbiden_proxy.svg create mode 100644 docs/source/images/graphs_delegate_reject_basic.svg create mode 100644 docs/source/images/graphs_delegate_reject_oauth.svg create mode 100644 docs/source/images/graphs_delegate_unimplemented.svg create mode 100644 docs/source/images/graphs_mapper.svg create mode 100644 docs/source/images/graphs_proxyAuth.svg create mode 100644 docs/source/images/graphs_separate.svg create mode 100644 docs/source/images/graphs_standard_accept.svg create mode 100644 docs/source/images/graphs_standard_reject.svg create mode 100644 docs/source/images/graphs_together.svg create mode 100644 docs/source/images/images_layouts.svg create mode 100644 docs/source/images/layouts.svg create mode 100644 docs/source/images/mapper.svg create mode 100644 docs/source/images/proxyAuth.svg create mode 100644 docs/source/middleware.rst create mode 100644 docs/source/middleware_architecture.rst create mode 100644 docs/source/migration.rst create mode 100644 docs/source/nova-api-paste.rst create mode 100644 docs/source/releases.rst create mode 100644 docs/source/serviceAPI_curl_examples.rst create mode 100644 docs/source/services.rst create mode 100644 docs/source/ssl.rst create mode 100644 docs/source/usingkeystone.rst (limited to 'docs/source') diff --git a/docs/source/adminAPI_curl_examples.rst b/docs/source/adminAPI_curl_examples.rst new file mode 100644 index 00000000..81f96c36 --- /dev/null +++ b/docs/source/adminAPI_curl_examples.rst @@ -0,0 +1,387 @@ +.. + Copyright 2011 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. + +============================= +Admin API Examples Using Curl +============================= + +These examples assume a default port value of 35357, and depend on the +``sampledata`` bundled with keystone. + +GET / +===== + +Disover API version information, links to documentation (PDF, HTML, WADL), +and supported media types:: + + $ curl http://0.0.0.0:35357 + +or:: + + $ curl http://0.0.0.0:35357/v2.0/ + +Returns:: + + { + "version":{ + "id":"v2.0", + "status":"beta", + "updated":"2011-11-19T00:00:00Z", + "links":[ + { + "rel":"self", + "href":"http://127.0.0.1:35357/v2.0/" + }, + { + "rel":"describedby", + "type":"text/html", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/" + }, + { + "rel":"describedby", + "type":"application/pdf", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf" + }, + { + "rel":"describedby", + "type":"application/vnd.sun.wadl+xml", + "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl" + } + ], + "media-types":[ + { + "base":"application/xml", + "type":"application/vnd.openstack.identity-v2.0+xml" + }, + { + "base":"application/json", + "type":"application/vnd.openstack.identity-v2.0+json" + } + ] + } + } + +GET /extensions +=============== + +Discover the API extensions enabled at the endpoint:: + + $ curl http://0.0.0.0:35357/extensions + +Returns:: + + { + "extensions":{ + "values":[] + } + } + +POST /tokens +============ + +Authenticate by exchanging credentials for an access token:: + + $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens + +Returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "serviceCatalog":[ + { + "endpoints":[ + { + "adminURL":"http://swift.admin-nets.local:8080/", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", + "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" + } + ], + "type":"object-store", + "name":"swift" + }, + { + "endpoints":[ + { + "adminURL":"http://cdn.admin-nets.local/v1.1/1", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:7777/v1.1/1", + "publicURL":"http://cdn.publicinternets.com/v1.1/1" + } + ], + "type":"object-store", + "name":"cdn" + } + ], + "user":{ + "id":"1", + "roles":[ + { + "tenantId":"1", + "id":"3", + "name":"Member" + } + ], + "name":"joeuser" + } + } + } + +.. note:: + + Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. + +GET /tokens/{token_id} +====================== + +.. note:: + + This call refers to a token known to be valid, ``887665443383838`` in this case. + +Validate a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +If the token is valid, returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "user":{ + "name":"joeuser", + "tenantName":"customer-x", + "id":"1", + "roles":[ + { + "serviceId":"1", + "id":"3", + "name":"Member" + } + ], + "tenantId":"1" + } + } + } + +HEAD /tokens/{token_id} +======================= + +This is a high-performance variant of the GET call documented above, which +by definition, returns no response body:: + + $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +... which returns ``200``, indicating the token is valid:: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: None + Date: Tue, 08 Nov 2011 23:07:44 GMT + +GET /tokens/{token_id}/endpoints +================================ + +List all endpoints for a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + +Returns:: + + { + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", + "rel": "next" + } + ], + "endpoints": [ + { + "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", + "name": "swift", + "adminURL": "http://swift.admin-nets.local:8080/", + "region": "RegionOne", + "tenantId": 1, + "type": "object-store", + "id": 1, + "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" + }, + { + "internalURL": "http://localhost:8774/v1.0", + "name": "nova_compat", + "adminURL": "http://127.0.0.1:8774/v1.0", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 2, + "publicURL": "http://nova.publicinternets.com/v1.0/" + }, + { + "internalURL": "http://localhost:8774/v1.1", + "name": "nova", + "adminURL": "http://127.0.0.1:8774/v1.1", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 3, + "publicURL": "http://nova.publicinternets.com/v1.1/ + }, + { + "internalURL": "http://127.0.0.1:9292/v1.1/", + "name": "glance", + "adminURL": "http://nova.admin-nets.local/v1.1/", + "region": "RegionOne", + "tenantId": 1, + "type": "image", + "id": 4, + "publicURL": "http://glance.publicinternets.com/v1.1/" + }, + { + "internalURL": "http://127.0.0.1:7777/v1.1/1", + "name": "cdn", + "adminURL": "http://cdn.admin-nets.local/v1.1/1", + "region": "RegionOne", + "tenantId": 1, + "versionId": "1.1", + "versionList": "http://127.0.0.1:7777/", + "versionInfo": "http://127.0.0.1:7777/v1.1", + "type": "object-store", + "id": 5, + "publicURL": "http://cdn.publicinternets.com/v1.1/1" + } + ] + } + +GET /tenants +============ + +List all of the tenants in the system (requires an Admin ``X-Auth-Token``):: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": false, + "description": "None", + "name": "project-y", + "id": "3" + }, + { + "enabled": true, + "description": "None", + "name": "ANOTHER:TENANT", + "id": "2" + }, + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } + +GET /tenants/{tenant_id} +======================== + +Retrieve information about a tenant, by tenant ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1 + +Returns:: + + { + "tenant":{ + "enabled":true, + "description":"None", + "name":"customer-x", + "id":"1" + } + } + +GET /tenants/{tenant_id}/users/{user_id}/roles +============================================== + +List the roles a user has been granted on a tenant:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"3", + "name":"Member" + } + ] + } + +GET /users/{user_id} +==================== + +Retrieve information about a user, by user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1 + +Returns:: + + { + "user":{ + "tenantId":"1", + "enabled":true, + "id":"1", + "name":"joeuser" + } + } + +GET /users/{user_id}/roles +========================== + +Retrieve the roles granted to a user, given a user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"2", + "name":"KeystoneServiceAdmin" + } + ] + } diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst new file mode 100644 index 00000000..8de45502 --- /dev/null +++ b/docs/source/architecture.rst @@ -0,0 +1,97 @@ +.. + Copyright 2011 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. + +Keystone Architecture +===================== + +Keystone has two major components: Authentication and a Service Catalog. + +Authentication +-------------- + +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. + +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. + +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 +--------------- + +Keystone also provides a list of REST API endpoints as a definitive list for +an OpenStack installation. Key concepts include: + +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. + +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. + +Template + A collection of endpoints representing a set of consumable OpenStack + service endpoints. + +Components of Keystone +---------------------- + +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. diff --git a/docs/source/backends.rst b/docs/source/backends.rst new file mode 100644 index 00000000..b3fc2d91 --- /dev/null +++ b/docs/source/backends.rst @@ -0,0 +1,188 @@ +.. + Copyright 2011 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. + +======== +Backends +======== + +Keystone supports multiple types of data stores for things like users, tenants, and +tokens, including SQL, LDAP, and memcache. + +SQL +=== + +In the default backend configuration (SQL-only), Keystone depends on the following database tables. + +``users`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Unqiue username used for authentication via ``passwordCredentials``. +``password`` + Password used for authentication via ``passwordCredentials``. + + Salted and hashed using ``passlib``. +``email`` + Email address (uniqueness is expected, but not enforced). +``enabled`` + If false, the user is unable to authenticate and the user's tokens will fail validation. +``tenant_id`` + Default tenant for the user. + +``tokens`` +---------- + +``id`` + The actual token provided after successful authentication (*plaintext*). +``user_id`` + References the user who owns the token. +``tenant_id`` + (*optional*) References the tenant the token is scoped to. +``expires`` + Indicates the expiration date of the token, after which the token can no longer be validated successfully. + +``tenants`` +----------- + +``id`` + Auto-incremented primary key. +``name`` + Unique string identifying the tenant. +``desc`` + Description of the tenant. +``enabled`` + If false, users are unable to scope to the tenant. + +``roles`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Name of the role. + + If the role is owned by a service, the role name **must** follow the convention:: + + serviceName:roleName +``desc`` + Description of the role. +``service_id`` + (*optional*) References the service that owns the role. + +``user_roles`` +-------------- + +Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). + +``id`` + Auto-incremented primary key. +``user_id`` + References the user the role is granted to. +``role_id`` + References the granted role. +``tenant_id`` + (*optional*) References a tenant upon which this grant is applies. + +``services`` +------------ + +``id`` + Auto-incremented primary key. +``name`` + Unique name of the service. +``type`` + Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). + + This can also be extended to support non-core services. Extended services + follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). +``desc`` + Describes the service. +``owner_id`` + (*optional*) References the user who owns the service. + +``credentials`` +--------------- + +Currently only used for Amazon EC2 credential storage, this table is designed to support multiple +types of credentials in the future. + +``id`` + Auto-incremented primary key. +``user_id`` + References the user who owns the credential. +``tenant_id`` + References the tenant upon which the credential is valid. +``types`` + Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). +``key`` + Amazon EC2 access key. +``secret`` + Amazon EC2 secret key. + +``endpoints`` +------------- + +Tenant-specific endpoints map endpoint templates to specific tenants. +The ``tenant_id`` which appears here replaces the +``%tenant_id%`` template variable in the specified endpoint template. + +``id`` + Auto-incremented primary key. +``tenant_id`` + References the tenant this endpoint applies to. +``endpoint_template_id`` + The endpoint template to appear in the user's service catalog. + +``endpoint_templates`` +---------------------- + +A multi-purpose model for the service catalog which can be: + +- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. +- Provided to all users as-is, when ``is_global`` is true. + +``id`` + Auto-incremented primary key. +``region`` + Identifies the geographic region the endpoint is physically located within. +``service_id`` + TODO: References the service which owns the endpoints? +``public_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint available on the public Internet. +``admin_url`` + Appears in the service catalog [#first]_. + + Users of this endpoint must have an Admin or ServiceAdmin role. +``internal_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint on an internal, unmetered network. +``enabled`` + If false, this endpoint template will not appear in the service catalog. +``is_global`` + If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. +``version_id`` + Identifies the version of the API contract that endpoint supports. +``version_list`` + A URL which lists versions supported by the endpoint. +``version_info`` + A URL which provides detailed version info regarding the service. + +.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 00000000..a98d92f8 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,100 @@ +.. + Copyright 2011 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. + +==================== +Configuring Keystone +==================== + +.. toctree:: + :maxdepth: 1 + + keystone.conf + man/keystone-manage + +Once Keystone is installed, there are a number of configuration options +available and potentially some initial data to create and set up. + +Sample data / Quick Setup +========================= + +Default sampledata is provided for easy setup and testing in bin/sampeldata. To +set up the sample data run the following command while Keystone is running:: + + $ ./bin/sampledata + +The sample data created comes from the file :doc:`sourcecode/keystone.test.sampledata` + + +Keystone Configuration File +=========================== + +Most configuration is done via configuration files. The default files are +in ``/etc/keystone.conf`` + +When starting up a Keystone server, you can specify the configuration file to +use (see :doc:`controllingservers`). +If you do **not** specify a configuration file, keystone will look in the following +directories for a configuration file, in order: + +* ``~/.keystone`` +* ``~/`` +* ``/etc/keystone`` +* ``/etc`` + +The keystone configuration file should be named ``keystone.conf``. +If you installed keystone via your operating system's +package management system, it is likely that you will have sample +configuration files installed in ``/etc/keystone``. + +In addition to this documentation page, you can check the +``etc/keystone.conf`` sample configuration +files distributed with keystone for example configuration files for each server +application with detailed comments on what each options does. + +Sample Configuration Files +-------------------------- + +Keystone ships with sample configuration files in keystone/etc. These files are: + +1. keystone.conf + + A standard configuration file for running keystone in stand-alone mode. + It has a set of default extensions loaded to support administering Keystone + over REST. It uses a local SQLite database. + +2. memcache.conf + + A configuration that uses memcached for storing tokens (but still SQLite for all + other entities). This requires memcached running. + +3. ssl.conf + + A configuration that runs Keystone with SSL (so all URLs are accessed over HTTPS). + +To run any of these configurations, use the `-c` option:: + + ./keystone -c ../etc/ssl.conf + + + +Usefule Links +------------- + +For a sample configuration file with explanations of the settings, see :doc:`keystone.conf` + +For configuring an LDAP backend, see http://mirantis.blogspot.com/2011/08/ldap-identity-store-for-openstack.html + +For configuration settings of middleware components, see :doc:`middleware` \ No newline at end of file diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst new file mode 100644 index 00000000..083c3ec5 --- /dev/null +++ b/docs/source/configuringservices.rst @@ -0,0 +1,333 @@ +.. + Copyright 2011 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. + +========================================== +Configuring Services to work with Keystone +========================================== + +.. toctree:: + :maxdepth: 1 + +Once Keystone is installed and running, services need to be configured to work +with it. These are the steps to configure a service to work with Keystone: + +1. Create or get credentials for the service to use + + A set of credentials are needed for each service (they may be + shared if you chose to). Depending on the service, these credentials are + either a username and password or a long-lived token.. + +2. Register the service, endpoints, roles and other entities + + In order for a service to have it's endpoints and roles show in the service + catalog returned by Keystone, a service record needs to be added for the + service. Endpoints and roles associated with that service can then be created. + + This can be done through the REST interface (using the OS-KSCATALOG extension) + or using keystone-manage. + +3. Install and configure middleware for the service to handle authentication + + Clients making calls to the service will pass in an authentication token. The + Keystone middleware will look for and validate that token, taking the + appropriate action. It will also retrive additional information from the token + such as user name, id, tenant name, id, roles, etc... + + The middleware will pass those data down to the service as headers. The + detailed description of this architecture is available here :doc:`middleware_architecture` + +Setting up credentials +====================== + +First admin user - bootstrapping +-------------------------------- + +For a default installation of Keystone, before you can use the REST API, you +need to create your first initial user and grant that user the right to +administer Keystone. + +For the keystone service itself, two +Roles are pre-defined in the keystone configuration file +(:doc:`keystone.conf`). + + #Role that allows admin operations (access to all operations) + keystone-admin-role = Admin + + #Role that allows acting as service (validate tokens, register service, + etc...) + keystone-service-admin-role = KeystoneServiceAdmin + +In order to create your first user, once Keystone is running use +the `keystone-manage` command: + + $ keystone-manage user add admin secrete + $ keystone-manage role add Admin + $ keystone-manage role add KeystoneServiceAdmin + $ keystone-manage role grant Admin admin + $ keystone-manage role grant KeystoneServiceAdmin admin + +This creates the `admin` user (with a password of `secrete`), creates +two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to +the `admin` user. From here, you should now have the choice of using the +administrative API (as well as the :doc:`man/keystone-manage` commands) to +further configure keystone. There are a number of examples of how to use +that API at :doc:`adminAPI_curl_examples`. + + +Setting up services +=================== + +Defining Services and Service Endpoints +--------------------------------------- + +Keystone also acts as a service catalog to let other OpenStack systems know +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:: + + $ keystone-manage service add nova compute "Nova Compute Service" + $ keystone-manage service add glance image "Glance Image Service" + $ keystone-manage service add swift storage "Swift Object Storage Service" + $ keystone-manage service add keystone identity "Keystone Identity Service" + +Once the services are defined, we create endpoints for them. Each service +has three relevant URL's associated with it that are used in the command: + +* the public API URL +* an administrative API URL +* an internal URL + +The "internal URL" is an endpoint the generally offers the same API as the +public URL, but over a high-bandwidth, low-latency, unmetered (free) network. +You would use that to transfer images from nova to glance for example, and +not the Public URL which would go over the internet and be potentially chargeable. + +The "admin URL" is for administering the services and is not exposed or accessible +to customers without the apporpriate privileges. + +An example of setting up the endpoint for Nova:: + + $ keystone-manage endpointTemplates add RegionOne nova \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + 1 1 + +Glance:: + + $ keystone-manage endpointTemplates add RegionOne glance \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + 1 1 + +Swift:: + + $ keystone-manage endpointTemplates add RegionOne swift \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + http://swift.mydomain:8080/v1.0/ \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + 1 1 + +And setting up an endpoint for Keystone:: + + $ keystone-manage endpointTemplates add RegionOne keystone \ + http://keystone.mydomain:5000/v2.0 \ + http://keystone.mydomain:35357/v2.0 \ + http://keystone.mydomain:5000/v2.0 \ + 1 1 + + +Defining an Administrative Service Token +---------------------------------------- + +An Administrative Service Token is a bit of arbitrary text which is configured +in Keystone and used (typically configured into) Nova, Swift, Glance, and any +other OpenStack projects, to be able to use Keystone services. + +This token is an arbitrary text string, but must be identical between Keystone +and the services using Keystone. This token is bound to a user and tenant as +well, so those also need to be created prior to setting it up. + +The *admin* user was set up above, but we haven't created a tenant for that +user yet:: + + $ keystone-manage tenant add admin + +and while we're here, let's grant the admin user the 'Admin' role to the +'admin' tenant:: + + $ keystone-manage role add Admin + $ keystone-manage role grant Admin admin admin + +Now we can create a service token:: + + $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 + +This creates a service token of '999888777666' associated to the admin user, +admin tenant, and expires on February 5th, 2015. This token will be used when +configuring Nova, Glance, or other OpenStack services. + +Securing Communications with SSL +-------------------------------- + +To encrypt traffic between services and Keystone, see :doc:`ssl` + + +Setting up OpenStack users +========================== + +Creating Tenants, Users, and Roles +---------------------------------- + +Let's set up a 'demo' tenant:: + + $ keystone-manage tenant add demo + +And add a 'demo' user with the password 'guest':: + + $ keystone-manage user add demo guest + +Now let's add a role of "Member" and grant 'demo' user that role +as it pertains to the tenant 'demo':: + + $ keystone-manage role add Member + $ keystone-manage role grant Member demo demo + +Let's also add the admin user as an Admin role to the demo tenant:: + + $ keystone-manage role grant Admin admin demo + +Creating EC2 credentials +------------------------ + +To add EC2 credentials for the `admin` and `demo` accounts:: + + $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' + $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' + +If you have a large number of credentials to create, you can put them all +into a single large file and import them using :doc:`man/keystone-import`. The +format of the document looks like:: + + credentials add admin EC2 'username' 'password' + credentials add admin EC2 'username' 'password' + +Then use:: + + $ keystone-import `filename` + + +Setting Up Middleware +===================== + +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. See :doc:`middleware` +for details on middleware and configuration parameters. + + +Configuring Nova to use Keystone +-------------------------------- + +To configure Nova to use Keystone for authentication, the Nova API service +can be run against the api-paste file provided by Keystone. This is most +easily accomplished by setting the `--api_paste_config` flag in nova.conf to +point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file +included references to the WSGI authentication middleware provided with the +keystone installation. + +When configuring Nova, it is important to create a admin service token for +the service (from the Configuration step above) and include that as the key +'admin_token' in the nova-api-paste.ini. See the documented +:doc:`nova-api-paste` file for references. + +Configuring Swift to use Keystone +--------------------------------- + +Similar to Nova, swift can be configured to use Keystone for authentication +rather than it's built in 'tempauth'. + +1. Add a service endpoint for Swift to Keystone + +2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) + +3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. + Here's an example `/etc/swift/proxy-server.conf`:: + + [DEFAULT] + bind_port = 8888 + user = + + [pipeline:main] + pipeline = catch_errors cache keystone proxy-server + + [app:proxy-server] + use = egg:swift#proxy + account_autocreate = true + + [filter:keystone] + use = egg:keystone#tokenauth + auth_protocol = http + auth_host = 127.0.0.1 + auth_port = 35357 + admin_token = 999888777666 + delay_auth_decision = 0 + service_protocol = http + service_host = 127.0.0.1 + service_port = 8100 + service_pass = dTpw + cache = swift.cache + + [filter:cache] + use = egg:swift#memcache + set log_name = cache + + [filter:catch_errors] + use = egg:swift#catch_errors + + Note that the optional "cache" property in the keystone filter allows any + service (not just Swift) to register its memcache client in the WSGI + environment. If such a cache exists, Keystone middleware will utilize it + to store validated token information, which could result in better overall + performance. + +4. Restart swift + +5. Verify that keystone is providing authentication to Swift + +Use `swift` to check everything works (note: you currently have to create a +container or upload something as your first action to have the account +created; there's a Swift bug to be fixed soon):: + + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v + StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 + Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 + Account: AUTH_1234 + Containers: 1 + Objects: 0 + Bytes: 0 + Accept-Ranges: bytes + X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b + +.. WARNING:: + Keystone currently allows any valid token to do anything with any account. + diff --git a/docs/source/controllingservers.rst b/docs/source/controllingservers.rst new file mode 100644 index 00000000..ba8bfc06 --- /dev/null +++ b/docs/source/controllingservers.rst @@ -0,0 +1,288 @@ +.. + Copyright 2011 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. + +============================ +Controlling Keystone Servers +============================ + +This section describes the ways to start, stop, and reload the Keystone +services. + +Keystone Services +----------------- + +Keystone can serve a number of REST APIs and extensions on different TCP/IP +ports. + +The Service API +~~~~~~~~~~~~~~~~ + +The core Keystone +API is primarily a read-only API (the only write operation being POST /tokens +which authenticates a client, and returns a generated token). +This API is sufficient to use OpenStack if all users, roles, endpoints already +exist. This is often the case if Keystone is using an enterprise backend +and the backend is managed through other entperrise tools and business +processes. This core API is called the Service API and can be started +separately from the more complete Admin API. By default, Keystone runs +this API on port 5000. This is not an IANA assigned port and should not +be relied upon (instead, use the Admin API on port 35357 to look for +this endpoint - more on this later) + +The Service API is started using this command in the /bin directory:: + + $ ./keystone-auth + +The Admin API +~~~~~~~~~~~~~ + +Inn order for Keystone to be a fully functional service out of the box, +API extensions that provide full CRUD operations is included with Keystone. +This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 +extensions. These extensions provide a full set of create, read, update, delete +(CRUD) operations that can be used to manage Keystone objects through REST +calls. By default Keystone runs this full REST API on TCP/IP port 35357 +(assigned by IANA to Keystone). + +The Admin API is started using this command in the /bin directory:: + + $ ./keystone-admin + + +Both APIs can be loaded simultaneously (on different ports) using this command:: + + $ ./keystone + +Starting a server +----------------- + +There are two ways to start a Keystone service (either the Service API server +or the Admin API server): + +- Manually calling the server program +- Using the ``keystone-control`` server daemon wrapper program + +We recommend using the second way in production and the first for development +and debugging. + +Manually starting the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first is by directly calling the server program, passing in command-line +options and a single argument for a ``paste.deploy`` configuration file to +use when configuring the server application. + +.. note:: + + Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` + configuration files that you can copy to a standard configuration directory and + adapt for your own uses. + +If you do `not` specify a configuration file on the command line, Keystone will +do its best to locate a configuration file in one of the +following directories, stopping at the first config file it finds: + +- ``$CWD`` +- ``~/.keystone`` +- ``~/`` +- ``/etc/keystone`` +- ``/etc`` + +The filename that is searched for is ``keystone.conf`` by default. + +If no configuration file is found, you will see an error, like:: + + $ keystone + ERROR: Unable to locate any configuration file. Cannot load application keystone + +Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: + + $ ./keystone -d + keystone-legacy-auth: INFO ************************************************** + keystone-legacy-auth: INFO Configuration options gathered from config file: + keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + keystone-legacy-auth: INFO ================================================ + keystone-legacy-auth: INFO admin_host 0.0.0.0 + keystone-legacy-auth: INFO admin_port 35357 + keystone-legacy-auth: INFO admin_ssl False + keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy + keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem + keystone-legacy-auth: INFO cert_required True + keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem + keystone-legacy-auth: INFO debug True + keystone-legacy-auth: INFO default_store sqlite + keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm + keystone-legacy-auth: INFO hash-password True + keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + keystone-legacy-auth: INFO keystone-admin-role Admin + keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin + keystone-legacy-auth: INFO log_dir . + keystone-legacy-auth: INFO log_file keystone.log + keystone-legacy-auth: INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + keystone-legacy-auth: INFO service_host 0.0.0.0 + keystone-legacy-auth: INFO service_port 5000 + keystone-legacy-auth: INFO service_ssl False + keystone-legacy-auth: INFO verbose False + keystone-legacy-auth: INFO ************************************************** + passlib.registry: INFO registered crypt handler 'sha512_crypt': + Starting the RAX-KEY extension + Starting the Legacy Authentication component + admin : INFO ************************************************** + admin : INFO Configuration options gathered from config file: + admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + admin : INFO ================================================ + admin : INFO admin_host 0.0.0.0 + admin : INFO admin_port 35357 + admin : INFO admin_ssl False + admin : INFO backends keystone.backends.sqlalchemy + admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem + admin : INFO cert_required True + admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem + admin : INFO debug True + admin : INFO default_store sqlite + admin : INFO extensions osksadm,oskscatalog,hpidm + admin : INFO hash-password True + admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + admin : INFO keystone-admin-role Admin + admin : INFO keystone-service-admin-role KeystoneServiceAdmin + admin : INFO log_dir . + admin : INFO log_file keystone.log + admin : INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + admin : INFO service_host 0.0.0.0 + admin : INFO service_port 5000 + admin : INFO service_ssl False + admin : INFO verbose False + admin : INFO ************************************************** + Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + Service API (ssl=False) listening on 0.0.0.0:5000 + Admin API (ssl=False) listening on 0.0.0.0:35357 + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ + + $ sudo keystone-registry keystone-registry.conf & + jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) + + $ ps aux | grep keystone + myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone + myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d + +Simply supply the configuration file as the first argument +and then any common options +you want to use (``-d`` was used above to show some of the debugging +output that the server shows when starting up. Call the server program +with ``--help`` to see all available options you can specify on the +command line.) + +Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) +for debugging. + +For more information on configuring the server via the ``paste.deploy`` +configuration files, see the section entitled +:doc:`Configuring Keystone ` + +Note that the server `daemonizes` itself by using the standard +shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend +using the ``keystone-control`` server daemon wrapper for daemonizing. See below +for more details on daemonization with ``keystone-control``. + +Using ``keystone-control`` to start the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The second way to start up a Keystone server is to use the ``keystone-control`` +program. ``keystone-control`` is a wrapper script that allows the user to +start, stop, restart, and reload the other Keystone server programs in +a fashion that is more conducive to automation and scripting. + +Servers started via the ``keystone-control`` program are always `daemonized`, +meaning that the server program process runs in the background. + +To start a Keystone server with ``keystone-control``, simply call +``keystone-control`` with a server and the word "start", followed by +any command-line options you wish to provide. Start the server with ``keystone-control`` +in the following way:: + + $ sudo keystone-control start [CONFPATH] + +.. note:: + + You must use the ``sudo`` program to run ``keystone-control`` currently, as the + pid files for the server programs are written to /var/run/keystone/ + +Start the ``keystone-admin`` server using ``keystone-control``:: + + $ sudo keystone-control admin start + Starting keystone-admin with /etc/keystone.conf + +The same ``paste.deploy`` configuration files are used by ``keystone-control`` +to start the Keystone server programs, and you can specify (as the example above +shows) a configuration file when starting the server. + +Stopping a server +----------------- + +If you started a Keystone server manually and did not use the ``&`` backgrounding +function, simply send a terminate signal to the server process by typing +``Ctrl-C`` + +If you started the Keystone server using ``keystone-control``, you can +use the ``keystone-control`` program to stop it:: + + $ sudo keystone-control stop + +For example:: + + $ sudo keystone-control auth stop + Stopping keystone-auth pid: 77401 signal: 15 + +Restarting a server +------------------- + +Restart the Keystone server using ``keystone-control``:: + + $ sudo keystone-control admin restart /etc/keystone.conf + Stopping keystone-admin pid: 77401 signal: 15 + Starting keystone-admin with /etc/keystone.conf diff --git a/docs/source/endpoints.rst b/docs/source/endpoints.rst new file mode 100644 index 00000000..84a42e09 --- /dev/null +++ b/docs/source/endpoints.rst @@ -0,0 +1,430 @@ +.. + Copyright 2011 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. + +================================ +Endpoints and Endpoint Templates +================================ + +.. toctree:: + :maxdepth: 1 + +What are Endpoints? +------------------- + +Simply, endpoints are URLs that point to OpenStack services. When you +authenticate to Keystone you get back a token which has a service catalog in +it. The service catalog is basically a list of the OpenStack services that +you have access to and the URLs you can use to get to them; their endpoints. + +Here is an example response from Keystone when you authenticate:: + + { + "access":{ + "token":{ + "id":"ab48a9efdfedb23ty3494", + "expires":"2010-11-01T03:32:15-05:00", + "tenant":{ + "id": "t1000", + "name": "My Project" + } + }, + "user":{ + "id":"u123", + "name":"jqsmith", + "roles":[{ + "id":"100", + "name":"compute:admin" + }, + { + "id":"101", + "name":"object-store:admin", + "tenantId":"t1000" + } + ], + "roles_links":[] + }, + "serviceCatalog":[{ + "name":"Nova", + "type":"compute", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1/t1000", + "internalURL":"https://compute.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://compute.north.host.com/v1/", + "versionList":"https://compute.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1.1/t1000", + "internalURL":"https://compute.north.internal/v1.1/t1000", + "region":"North", + "versionId":"1.1", + "versionInfo":"https://compute.north.host.com/v1.1/", + "versionList":"https://compute.north.host.com/" + } + ], + "endpoints_links":[] + }, + { + "name":"Swift", + "type":"object-store", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://storage.north.host.com/v1/t1000", + "internalURL":"https://storage.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://storage.north.host.com/v1/", + "versionList":"https://storage.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://storage.south.host.com/v1/t1000", + "internalURL":"https://storage.south.internal/v1/t1000", + "region":"South", + "versionId":"1", + "versionInfo":"https://storage.south.host.com/v1/", + "versionList":"https://storage.south.host.com/" + } + ] + }, + { + "name":"DNS-as-a-Service", + "type":"dnsextension:dns", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://dns.host.com/v2.0/t1000", + "versionId":"2.0", + "versionInfo":"https://dns.host.com/v2.0/", + "versionList":"https://dns.host.com/" + } + ] + } + ] + } + } + +Note the following about this response: + +#. There are two endpoints given to the Nova compute service. The only + difference between them is the version (1.0 vs. 1.1). This allows for code + written to look for the version 1.0 endpoint to still work even after the 1.1 + version is released. + +#. There are two endpoints for the Swift object-store service. The difference + between them is they are in different regions (North and South). + +#. Note the DNS service is global; it does not have a Region. Also, since DNS + is not a core OpenStack service, the endpoint type is "dnsextension:dns" + showing it is coming from an extension to the Keystone service. + +#. The Region, Tenant, and versionId are listed under the endpoint. You do not + (and should not) have to parse those out of the URL. In fact, they may not be + embedded in the URL if the service developer so chooses. + + +What do the fields in an Endpoint mean? +--------------------------------------- + +The schema definition for an endpoint is in endpoints.xsd under +keystone/content/common/xsd in the Keystone code repo. The fields are: + +id + A unique ID for the endpoint. + +type + The OpenStack-registered type (ex. 'compute', 'object-store', 'image service') + This can also be extended using the OpenStack Extension mechanism to support + non-core services. Extended services will be in the form ``extension:type`` + (e.g. ``dnsextension:dns``) + +name + This can be anything that the operator of OpenStack chooses. It could be a + brand or marketing name (ex. Rackspace Cloud Servers). + +region + This is a string that identifies the region where this endpoint exists. + Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or + 'Data Center 1', 'Data Center 2'. + The list of regions and what a region means is decided by the operator. The + spec treats them as opaque strings. + +publicURL + This is the URL to use to access that endpoint over the internet. + +internalURL + This is the URL to use to communicate between services. This is genenrally + a way to communicate between services over a high bandwidth, low latency, + unmetered (free, no bandwidth charges) network. An example would be if you + want to access a swift cluster from inside your Nova VMs and want to make + sure the communication stays local and does not go over a public network + and rack up your bandwidth charges. + +adminURL + This is the URL to use to administer the service. In Keystone, this URL + is only shown to users with the appropriate rights. + +tenantId + If an endpoint is specific to a tenant, the tenantId field identifies the + tenant that URL applies to. Some operators include the tenant in the + URLs for a service, while others may provide one endpoint and use some + other mechanism to identify the tenant. This field is therefore optional. + Having this field also means you do not have to parse the URL to identify + a tenant if the operator includes it in the URL. + +versionId + This identifies the version of the API contract that endpoint supports. + While many APIs include the version in the URL (ex: https://compute.host/v1), + this field allows you to identify the version without parsing the URL. It + therefore also allows operators and service developers to publish endpoints + that do not have versions embedded in the URL. + +versionInfo + This is the URL to call to get some information on the version. This returns + information in this format:: + + { + "version": { + "id": "v2.0", + "status": "CURRENT", + "updated": "2011-01-21T11:33:21-06:00", + "links": [ + { + "rel": "self", + "href": "http://identity.api.openstack.org/v2.0/" + }, { + "rel": "describedby", + "type": "application/pdf", + "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" + }, { + "rel": "describedby", + "type": "application/vnd.sun.wadl+xml", + "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" + } + ], + "media-types": [ + { + "base": "application/xml", + "type": "application/vnd.openstack.identity+xml;version=2.0" + }, { + "base": "application/json", + "type": "application/vnd.openstack.identity+json;version=2.0" + } + ] + } + } + +versionList + + This is the URL to call to find out which versions are supported at that + endpoint. The response is in this format:: + + { + "versions":[{ + "id":"v1.0", + "status":"DEPRECATED", + "updated":"2009-10-09T11:30:00Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.0/" + } + ] + }, + { + "id":"v1.1", + "status":"CURRENT", + "updated":"2010-12-12T18:30:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.1/" + } + ] + }, + { + "id":"v2.0", + "status":"BETA", + "updated":"2011-05-27T20:22:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v2.0/" + } + ] + } + ], + "versions_links":[] + } + + Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0. + It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA. + +What are Endpoint Templates? +---------------------------- + +Endpoint Templates are a way for an administrator to manage endpoints en masse. +They provide a way to define Endpoints that apply to many or all tenants +without having to a create each endpoint on each tenant manually. Without +Endpoint Templates, if I wanted to create Endpoints for each tenant in my +OpenStack deployment, I'd have to manually create a bunch of endpoints on +each tenant (probably when I created the tenant). And then I'd have to go change +them all whenever a service changed versions or I added a new service. + +To provide a simpler mechanism to manage endpoints on tenants, Keystone uses +Endpoint Templates. I can, for example, define a template with parametrized URLs +and set it's `global` to true and that will show up as an endpoint on all the tenants +I have. Here is an example: + +Define a global Endpoint Template:: + + $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1 + + The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global' + +This creates a global endpoint (global means it gets applied to all tenants automatically). + +Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example +authentication request for use against tenant 1:: + + $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens + +The response is:: + + { + "access": { + "serviceCatalog": [ + { + "endpoints": [ + { + "internalURL": "https://compute.north.example.local", + "publicURL": "https://compute.north.example.com/v1/1/", + "region": "North" + } + ], + "name": "nova", + "type": "compute" + } + ], + "token": { + "expires": "2012-02-05T00:00:00", + "id": "887665443383838", + "tenant": { + "id": "1", + "name": "customer-x" + } + }, + "user": { + "id": "1", + "name": "joeuser", + "roles": [ + { + "id": "3", + "name": "Member", + "tenantId": "1" + } + ] + } + } + } + +Notice the adminURL is not showing (this user is a regular user and does not +have rights to see the adminURL) and the tenant ID has been substituted in the +URL:: + + "publicURL": "https://compute.north.example.com/v1/1/", + +This endpoint will show up for all tenants. The OpenStack administrator does +not need to create the endpoint manually. + +.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). + + +What parameters can I use in a Template URL +------------------------------------------- + +Currently the only parameterization available is %tenant_id% which gets +substituted by the Tenant ID. + + +Endpoint Template Types: Global or not +-------------------------------------- + +When the global flag is set to true on an Endpoint Template, it means it should +be available to all tenants. Whenever someone authenticates to a tenant, they +will see the Endpoint generated by that template. + +When the global flag is not set, the template only shows up when it is added to +a tenant manually. To add an endpoint to a tenant manually, you must create +the Endpoint and supply the Endpoint Template ID: + +Create the Endpoint Template:: + + $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 + + Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. + +Find the Endpoint Template ID:: + + $ ./keystone-manage endpointTemplates list + + All EndpointTemplates + id service type region enabled is_global Public URL Admin URL + ------------------------------------------------------------------------------- + 15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp + 16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp + +Add the Endpoint to the tenant:: + + $ ./keystone-manage endpoint add customer-x 16 + +Now, when the user authenticates, they get the endpoint:: + + { + "internalURL": "https://compute.west.example.local", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West" + } + +Who can see the AdminURL? +------------------------- + +Users who have the Keystone `Admin` or `Service Admin` roles will see the +AdminURL when they authenticate or when they retrieve token information: + +Using an administrator token to authenticate, GET a client token's endpoints:: + + $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + + { + "endpoints": [ + { + "adminURL": "https://compute.west.example.corp", + "id": 6, + "internalURL": "https://compute.west.example.local", + "name": "nova", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West", + "tenantId": 1, + "type": "compute" + } + ], + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", + "rel": "next" + } + ] + } diff --git a/docs/source/extensions.rst b/docs/source/extensions.rst new file mode 100644 index 00000000..539bef39 --- /dev/null +++ b/docs/source/extensions.rst @@ -0,0 +1,183 @@ +.. + Copyright 2011 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. + +========== +Extensions +========== + +Extensions support adding features and functions to OpenStack APIs at any time, without prior +approval or waiting for a new API and release cycles. + +The extension framework is in development and documented in extensions_ and extensionspresentation_. + +This document describes the extensions included with Keystone, how to enable and disable them, +and briefly touches on how to write your own extensions. + +.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html +.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions + +Built-in Extensions +------------------- + +Keystone ships with a number of extensions found under the +``keystone/contib/extensions`` folder. + +The following built-in extensions are included: + +OS-KSADM + + This is an extensions that supports managing users, tenants, and roles + through the API. Without this extensions, the ony way to manage those + objects is through keystone-manage or directly in the underlying database. + + This is an Admin API extension only. + +OS-KSCATALOG + + This extensions supports managing Endpoints and prrovides the Endpoint + Template mechanism for managing bulk endpoints. + + This is an Admin API extension only. + +OS-EC2 + + This extension adds support for EC2 credentials. + + This is an Admin and Service API extension. + +RAX-GRP + + This extension adds functionality the enables groups. + + This is an Admin and Service API extension. + +RAX-KEY + + This extensions adds support for authentication with an API Key (the core + Keystone API only supports username/password credentials) + + This is an Admin and Service API extension. + +HP-IDM + + This extension adds capability to filter roles with optional service IDs + for token validation to mitigate security risks with role name conflicts. + See https://bugs.launchpad.net/keystone/+bug/890411 for more details. + + This is an Admin API extension. Applicable to validate token (GET) + and check token (HEAD) APIs only. + +OS-KSVALIDATE + + This extensions supports admin calls to /tokens without having to specify + the token ID in the URL. Instead, the ID is supplied in a header called + X-Subject-Token. This is provided as an alternative to address any security + concerns that arise when token IDs are passed as part of the URL which is + often (and by default) logged to insecure media. + + This is an Admin API extension only. + +.. note:: + + The included extensions are in the process of being rewritten. Currently + osksadm, oskscatalog, hpidm, and osksvalidate work with this new + extensions design. + + +Enabling & Disabling Extensions +------------------------------- + +The Keystone conf file has a property called extensions. This property holds +the list of supported extensions that you want enabled. If you want to +add/remove an extension from being supported, add/remove the extension key +from this property. The key is the name of the folder of the extension +under the keystone/contrib/extensions folder. + +.. note:: + + If you want to load different extensions in the service API than the Admin API + you need to use different config files. + +Creating New Extensions +----------------------- + +#. **Adopt a unique organization abbreviation.** + + This prefix should uniquely identify your organization within the community. + The goal is to avoid schema and resource collisions with similiar extensions. + (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) + +#. **Adopt a unique extension abbreviation.** + + Select an abbreviation to identify your extension, and append to + your organization prefix using a hyphen (``-``), by convention + (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). + + This combination is referred to as your extension's prefix. + +#. **Determine the scope of your extension.** + + Extensions can enhance the Admin API, Service API or both. + +#. **Create a new module.** + + Create a module to isolate your namespace based on the extension prefix + you selected:: + + keystone/contrib/extensions/admin + + ... and/or:: + + keystone/contrib/extensions/service/ + + ... based on which API you are enhancing. + + .. note:: + + In the future, we will support loading external extensions. + +#. Add static extension files for JSON (``*.json``) and XML + (``*.xml``) to the new extension module. + + Refer to `Service Guide `_ + `Sample extension XML `_ + `Sample extension JSON `_ for the the content and structure. + +#. If your extension is adding additional methods override the base class + ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. + +#. **Document your work.** + + Provide documentation to support your extension. + + Extensions documentation, WADL, and XSD files can be stored in the + ``keystone/content`` folder. + +#. Add your extension name to the list of supported extensions in The + ``keystone.conf`` file. + +Which extensions are enabled? +----------------------------- + +Discover which extensions are available (service API):: + + curl http://localhost:5000/v2.0/extensions + +... or (admin API):: + + curl http://localhost:35357/v2.0/extensions + +The response will list the extensions available. diff --git a/docs/source/images/305.svg b/docs/source/images/305.svg new file mode 100644 index 00000000..7d79464e --- /dev/null +++ b/docs/source/images/305.svg @@ -0,0 +1,158 @@ + + + + + + + + + + image/svg+xml + + + + + + + + Request + service directly + + + Auth + Component + 305 + Use proxy to + redirect to Auth + + + + + + + OpenStack + Service + + + diff --git a/docs/source/images/authComp.svg b/docs/source/images/authComp.svg new file mode 100644 index 00000000..d344b871 --- /dev/null +++ b/docs/source/images/authComp.svg @@ -0,0 +1,174 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + Auth + Component + + + OpenStack + Service + + + + + + + Reject + unauthenticated + requests + Forward + authenticated + requests + + + diff --git a/docs/source/images/both.svg b/docs/source/images/both.svg new file mode 100644 index 00000000..d29872a4 --- /dev/null +++ b/docs/source/images/both.svg @@ -0,0 +1,135 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + Auth + Component + + Auth + Component + + + OpenStack + Service + + + + + diff --git a/docs/source/images/graphs_305.svg b/docs/source/images/graphs_305.svg new file mode 100644 index 00000000..1dff61a6 --- /dev/null +++ b/docs/source/images/graphs_305.svg @@ -0,0 +1,41 @@ + + + + + + +Handle305 + + +AuthComp + +Auth +Component + + +Service + +OpenStack +Service + + + +Service:n->AuthComp:n + + +305 Use Proxy +To Redirect to Auth + + + +Start:sw->Service + + +Request +Service Directly + + + diff --git a/docs/source/images/graphs_authComp.svg b/docs/source/images/graphs_authComp.svg new file mode 100644 index 00000000..6be629c1 --- /dev/null +++ b/docs/source/images/graphs_authComp.svg @@ -0,0 +1,48 @@ + + + + + + +AuthComp + + +AuthComp + +Auth +Component + + + +AuthComp->Reject + + +Reject +Unauthenticated +Requests + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Forward +Authenticated +Requests + + + +Start->AuthComp + + + + + diff --git a/docs/source/images/graphs_authCompDelegate.svg b/docs/source/images/graphs_authCompDelegate.svg new file mode 100644 index 00000000..4788829a --- /dev/null +++ b/docs/source/images/graphs_authCompDelegate.svg @@ -0,0 +1,53 @@ + + + + + + +AuthCompDelegate + + +AuthComp + +Auth +Component + + + +AuthComp->Reject + + +Reject Requests +Indicated by the Service + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Forward Requests +with Identiy Status + + +Service->AuthComp + + +Send Response OR +Reject Message + + + +Start->AuthComp + + + + + diff --git a/docs/source/images/graphs_both.svg b/docs/source/images/graphs_both.svg new file mode 100644 index 00000000..6aa87612 --- /dev/null +++ b/docs/source/images/graphs_both.svg @@ -0,0 +1,36 @@ + + + + + + +Both + + +AuthComp + +Auth +Component + + +Together + + + +Auth +Component + + +OpenStack +Service + + +AuthComp->Together:OStack:n + + + + + diff --git a/docs/source/images/graphs_delegate_accept.svg b/docs/source/images/graphs_delegate_accept.svg new file mode 100644 index 00000000..1d86cadf --- /dev/null +++ b/docs/source/images/graphs_delegate_accept.svg @@ -0,0 +1,52 @@ + + + + + + +DelegateAcceptAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +200 Okay + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +200 Okay + + + diff --git a/docs/source/images/graphs_delegate_forbiden_basic.svg b/docs/source/images/graphs_delegate_forbiden_basic.svg new file mode 100644 index 00000000..dcd62b77 --- /dev/null +++ b/docs/source/images/graphs_delegate_forbiden_basic.svg @@ -0,0 +1,53 @@ + + + + + + +DelegateRejectForbidden + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +403 Forbidden + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +403 Forbidden +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_delegate_forbiden_proxy.svg b/docs/source/images/graphs_delegate_forbiden_proxy.svg new file mode 100644 index 00000000..df53212b --- /dev/null +++ b/docs/source/images/graphs_delegate_forbiden_proxy.svg @@ -0,0 +1,52 @@ + + + + + + +DelegateForbiddnProxy + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +500 Internal Error + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +403 Forbidden + + + diff --git a/docs/source/images/graphs_delegate_reject_basic.svg b/docs/source/images/graphs_delegate_reject_basic.svg new file mode 100644 index 00000000..a33ea095 --- /dev/null +++ b/docs/source/images/graphs_delegate_reject_basic.svg @@ -0,0 +1,55 @@ + + + + + + +DelegateRejectAuthBasic + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic Yjpw + + +AuthComp->Start + + +401 Unauthorized +WWW-Authenticate: Basic +Realm="API Realm" + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy b +X-Identity-Status: Indeterminate + + +Service->AuthComp + + +401 Unauthorized +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_delegate_reject_oauth.svg b/docs/source/images/graphs_delegate_reject_oauth.svg new file mode 100644 index 00000000..760adeb6 --- /dev/null +++ b/docs/source/images/graphs_delegate_reject_oauth.svg @@ -0,0 +1,56 @@ + + + + + + +DelegateRejectAuthOAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: OAuth 000-999-222 + + +AuthComp->Start + + +401 Unauthorized +WWW-Authenticate: OAuth +Realm=’API Realm’, +Error=’invalid-token’ + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy +X-Identity-Status: Indeterminate + + +Service->AuthComp + + +401 Unauthorized +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_delegate_unimplemented.svg b/docs/source/images/graphs_delegate_unimplemented.svg new file mode 100644 index 00000000..8c4fdc6b --- /dev/null +++ b/docs/source/images/graphs_delegate_unimplemented.svg @@ -0,0 +1,53 @@ + + + + + + +DelegateUnimplemented + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +500 Internal Error + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +501 Unimplemented +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_mapper.svg b/docs/source/images/graphs_mapper.svg new file mode 100644 index 00000000..52c6c55b --- /dev/null +++ b/docs/source/images/graphs_mapper.svg @@ -0,0 +1,73 @@ + + + + + + +Mapper + + + +Mapper + +Mapper + + +Start->Mapper + + + + +Auths + + + +Auth1 + + +Auth2 + + +Auth3 + + +Mapper:sw->Auths:auth1 + + + + +Mapper:s->Auths:auth2 + + + + +Mapper:se->Auths:auth3 + + + + +Service + +OpenStack +Service + + +Auths:auth1->Service + + + + +Auths:auth2->Service + + + + +Auths:auth3->Service + + + + + diff --git a/docs/source/images/graphs_proxyAuth.svg b/docs/source/images/graphs_proxyAuth.svg new file mode 100644 index 00000000..7b94b077 --- /dev/null +++ b/docs/source/images/graphs_proxyAuth.svg @@ -0,0 +1,51 @@ + + + + + + +ProxyAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp:w->Start + + +500 Internal Error + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U + + +Service:w->AuthComp + + +403 Forbidden + + + diff --git a/docs/source/images/graphs_separate.svg b/docs/source/images/graphs_separate.svg new file mode 100644 index 00000000..376e5988 --- /dev/null +++ b/docs/source/images/graphs_separate.svg @@ -0,0 +1,30 @@ + + + + + + +Seperate + + +AuthComp + +Auth +Component + + +Service + +OpenStack +Service + + +AuthComp->Service + + + + + diff --git a/docs/source/images/graphs_standard_accept.svg b/docs/source/images/graphs_standard_accept.svg new file mode 100644 index 00000000..bddf4b5f --- /dev/null +++ b/docs/source/images/graphs_standard_accept.svg @@ -0,0 +1,51 @@ + + + + + + +StandardAcceptAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +200 Okay + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U + + +Service->AuthComp + + +200 Okay + + + diff --git a/docs/source/images/graphs_standard_reject.svg b/docs/source/images/graphs_standard_reject.svg new file mode 100644 index 00000000..6020ad67 --- /dev/null +++ b/docs/source/images/graphs_standard_reject.svg @@ -0,0 +1,39 @@ + + + + + + +StandardRejectAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic Yjpw + + +AuthComp->Start + + +401 Unauthorized +WWW-Authenticate: Basic Realm="API Realm" + + +Service + +OpenStack +Service + + + diff --git a/docs/source/images/graphs_together.svg b/docs/source/images/graphs_together.svg new file mode 100644 index 00000000..1425a28b --- /dev/null +++ b/docs/source/images/graphs_together.svg @@ -0,0 +1,24 @@ + + + + + + +Together + + +Together + + +Auth +Component + + +OpenStack +Service + + + diff --git a/docs/source/images/images_layouts.svg b/docs/source/images/images_layouts.svg new file mode 100644 index 00000000..e7fe7a95 --- /dev/null +++ b/docs/source/images/images_layouts.svg @@ -0,0 +1,200 @@ + + + + + + image/svg+xml + + + + + + + + Auth Layouts + (a) + (b) + + + Together + + + + Together + + + Auth + Component + + + OpenStack + Service + + + + Seperate + + + + AuthComp + + Auth + Component + + + + Service + + OpenStack + Service + + + + AuthComp->Service + + + + + diff --git a/docs/source/images/layouts.svg b/docs/source/images/layouts.svg new file mode 100644 index 00000000..fdf61b7d --- /dev/null +++ b/docs/source/images/layouts.svg @@ -0,0 +1,215 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + Auth + Component + + + OpenStack + Service + + + Option + ( + b + ) + + + Auth + Component + + + OpenStack + Service + Option + ( + a + ) + + + + diff --git a/docs/source/images/mapper.svg b/docs/source/images/mapper.svg new file mode 100644 index 00000000..b5a2b7b1 --- /dev/null +++ b/docs/source/images/mapper.svg @@ -0,0 +1,237 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + OpenStack + Service + + + + + + + + + + + + + + + Mapper + + + Auth + 1 + + + Auth + 2 + + + Auth + 3 + + + + + diff --git a/docs/source/images/proxyAuth.svg b/docs/source/images/proxyAuth.svg new file mode 100644 index 00000000..f60b40d8 --- /dev/null +++ b/docs/source/images/proxyAuth.svg @@ -0,0 +1,238 @@ + + + + + + + + + + image/svg+xml + + + + + + + + Authorization + : + Basic dTpw + X + - + Authorization + : + Proxy U + Authorization + : + Basic VTpQ + 500 + Internal Error + 403 + Proxy Unauthorized + + + + + Auth + Component + + + + + OpenStack + Service + + + + + + + diff --git a/docs/source/middleware.rst b/docs/source/middleware.rst new file mode 100644 index 00000000..69506ee2 --- /dev/null +++ b/docs/source/middleware.rst @@ -0,0 +1,169 @@ +.. + Copyright 2011 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 +========== + +The Keystone middleware sits in front of an OpenStack service and handles authenticating +incoming requests. The middleware was designed according to `this spec`. + +The middleware is found in source under Keystone/middleware. + +The middleware supports two interfaces; WSGI and REST/HTTP. + +.. _`this spec`: http://wiki.openstack.org/openstack-authn + +REST & HTTP API +=============== + +If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per +HTTP standards, it will also return a WWW-Authenticate header informing the caller +of what protocols are supported. For Keystone authentication, the response syntax will be:: + + WWW-Authenticate: Keystone uri="url to Keystone server" + +The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token. + +The token is passed in using ther X-Auth-Token header. + +WSGI API (Headers) +================== + +Upon successful authentication the middleware sends the following +headers to the downstream WSGI app: + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +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-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-Roles + The roles associated with that user + + +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 = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 + +*The required configuration entries are:* + +auth_host + The IP address or DNS name of the Keystone server + +auth_port + The TCP/IP port of the Keystone server + +auth_protocol + The protocol of the Keystone server ('http' or 'https') + +auth_uri + The externally accessible URL of the Keystone server. This will be where unauthenticated + clients are redirected to. This is in the form of a URL. For example, if they make an + unauthenticated call, they get this response:: + + HTTP/1.1 401 Unauthorized + Www-Authenticate: Keystone uri='https://auth.example.com/' + Content-Length: 381 + + In this case, the auth_uri setting is set to https://auth.example.com/ + +admin_token + This is the long-lived token issued to the service to authenticate itself when calling + Keystone. See :doc:`configuration` for more information on setting this up. + + +*Optional parameters are:* + +delay_auth_decision + Whether the middleware should reject invalid or unauthenticated calls directly or not. If not, + it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS + header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the + service can then decide if it wants to honor the call or not. This is useful if the service offers + some resources publicly, for example. + +auth_timeout + The amount of time to wait before timing out a call to Keystone (in seconds) + +memcache_hosts + This is used to point to a memcached server (in ip:port format). If supplied, + the middleware will cache tokens and data retrieved from Keystone in memcached + to minimize calls made to Keystone and optimize performance. + +.. warning:: + Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone, + the service will not know and will continue to honor the token as it has them stored in memcached. + Also note that tokens and data stored in memcached are not encrypted. The memcached server must + be trusted and on a secure network. + + +*Parameters needed in a distributed topology.* In this configuration, the middleware is running +on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture` +for details on different deployment topologies): + +service_host + The IP address or DNS name of the location of the service (since it is remote + and not automatically down the WSGI chain) + +service_port + The TCP/IP port of the remote service. + +service_protocol + The protocol of the service ('http' or 'https') + +service_pass + The basic auth password used to authenticate to the service (so the service + knows the call is coming from a server that has validated the token and not from + an untrusted source or spoofer) + +service_timeout + The amount of time to wait for the service to respond before timing out. diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst new file mode 100644 index 00000000..a8c38f3c --- /dev/null +++ b/docs/source/middleware_architecture.rst @@ -0,0 +1,529 @@ +.. + Copyright 2011 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 multiple authentication protocols +in a pluggable manner in OpenStack. By providing support for authentication via +pluggable authentication components, this architecture allows OpenStack +services to be integrated easily into existing deployment environments. It also +provides a path by which to implement support for emerging authentication +standards such as OAUTH. + +Rationale and Goals +=================== + +Keystone is the Identity service for OpenStack. To support the easy integrating +of OpenStack with existing authentication and identity management systems, +Keystone supports talking to multiple backends like LDAP. +And to support different deployment needs, it can support multiple +authentication protocols via pluggable 'authentication components' implemented +as WSGI middleware. + +In this document, we describe the responsibilities of the authentication +middleware. We describe how these interact with underlying OpenStack services +and how existing services can be modified to take advantage of pluggable +authentication. The goal is to allow OpenStack services to be integrated easily +into existing deployment environments and to provide a path by which to +implement support for emerging authentication standards such as OAUTH. + +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. + +At a high level, an authentication component is simply a reverse proxy that +intercepts HTTP calls from clients. Once it has verified a user's identity, the +authentication component extends the call with information about the current +user and forwards the request to the OpenStack service. Otherwise, if a user's +identity is not verified, the message is rejected before it gets to the +service. This is illustrated in :ref:`authComponent`. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +Authentication components may operate in 'delegated mode'. In this mode, the +decision reject an unauthenticated client is delegated to the OpenStack +service. Delegated mode is 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. Note that it is always the responsibility +of the Authentication Component to transmit reject messages 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) + +In this architecture, we define interactions between the authentication component +and the OpenStack service. Interactions between the client and the +authentication component are defined only for exceptional cases. For example, +we define the message that should be returned when the OpenStack service is +down. Other interactions, however, are defined by the underlying authentication +protocol and the OpenStack service and are considered out of scope. + +.. _deployStrategies: + +Deployment Strategies +===================== + +An authentication component may be integrated directly into the service +implementation, or it may be deployed separately as an HTTP reverse proxy. This +is illustrated in :ref:`deployment`, showing both approaches to +authentication, labeled Option (a) and Option (b). + +.. _deployment: + +Authentication Component Deployments Options +-------------------------------------------- + +Figure 3. Authentication Component Deployments Options + +.. image:: images/images_layouts.svg + :width: 100% + :height: 180 + :alt: Authentication Component Deployments Options + +In Option (a), the component is integrated into the service implementation. In +this case, communication between the authentication component and the service +can be efficiently implemented via a method call. In Option (b), the component +is deployed separately and communication between the service and the component +involves an HTTP request. In both cases, unauthenticated requests are filtered +before they reach the service. + +Each approach offers some benefits. Option (a) offers low latency and ease of +initial implementation, making it possibly most appropriate as a starting point +for simple configurations. Option (b) offers several key advantages that may be +of particular value in complex and dynamic configurations. It offers the +ability to scale horizontally in cases where authentication is computationally +expensive, such as when verifying digital signatures. Option (b) also allows +authentication components to be written in different programming languages. +Finally, Option (b) allows multiple authentication components to be deployed in +front of the same service. + +OpenStack services can support both embedded (Option (a)) and external (Option +(b)) deployment strategies. Individual authentication components should support +either strategy or they |may| support both strategies. In order to support +option (a), authentication components written in the Python programming +language should be written as WSGI middleware components (in accordance with +the Web Server Gateway Interface (WSGI) standard [PEP-333]_. + +Additionally, services should support the ability to swap between different +embedded or external authentication components via configuration options. + +Exchanging User Information +=========================== + +If a request is successfully authenticated, the authentication component must +extend the request by adding an ``X-Authorization`` header. The header |must| +be formatted as illustrated in :ref:`xAuthHeader`. + +.. _xAuthHeader: + +X-Authorization Header +---------------------- + +Example 1. X-Authorization Header:: + + X-Authorization: Proxy JoeUser + +Here, `Proxy` denotes that the authentication occurred via a proxy (in this +case authentication component) and ''JoeUser'' is the name of the user who +issued the request. + +.. note: + + We considered using an ``Authorization`` header rather than an + ``X-Authorization``, thereby following normal HTTP semantics. There are some + cases, however, where multiple ``Authorization`` headers need to be transmitted + in a single request. We want to assure ourselves that this will not break + common clients before we recommend the approach. + +Authentication components |may| extend the request with additional +information. For example, an authentication system may add additional headers +or modify the target URI to pass authentication information to the back-end +service. Additionally, an authentication component |may| strip sensitive +information — a plain text password, for example — from the request. That said, +an authentication component |should| pass the majority of the request +unmodified. + +Reverse Proxy Authentication +---------------------------- + +An OpenStack service |should| verify that it is receiving requests from a +trusted authentication component. This is particularly important in cases where +the authentication component and the OpenStack service are deployed separately. +In order to trust incoming requests, the OpenStack service should therefore +authenticate the authentication component. To avoid confusion, we call this +'reverse proxy authentication', since in this case the authentication +component is acting as an HTTP reverse proxy. + +Any HTTP-based authentication scheme may be used for reverse proxy +authentication; however, all OpenStack services and all authentication +components |must| support HTTP Basic Authentication as defined in +[RFC-2617]_. + +Whether or not reverse proxy authentication is required is strictly a +deployment concern. For example, an operations team may opt to utilize firewall +rules instead of an authentication protocol to verify the integrity of incoming +request. Because of this, both OpenStack services and authentication components +|must| also allow for unauthenticated communication. + +In cases where reverse proxy authentication is used, the authorization +component may receive an HTTP 401 authentication error or an HTTP 403 +authorization error. These errors indicate that the component does not have +access to the underlying OpenStack service. The authentication component +|must not| return these errors to the client application. Instead, the +component |must| return a 500 internal error. This is illustrated in +:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component +|should| format the errors in a manner that does not break the service +contract defined by the OpenStack service. :ref:`proxyAuthDelegated` +illustrates proxy authorization in delegated mode. Delegated mode is discussed +in detail in the next section. + +.. _proxyAuth: + +Reverse Proxy Authentication +---------------------------- + +Figure 4. Reverse Proxy Authentication + +.. image:: images/graphs_proxyAuth.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication + +.. _proxyAuthDelegated: + +Reverse Proxy Authentication (Delegated Mode) +--------------------------------------------- + +Figure 5. Reverse Proxy Authentication (Delegated Mode) + +.. image:: images/graphs_delegate_forbiden_proxy.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication (Delegated Mode) + +Delegated Mode +============== +In some cases, the decision to reject an unauthenticated request should be +delegated to the OpenStack service. An unauthenticated request may be +appropriate in cases when anonymous access is allowed. In order to support +these cases, an authentication component may be placed in Delegated Mode. In +this mode, the component forwards requests to the OpenStack service when the +client's identity has been confirmed or is indeterminate — that is when +credentials are missing. The authentication component directly rejects requests +with invalid credentials. Authentication components |must| extend the +request by adding an `X-Identity-Status` header. The identity status header +|must| contain one of the following values: + +Identity Status Values +---------------------- + +Confirmed + A `confirmed` value indicates that valid credentials were sent and identity + has been confirmed. The service can trust that the request has been sent on + behalf of the user specified in the `X-Authorization` header. + +Indeterminate + An `indeterminate` value indicates that no credentials were sent and + identity has not been confirmed. In this case, the service will receive an + `X-Authorization` header with no user entry as illustrated in + :ref:`xauth-header-indeterminate`. + +.. _xauth-header-indeterminate: + +Indeterminate Identity Headers +------------------------------ + +Example 2. Indeterminate Identity Headers:: + + X-Identity-Status: Indeterminate + X-Authorization: Proxy + +Services |may| reject a delegated request by issuing an HTTP 401 +authentication error or an HTTP 403 authorization error. These responses +|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as +illustrated in :ref:`unauthHeaders`. + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +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-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-Roles + The roles associated with that user + +.. _unauthHeaders: + +Delegated WWW-Authenticate Header +--------------------------------- + +:: + + WWW-Authenticate: Delegated + +It is important to note that the actual reject message will likely be modified +by the authentication component in order to comply with the authentication +scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and +:ref:`delegateRejectOAuth` below. + +.. _delegateRejectBasic: + +Delegated Reject Basic Auth +--------------------------- + +.. image:: images/graphs_delegate_reject_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Basic Auth + +.. _delegateRejectOAuth: + +Delegated Reject OAuth +---------------------- + +.. image:: images/graphs_delegate_reject_oauth.svg + :width: 100% + :height: 180 + :alt: Delegated Reject OAuth + +The presence of the `WWW-Authenticate` header with a value of `Delegated` +distinguishes a client authentication/authorization failure from a component +failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In +:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. +In :ref:`proxyAuthDelegated`, it is the authentication component itself which is +unauthorized. + +.. _delegateForbidden: + +Delegated Reject Forbidden +-------------------------- + +Figure 8. Delegated Reject Forbidden + +.. image:: images/graphs_delegate_forbiden_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Forbidden + +Authentication components |must| support both delegated and undelegated +(standard) modes. Delegated mode |should| be configured via a configuration +option. Delegated mode |should| be disabled by default. + +OpenStack services are not required to support delegated mode. If a service +does not support delegated mode, it |must| respond with a 501 not implemented +error and an `WWW-Authenticate` header with a value of `Delegated`. The +authentication component |must not| return the error to the client +application. Instead, the component |must| return a 500 internal error; this is +illustrated in :ref:`delegateUnimplemented`. The component |should| +format the error in a manner that does not break the service contract defined +by the OpenStack service. The component should also log the error such that it +that will inform operators of the misconfiguration. + +.. _delegateUnimplemented: + +Unimplemented Delegated Mode +---------------------------- + +.. image:: images/graphs_delegate_unimplemented.svg + :width: 100% + :height: 180 + :alt: Unimplemented Delegated Mode + +Handling Direct Client Connections +================================== + +Requests from the authentication component to an OpenStack service |must| +contain an ``X-Authorization`` header. If the header is missing, and reverse +proxy authentication fails or is switched off, the OpenStack service |may| +assume that the request is coming directly from a client application. In this +case, the OpenStack service |must| redirect the request to the authentication +component by issuing an HTTP 305 User Proxy redirect. This is illustrated in +:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header +specifying the authentication component's URL as shown in :ref:`redirect-response`. + +.. _redirect: + +Auth Component Redirect +----------------------- + +.. image:: images/graphs_305.svg + :width: 100% + :height: 280 + :alt: Auth Component Redirect + +.. _redirect-response: + +Auth Component Redirect Response +-------------------------------- + +:: + + HTTP/1.1 305 Use Proxy + Date: Thu, 28 Oct 2011 07:41:16 GMT + Location: http://sample.auth.openstack.com/path/to/resource + +Using Multiple Authentication Components +======================================== + +There are some use cases when a service provider might want to consider using +multiple authentication components for different purposes. For instance, a +service provider may have one authentication scheme to authenticate the users +of the service and another one to authenticate the administrators or operations +personnel that maintain the service. For such scenarios, we propose using a +mapper as illustrated in :ref:`multiAuth`. + +.. _multiAuth: + +Multiple Authentication Components +---------------------------------- + +.. image:: images/graphs_mapper.svg + :width: 100% + :height: 320 + :alt: Multiple Authentication Components + +At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls +from clients and routes the request to the appropriate authentication +component. A mapper can make the routing decisions based on a number of routing +rules that map a resource to a specific authentication component. For example, +a request URI may determine whether a call should be authenticated via one +authentication component or another. + +Note that neither the authentication component nor the OpenStack service need +be aware of the mapper. Any external authentication component can be used +alongside others. Mappers may provide a means by which to offer support for +anonymous or guest access to a subset of service resources. A mapper may be +implemented via a traditional reverse proxy server such as Pound or Zeus. + +The Default Component +===================== + +Individual services |must| be distributed with a simple integrated +authentication component by default. Providing such a component lowers barriers +to the deployment of individual services. This is especially important to] +developers who may want to deploy OpenStack services on their own machines. +Also, since there is no direct dependency on an external authentication system, +OpenStack services can be deployed individually, without the need to stand up +and configure additional services. Finally, having a standard authentication +component that all services share promotes a separation of concerns. That is, +as a community we are explicitly stating that services should not develop their +own authentication mechanisms. Additional authentication components may be +developed, of course, but these components should not be intimately coupled to +any one particular service. + +As discussed in :ref:`deployStrategies`, an authentication component may be +integrated directly into the service implementation (Option (a)), or it may be +deployed separately as an HTTP reverse proxy (Option (b)). The default +component should be implemented to support Option (a) and services should +maintain support for Option (b). One way to achieve this is to provide a +method that allows the disabling of the default authentication component via +configuration. This is illustrated in :ref:`both`. Here, requests are +sent directly to the OpenStack service when the default authentication +component is disabled. + +We will discuss the design of the default component in an upcoming blueprint. + +.. _both: + +Disabled Embedded Component +--------------------------- + +.. image:: images/graphs_both.svg + :width: 100% + :height: 250 + :alt: Disabled Embedded Component + +Questions and Answers +===================== + +#. Why do authentication components send reject messages? Why not have + OpenStack services reject requests themselves? + + The content and format of an authentication failed message is determined by + the authentication scheme (or protocol). For the service to respond + appropriately, it would have to be aware of the authentication scheme in + which it participates; this defeats the purpose of pluggable authentication + components. + +#. Why require support for deploying authentication components in separate + nodes? + + The deployment strategy is very flexible. It allows for authentication + components to be horizontally scalable. It allows for components to be written + in different languages. Finally, it allows different authentication components + to be deployed simultaneously as described above. + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. + +.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. + P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest + Access Authentication.'' http://tools.ietf.org/html/rfc2617. + +.. |must| replace:: must must +.. |should| replace:: should should +.. |may| replace:: may may +.. |must not| replace:: "must not" "must not" + diff --git a/docs/source/migration.rst b/docs/source/migration.rst new file mode 100644 index 00000000..460d980b --- /dev/null +++ b/docs/source/migration.rst @@ -0,0 +1,126 @@ +=================== +Database Migrations +=================== + +Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage +migrations. + +Migrations are tracked using a metadata table (``migrate_version``), which +allows keystone to compare the state of your database to the state it +expects, and to move between versions. + +.. WARNING:: + + Backup your database before applying migrations. Migrations may + attempt to modify both your schema and data, and could result in data + loss. + + Always review the behavior of migrations in a staging environment + before applying them in production. + +Getting Started +=============== + +Your initial approach to migrations should depend on whether you have an +empty database or a schema full of data. + +Starting with an empty database +------------------------------- + +If you have an empty database for keystone to work with, you can simply +run:: + + $ ./bin/keystone-manage database sync + +This command will initialize your metadata table, and run through all the +schema & data migrations necessary to bring your database in sync with +keystone. That's it! + +Starting with an existing database +---------------------------------- + +Place an existing database under version control to enable migration +support:: + + $ ./bin/keystone-manage database version_control + +This command simply creates a ``migrate_version`` table, set at +``version_number`` 0, which indicates that no migrations have been applied. + +If you are starting with an existing schema, you can jump to a specific +schema version without performing migrations using the ``database goto`` +command. For example, if you're starting from a diablo-compatible +database, set your current database ``version_number`` to ``1`` using:: + + $ ./bin/keystone-manage database goto + +Determine your appropriate database ``version_number`` by referencing the +following table: + + +------------+-------------+ + | Release | ``version`` | + +============+=============+ + | pre-diablo | (see below) | + +------------+-------------+ + | diablo | 1 | + +------------+-------------+ + | essex-m1 | 3 | + +------------+-------------+ + | essex-m2 | 4 | + +------------+-------------+ + +From there, you can upgrade normally (see :ref:`upgrading`). + +Starting with a pre-diablo database (cactus) +-------------------------------------------- + +You'll need to manually migrate your database to a diablo-compatible +schema, and continue forward from there (if desired) using migrations. + +.. _upgrading: + +Upgrading & Downgrading +======================= + +.. note:: + + Attempting to start keystone with an outdated schema will cause + keystone to abort, to avoid corrupting your data. + +Upgrade to the latest version automatically:: + + $ ./bin/keystone-manage database sync + +Check your current schema version:: + + $ ./bin/keystone-manage database version + +Jump to a specific version without performing migrations:: + + $ ./bin/keystone-manage database goto + +Upgrade to a specific version:: + + $ ./bin/keystone-manage database upgrade + +Downgrade to a specific version (will likely result in data loss!):: + + $ ./bin/keystone-manage database downgrade + +Opting Out of Migrations +======================== + +If you don't want to use migrations (e.g. if you want to manage your +schema manually), keystone will complain in your logs on startup, but +won't actually stop you from doing so. + +It's recommended that you use migrations to get up and running, but if +you want to manage migrations manually after that, simply drop the +``migrate_version`` table:: + + DROP TABLE migrate_version; + +Useful Links +============ + +Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst new file mode 100644 index 00000000..586bac72 --- /dev/null +++ b/docs/source/nova-api-paste.rst @@ -0,0 +1,142 @@ +.. + Copyright 2011 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. + +nova-api-paste example +====================== +:: + + ####### + # EC2 # + ####### + + [composite:ec2] + use = egg:Paste#urlmap + /: ec2versions + /services/Cloud: ec2cloud + /services/Admin: ec2admin + /latest: ec2metadata + /2007-01-19: ec2metadata + /2007-03-01: ec2metadata + /2007-08-29: ec2metadata + /2007-10-10: ec2metadata + /2007-12-15: ec2metadata + /2008-02-01: ec2metadata + /2008-09-01: ec2metadata + /2009-04-04: ec2metadata + /1.0: ec2metadata + + [pipeline:ec2cloud] + pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor + + [pipeline:ec2admin] + pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor + + [pipeline:ec2metadata] + pipeline = logrequest ec2md + + [pipeline:ec2versions] + pipeline = logrequest ec2ver + + [filter:logrequest] + paste.filter_factory = nova.api.ec2:RequestLogging.factory + + [filter:ec2lockout] + paste.filter_factory = nova.api.ec2:Lockout.factory + + [filter:totoken] + paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory + + [filter:ec2noauth] + paste.filter_factory = nova.api.ec2:NoAuth.factory + + [filter:authenticate] + paste.filter_factory = nova.api.ec2:Authenticate.factory + + [filter:cloudrequest] + controller = nova.api.ec2.cloud.CloudController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:adminrequest] + controller = nova.api.ec2.admin.AdminController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:authorizer] + paste.filter_factory = nova.api.ec2:Authorizer.factory + + [app:ec2executor] + paste.app_factory = nova.api.ec2:Executor.factory + + [app:ec2ver] + paste.app_factory = nova.api.ec2:Versions.factory + + [app:ec2md] + paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory + + ############# + # Openstack # + ############# + + [composite:osapi] + use = egg:Paste#urlmap + /: osversions + /v1.1: openstackapi + + [pipeline:openstackapi] + pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp + + [filter:faultwrap] + paste.filter_factory = nova.api.openstack:FaultWrapper.factory + + [filter:auth] + paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory + + [filter:noauth] + paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory + + [filter:ratelimit] + paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory + + [filter:extensions] + paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory + + [app:osapiapp] + paste.app_factory = nova.api.openstack:APIRouter.factory + + [pipeline:osversions] + pipeline = faultwrap osversionapp + + [app:osversionapp] + paste.app_factory = nova.api.openstack.versions:Versions.factory + + ########## + # Shared # + ########## + + [filter:keystonecontext] + paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory + + [filter:authtoken] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + service_protocol = http + service_host = 127.0.0.1 + service_port = 5000 + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/releases.rst b/docs/source/releases.rst new file mode 100644 index 00000000..a4b698d7 --- /dev/null +++ b/docs/source/releases.rst @@ -0,0 +1,36 @@ +============= +Release notes +============= + + +E3 (January 26, 2012) +========================================== +* Contract compliance: version response and ATOM, 300 multiple choice +* Global endpoints returned for unscoped calls +* adminUrl only shown to admin clients +* Endpoints have unique ID +* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) +* Default tenant scope optionally returned when authenticating +* Vary header returned for caching proxies + +* Portable identifiers: modifiable, string identifiers in database backend +* Much improved keystone-manage command (see --help and docs) +* OS-KSVALIDATE extension to support not passing tokens in URL +* OS-KSEC2 and OS-KSS3 extensions respond on /tokens +* HP-IDM extension to filter roles to a given service ID +* Additional caching options in middleware (memcache and swift cache) + +* Enhanced configuration management (in line with other OpenStack projects) +* Additional logging +* Enhanced tracer tool (-t or --trace-calls) + +See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 + + +E2 (December 15, 2011) +======================== +* D5 compatibility middleware +* Database versioning +* Much more documentation: http://keystone.openstack.org + +See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/docs/source/serviceAPI_curl_examples.rst b/docs/source/serviceAPI_curl_examples.rst new file mode 100644 index 00000000..d05afc9f --- /dev/null +++ b/docs/source/serviceAPI_curl_examples.rst @@ -0,0 +1,69 @@ +.. + Copyright 2011 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. + +=============================== +Service API Examples Using Curl +=============================== + +The service API is defined to be a subset of the Admin API and, by +default, runs on port 5000. + +GET / +===== + +This call is identical to that documented for the Admin API, except +that it uses port 5000, instead of port 35357, by default:: + + $ curl http://0.0.0.0:5000 + +or:: + + $ curl http://0.0.0.0:5000/v2.0/ + +See the `Admin API Examples Using Curl`_ for more info. + +.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html + +GET /extensions +=============== + +This call is identical to that documented for the Admin API. + +POST /tokens +============ + +This call is identical to that documented for the Admin API. + +GET /tenants +============ + +List all of the tenants your token can access:: + + $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } diff --git a/docs/source/services.rst b/docs/source/services.rst new file mode 100644 index 00000000..d1c33381 --- /dev/null +++ b/docs/source/services.rst @@ -0,0 +1,92 @@ +.. + Copyright 2011 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. + +================ +Services +================ + +.. toctree:: + :maxdepth: 1 + + +What are services? +================== + +Keystone includes service registry and service catalog functionality which it +uses to respond to client authentication requests with information useful to +clients in locating the list of available services they can access. + +The Service entity in Keystone represents an OpenStack service that is integrated +with Keystone. The Service entity is also used as a reference from roles, endpoints, +and endpoint templates. + +Keystone also includes an authorization mechanism to allow a service to own +its own roles and endpoints and prevent other services from changing or +modifying them. + +Who can create services? +======================== + +Any user with the Admin or Service Admin roles in Keystone may create services. + +How are services created? +========================= + +Services can be created using ``keystone-manage`` or through the REST API using +the OS-KSADM extension calls. + +Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: + + $ keystone-manage add service compute nova 'This is a sample compute service' + +Using the REST API (see `extensions dev guide `_ for details):: + + $ curl -H "Content-type: application/json" -X POST -d '{ + "OS-KSADM:service": { + "name": "nova", + "type": "compute", + "description": "This is a sample compute service" + } + }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ + +How is service ownership determined? +==================================== + +Currently, the way to assign ownership to a service is to provide the owner's +user id in the keystone-manage add command:: + + $ keystone-manage add service nova compute 'This is a sample compute service' joeuser + +This will assign ownership to the new service to joeuser. + +When a service has an owner, then only that owner (or a global Admin) can create and manage +roles that start with that service name (ex: "nova:admin") and manage endpoints +and endpoint templates associated with that service. + +Listing services +================ + +Using ``keystone-manage``, the list of services and their owners can be listed:: + + $ keystone-manage service list + + id name type owner_id description + ------------------------------------------------------------------------------- + 1 compute nova joeuser This is a sample compute service + +Using the REST API, call ``GET /v2.0/OS-KSADM/services`` + +.. note: The rest API does not yet support service ownership diff --git a/docs/source/ssl.rst b/docs/source/ssl.rst new file mode 100644 index 00000000..839e951e --- /dev/null +++ b/docs/source/ssl.rst @@ -0,0 +1,118 @@ +.. + Copyright 2011 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. + +=========================== +x.509 Client Authentication +=========================== + +Purpose +======= + +Allows the Keystone middleware to authenticate itself with the Keystone server +via an x.509 client certificate. Both Service API and Admin API may be secured +with this feature. + +Certificates +============ + +The following types of certificates are required. A set of certficates is provided +in the examples/ssl directory with the Keystone distribution for testing. Here +is the description of each of them and their purpose: + +ca.pem + Certificate Authority chain to validate against. + +keystone.pem + Public certificate for Keystone server. + +middleware-key.pem + Public and private certificate for Keystone middleware. + +cakey.pem + Private key for the CA. + +keystonekey.pem + Private key for the Keystone server. + +Note that you may choose whatever names you want for these certificates, or combine +the public/private keys in the same file if you wish. These certificates are just +provided as an example. + +Configuration +============= + +By default, the Keystone server does not use SSL. To enable SSL with client authentication, +modify the etc/keystone.conf file accordingly: + +1. To enable SSL for Service API:: + + service_ssl = True + +2. To enable SSL for Admin API:: + + admin_ssl = True + +3. To enable SSL client authentication:: + + cert_required = True + +4. Set the location of the Keystone certificate file (example):: + + certfile = /etc/keystone/ca/certs/keystone.pem + +5. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/private/keystonekey.pem + +6. Set the location of the CA chain:: + + ca_certs = /etc/keystone/ca/certs/ca.pem + +Middleware +========== + +Add the following to your middleware configuration to support x.509 client authentication. +If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters +in steps 3) and 4) may be commented out. + +1. Specify 'https' as the auth_protocol:: + + auth_protocol = https + +2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured + for SSL:: + + auth_uri = https://localhost:5000/ + +3. Set the location of the middleware certificate file (example):: + + certfile = /etc/keystone/ca/certs/middleware-key.pem + +4. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/certs/middleware-key.pem + +For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example +service in the examples/echo directory. + +Testing +======= + +You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory +and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with +the path to the client certificate:: + + python echo_client.py -s diff --git a/docs/source/usingkeystone.rst b/docs/source/usingkeystone.rst new file mode 100644 index 00000000..bb52a94d --- /dev/null +++ b/docs/source/usingkeystone.rst @@ -0,0 +1,28 @@ +.. + Copyright 2011 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. + +============== +Using Keystone +============== + +Curl examples +------------- + +.. toctree:: + :maxdepth: 1 + + adminAPI_curl_examples + serviceAPI_curl_examples -- cgit From e643f239816bae29e8206407db3d5eabdd2ea4b0 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 10:57:02 -0800 Subject: doc updates --- docs/source/api_curl_examples.rst | 442 ++++++++++++++++++++++++++++++++++++ docs/source/architecture.rst | 4 + docs/source/community.rst | 26 +-- docs/source/configuration.rst | 224 ++++++++++++++---- docs/source/developing.rst | 130 +++++------ docs/source/index.rst | 20 +- docs/source/man/keystone-manage.rst | 241 ++++++++++++-------- docs/source/man/keystone.rst | 69 +++--- docs/source/setup.rst | 71 ++++-- docs/source/testing.rst | 77 ------- 10 files changed, 918 insertions(+), 386 deletions(-) create mode 100644 docs/source/api_curl_examples.rst delete mode 100644 docs/source/testing.rst (limited to 'docs/source') diff --git a/docs/source/api_curl_examples.rst b/docs/source/api_curl_examples.rst new file mode 100644 index 00000000..686e8bd5 --- /dev/null +++ b/docs/source/api_curl_examples.rst @@ -0,0 +1,442 @@ +.. + Copyright 2011 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. + + +=============================== +Service API Examples Using Curl +=============================== + +The service API is defined to be a subset of the Admin API and, by +default, runs on port 5000. + +GET / +===== + +This call is identical to that documented for the Admin API, except +that it uses port 5000, instead of port 35357, by default:: + + $ curl http://0.0.0.0:5000 + +or:: + + $ curl http://0.0.0.0:5000/v2.0/ + +See the `Admin API Examples Using Curl`_ for more info. + +.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html + +GET /extensions +=============== + +This call is identical to that documented for the Admin API. + +POST /tokens +============ + +This call is identical to that documented for the Admin API. + +GET /tenants +============ + +List all of the tenants your token can access:: + + $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } + +============================= +Admin API Examples Using Curl +============================= + +These examples assume a default port value of 35357, and depend on the +``sampledata`` bundled with keystone. + +GET / +===== + +Disover API version information, links to documentation (PDF, HTML, WADL), +and supported media types:: + + $ curl http://0.0.0.0:35357 + +or:: + + $ curl http://0.0.0.0:35357/v2.0/ + +Returns:: + + { + "version":{ + "id":"v2.0", + "status":"beta", + "updated":"2011-11-19T00:00:00Z", + "links":[ + { + "rel":"self", + "href":"http://127.0.0.1:35357/v2.0/" + }, + { + "rel":"describedby", + "type":"text/html", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/" + }, + { + "rel":"describedby", + "type":"application/pdf", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf" + }, + { + "rel":"describedby", + "type":"application/vnd.sun.wadl+xml", + "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl" + } + ], + "media-types":[ + { + "base":"application/xml", + "type":"application/vnd.openstack.identity-v2.0+xml" + }, + { + "base":"application/json", + "type":"application/vnd.openstack.identity-v2.0+json" + } + ] + } + } + +GET /extensions +=============== + +Discover the API extensions enabled at the endpoint:: + + $ curl http://0.0.0.0:35357/extensions + +Returns:: + + { + "extensions":{ + "values":[] + } + } + +POST /tokens +============ + +Authenticate by exchanging credentials for an access token:: + + $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens + +Returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "serviceCatalog":[ + { + "endpoints":[ + { + "adminURL":"http://swift.admin-nets.local:8080/", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", + "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" + } + ], + "type":"object-store", + "name":"swift" + }, + { + "endpoints":[ + { + "adminURL":"http://cdn.admin-nets.local/v1.1/1", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:7777/v1.1/1", + "publicURL":"http://cdn.publicinternets.com/v1.1/1" + } + ], + "type":"object-store", + "name":"cdn" + } + ], + "user":{ + "id":"1", + "roles":[ + { + "tenantId":"1", + "id":"3", + "name":"Member" + } + ], + "name":"joeuser" + } + } + } + +.. note:: + + Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. + +GET /tokens/{token_id} +====================== + +.. note:: + + This call refers to a token known to be valid, ``887665443383838`` in this case. + +Validate a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +If the token is valid, returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "user":{ + "name":"joeuser", + "tenantName":"customer-x", + "id":"1", + "roles":[ + { + "serviceId":"1", + "id":"3", + "name":"Member" + } + ], + "tenantId":"1" + } + } + } + +HEAD /tokens/{token_id} +======================= + +This is a high-performance variant of the GET call documented above, which +by definition, returns no response body:: + + $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +... which returns ``200``, indicating the token is valid:: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: None + Date: Tue, 08 Nov 2011 23:07:44 GMT + +GET /tokens/{token_id}/endpoints +================================ + +List all endpoints for a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + +Returns:: + + { + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", + "rel": "next" + } + ], + "endpoints": [ + { + "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", + "name": "swift", + "adminURL": "http://swift.admin-nets.local:8080/", + "region": "RegionOne", + "tenantId": 1, + "type": "object-store", + "id": 1, + "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" + }, + { + "internalURL": "http://localhost:8774/v1.0", + "name": "nova_compat", + "adminURL": "http://127.0.0.1:8774/v1.0", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 2, + "publicURL": "http://nova.publicinternets.com/v1.0/" + }, + { + "internalURL": "http://localhost:8774/v1.1", + "name": "nova", + "adminURL": "http://127.0.0.1:8774/v1.1", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 3, + "publicURL": "http://nova.publicinternets.com/v1.1/ + }, + { + "internalURL": "http://127.0.0.1:9292/v1.1/", + "name": "glance", + "adminURL": "http://nova.admin-nets.local/v1.1/", + "region": "RegionOne", + "tenantId": 1, + "type": "image", + "id": 4, + "publicURL": "http://glance.publicinternets.com/v1.1/" + }, + { + "internalURL": "http://127.0.0.1:7777/v1.1/1", + "name": "cdn", + "adminURL": "http://cdn.admin-nets.local/v1.1/1", + "region": "RegionOne", + "tenantId": 1, + "versionId": "1.1", + "versionList": "http://127.0.0.1:7777/", + "versionInfo": "http://127.0.0.1:7777/v1.1", + "type": "object-store", + "id": 5, + "publicURL": "http://cdn.publicinternets.com/v1.1/1" + } + ] + } + +GET /tenants +============ + +List all of the tenants in the system (requires an Admin ``X-Auth-Token``):: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": false, + "description": "None", + "name": "project-y", + "id": "3" + }, + { + "enabled": true, + "description": "None", + "name": "ANOTHER:TENANT", + "id": "2" + }, + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } + +GET /tenants/{tenant_id} +======================== + +Retrieve information about a tenant, by tenant ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1 + +Returns:: + + { + "tenant":{ + "enabled":true, + "description":"None", + "name":"customer-x", + "id":"1" + } + } + +GET /tenants/{tenant_id}/users/{user_id}/roles +============================================== + +List the roles a user has been granted on a tenant:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"3", + "name":"Member" + } + ] + } + +GET /users/{user_id} +==================== + +Retrieve information about a user, by user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1 + +Returns:: + + { + "user":{ + "tenantId":"1", + "enabled":true, + "id":"1", + "name":"joeuser" + } + } + +GET /users/{user_id}/roles +========================== + +Retrieve the roles granted to a user, given a user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"2", + "name":"KeystoneServiceAdmin" + } + ] + } diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 8de45502..21d9b895 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -17,6 +17,10 @@ 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. Authentication diff --git a/docs/source/community.rst b/docs/source/community.rst index bbad2421..d3e32178 100644 --- a/docs/source/community.rst +++ b/docs/source/community.rst @@ -33,20 +33,6 @@ from blueprint designs to documentation to testing to deployment scripts. .. _Launchpad: https://launchpad.net/keystone .. _wiki: http://wiki.openstack.org/ - - -Contributing Code ------------------ - -To contribute code, sign up for a Launchpad account and sign a contributor license agreement, -available on the ``_. Once the CLA is signed you -can contribute code through the Gerrit version control system which is related to your Launchpad account. - -To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_. - -.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub - - #openstack on Freenode IRC Network ---------------------------------- @@ -68,10 +54,10 @@ to write drafts for specs or documentation, describe a blueprint, or collaborate Keystone on Launchpad --------------------- -Launchpad is a code hosting service that hosts the Keystone source code. From -Launchpad you can report bugs, ask questions, and register blueprints (feature requests). +Launchpad is a code hosting that OpenStack is using to track bugs, feature work, and releases of OpenStack. Like other OpenStack projects, Keystone source code is hosted on GitHub -* `Launchpad Keystone Page `_ +* `Keystone Project Page on Launchpad `_ +* `Keystone Source Repository on GitHub `_ OpenStack Blog -------------- @@ -82,9 +68,9 @@ events and posts from OpenStack contributors. `OpenStack Blog `_ -See also: `Planet OpenStack `_, aggregating blogs -about OpenStack from around the internet into a single feed. If you'd like to contribute to this blog -aggregation with your blog posts, there are instructions for `adding your blog `_. +See also: `Planet OpenStack `_, an aggregation of blogs +about OpenStack from around the internet, combined into a web site and RSS feed. If you'd like to +contribute with your blog posts, there are instructions for `adding your blog `_. Twitter ------- diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index a98d92f8..02fbd4b4 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -21,80 +21,214 @@ Configuring Keystone .. toctree:: :maxdepth: 1 - keystone.conf man/keystone-manage -Once Keystone is installed, there are a number of configuration options -available and potentially some initial data to create and set up. - -Sample data / Quick Setup -========================= - -Default sampledata is provided for easy setup and testing in bin/sampeldata. To -set up the sample data run the following command while Keystone is running:: - - $ ./bin/sampledata - -The sample data created comes from the file :doc:`sourcecode/keystone.test.sampledata` +Once Keystone is installed, it is configured via a primary configuration file +(:doc:`keystone.conf`), possibly a separate logging configuration file, and +initializing data into keystone using the command line client. Keystone Configuration File =========================== -Most configuration is done via configuration files. The default files are -in ``/etc/keystone.conf`` - -When starting up a Keystone server, you can specify the configuration file to -use (see :doc:`controllingservers`). -If you do **not** specify a configuration file, keystone will look in the following -directories for a configuration file, in order: +The keystone configuration file is an 'ini' file format with sections, +extended from Paste_, a common system used to configure python WSGI based +applications. In addition to the paste config entries, general configuration +values are stored under [DEFAULT] and [sql], and then drivers for the various +backend components are included under their individual sections. + +The driver sections include: +* ``[identity]`` - the python module that backends the identity system +* ``[catalog]`` - the python module that backends the service catalog +* ``[token]`` - the python module that backends the token providing mechanisms +* ``[policy]`` - the python module that drives the policy system for RBAC +* ``[ec2]`` - the python module providing the EC2 translations for OpenStack + +The keystone configuration file is expected to be named ``keystone.conf``. +When starting up Keystone, you can specify a different configuration file to +use with ``--config-file``. If you do **not** specify a configuration file, +keystone will look in the following directories for a configuration file, in +order: * ``~/.keystone`` * ``~/`` * ``/etc/keystone`` * ``/etc`` -The keystone configuration file should be named ``keystone.conf``. -If you installed keystone via your operating system's -package management system, it is likely that you will have sample -configuration files installed in ``/etc/keystone``. +Logging is configured externally to the rest of keystone, the file specifying +the logging configuration is in the [DEFAULT] section of the keystone conf +file under ``log_config``. If you wish to route all your logging through +syslog, there is a ``use_syslog`` option also in the [DEFAULT] section that +easy. -In addition to this documentation page, you can check the -``etc/keystone.conf`` sample configuration -files distributed with keystone for example configuration files for each server -application with detailed comments on what each options does. +A sample logging file is available with the project in the directory ``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the +`python logging module`, which includes extensive configuration options for +choosing the output levels and formats. + +In addition to this documentation page, you can check the ``etc/keystone.conf`` +sample configuration files distributed with keystone for example configuration +files for each server application. + +.. _Paste: http://pythonpaste.org/ +.. _`python logging module`: http://docs.python.org/library/logging.html Sample Configuration Files -------------------------- -Keystone ships with sample configuration files in keystone/etc. These files are: +* ``etc/keystone.conf`` +* ``etc/logging.conf.sample`` + +Initializing Keystone +===================== + +Keystone must be running in order to initialize data within it. This is because +the keystone-manage commands are all used the same REST API that other +OpenStack systems utilize. + +General keystone-manage options: +-------------------------------- + +* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result +from the API call. +* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' +* ``--auth-token`` : provides the authorization token + +``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command +``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: + + keystone-manage tenant create tenant_name=example_tenant + +Invoking keystone-manage by itself will give you some usage information. + +Available keystone-manage commands: + db_sync: Sync the database. + ec2: no docs + role: Role CRUD functions. + service: Service CRUD functions. + tenant: Tenant CRUD functions. + token: Token CRUD functions. + user: User CRUD functions. + +Tenants +------- + +Tenants are the high level grouping within Keystone that represent groups of +users. A tenant is the grouping that owns virtual machines within Nova, or +containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. + +* tenant create + + keyword arguments + * tenant_name + * id (optional) + +example:: + keystone-manage --id-only tenant create tenant_name=admin + +creates a tenant named "admin". + +* tenant delete + + keyword arguments + * tenant_id + +example:: + keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 + +* tenant update + + keyword arguments + * description + * name + * tenant_id + +example:: + keystone-manage tenant update \ + tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ + description="those other guys" \ + name=tog + +Users +----- + +* user create + + keyword arguments + * name + * password + * email + +example:: + keystone-manage user --ks-id-only create \ + name=admin \ + password=secrete \ + email=admin@example.com + +* user delete + + keyword arguments + +* user list + + keyword arguments + +* user update_email + + keyword arguments + +* user update_enabled + + keyword arguments + +* user update_password + + keyword arguments -1. keystone.conf +* user update_tenant - A standard configuration file for running keystone in stand-alone mode. - It has a set of default extensions loaded to support administering Keystone - over REST. It uses a local SQLite database. + keyword arguments -2. memcache.conf +Roles +----- - A configuration that uses memcached for storing tokens (but still SQLite for all - other entities). This requires memcached running. +* role create -3. ssl.conf + keyword arguments + * name - A configuration that runs Keystone with SSL (so all URLs are accessed over HTTPS). +exmaple:: + keystone-manage role --ks-id-only create name=Admin + +* role add_user_to_tenant -To run any of these configurations, use the `-c` option:: + keyword arguments + * role_id + * user_id + * tenant_id - ./keystone -c ../etc/ssl.conf +example:: + keystone-manage role add_user_to_tenant \ + role_id=19d1d3344873464d819c45f521ff9890 \ + user_id=08741d8ed88242ca88d1f61484a0fe3b \ + tenant_id=20601a7f1d94447daa4dff438cb1c209 + +* role remove_user_from_tenant +* role get_user_role_refs -Usefule Links -------------- +Services +-------- -For a sample configuration file with explanations of the settings, see :doc:`keystone.conf` +* service create -For configuring an LDAP backend, see http://mirantis.blogspot.com/2011/08/ldap-identity-store-for-openstack.html + keyword arguments + * name + * service_type + * description -For configuration settings of middleware components, see :doc:`middleware` \ No newline at end of file +example:: + keystone-manage service create \ + name=nova \ + service_type=compute \ + description="Nova Compute Service" diff --git a/docs/source/developing.rst b/docs/source/developing.rst index acd22730..b19fec24 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -18,33 +18,22 @@ Developing with Keystone ======================== -Get your development environment set up according to :doc:`setup`. +Contributing Code +================= -Running a development instance -============================== +To contribute code, sign up for a Launchpad account and sign a contributor license agreement, +available on the ``_. Once the CLA is signed you +can contribute code through the Gerrit version control system which is related to your Launchpad account. -Setting up a virtualenv ------------------------ +To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_. -We recommend establishing a virtualenv to run keystone within. To establish -this environment, use the command:: +.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub - $ python tools/install_venv.py +Setup +----- -This will create a local virtual environment in the directory ``.venv``. -Once created, you can activate this virtualenv for your current shell using:: - - $ source .venv/bin/activate - -The virtual environment can be disabled using the command:: - - $ deactivate - -You can also use ``tools\with_venv.sh`` to prefix commands so that they run -within the virtual environment. For more information on virtual environments, -see virtualenv_. - -.. _virtualenv: http://www.virtualenv.org/ +Get your development environment set up according to :doc:`setup`. The instructions from here will +assume that you have installed keystone into a virtualenv. If you chose not to, simply exclude "tools/with_venv.sh" from the example commands below. Running Keystone ---------------- @@ -52,84 +41,69 @@ Running Keystone To run the keystone Admin and API server instances, use:: $ tools/with_venv.sh bin/keystone - -Running a demo service that uses Keystone ------------------------------------------ - -To run client demo (with all auth middleware running locally on sample service):: - - $ tools/with_venv.sh examples/echo/bin/echod - -which spins up a simple "echo" service on port 8090. To use a simple echo client:: - - $ python examples/echo/echo_client.py + +this runs keystone with the configuration the etc/ directory of the project. See :doc:`configuration` for details on how Keystone is configured. Interacting with Keystone -========================= +------------------------- You can interact with Keystone through the command line using :doc:`man/keystone-manage` which allows you to establish tenants, users, etc. You can also interact with Keystone through it's REST API. There is a python -keystone client library python-keystoneclient_ which interacts exclusively through -the REST API. +keystone client library `python-keystoneclient`_ which interacts exclusively through +the REST API, and which keystone itself uses to provide it's command-line interface. + +.. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient + +Running Tests +============= + +To run the full suites of tests maintained within Keystone, run:: -.. _python-keystoneclient: https://github.com/4P/python-keystoneclient + $ ./run_tests.sh -The easiest way to establish some base information in Keystone to interact with is -to invoke:: +This shows realtime feedback during test execution, iterates over +multiple configuration variations, and uses external projects to do +light integration testing to verify the keystone API against other projects. - $ tools/with_venv.sh bin/sampledata +Test Structure +-------------- -You can see the details of what that creates in ``keystone/test/sampledata.py`` +UPDATE THIS... -Enabling debugging middleware ------------------------------ +Testing Schema Migrations +------------------------- -You can enable a huge amount of additional data (debugging information) about -the request and repsonse objects flowing through Keystone using the debugging -WSGI middleware. +The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time. -To enable this, just modify the pipelines in ``etc/keystone.conf``, from:: +.. WARNING:: - [pipeline:admin] - pipeline = - urlnormalizer - admin_api + This may leave your database in an inconsistent state; attempt this in non-production environments only! - [pipeline:keystone-legacy-auth] - pipeline = - urlnormalizer - legacy_auth - d5_compat - service_api +This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control:: -... to:: + python keystone/common/sql/migrate_repo/manage.py test \ + --url=sqlite:///test.db \ + --repository=keystone/common/sql/migrate_repo/ - [pipeline:admin] - pipeline = - debug - urlnormalizer - d5_compat - admin_api +This command references to a SQLite database (test.db) to be used. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration. - [pipeline:keystone-legacy-auth] - pipeline = - debug - urlnormalizer - legacy_auth - d5_compat - service_api +Writing Tests +------------- -Two simple and easy debugging tools are using the ``-d`` when you start keystone:: +UPDATE THIS... - $ ./keystone -d -and the `--trace-calls` flag:: +Further Testing +--------------- - $ ./keystone -trace-calls +devstack_ is the *best* way to quickly deploy keystone with the rest of the +OpenStack universe and should be critical step in your development workflow! -The ``-d`` flag outputs debug information to the console. The ``--trace-calls`` flag -outputs extensive, nested trace calls to the console and highlights any errors -in red. +You may also be interested in either the `OpenStack Continuous Integration Project`_ +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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 4270033a..427414d4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,9 +18,9 @@ Welcome to Keystone, the OpenStack Identity Service! ==================================================== -Keystone is a cloud identity service written in Python, which provides -authentication, authorization, and an OpenStack service catalog. It -implements `OpenStack's Identity API`_. +Keystone is an OpenStack project that provides Identity, Token, Catalog and +Policy services for use specifically by projects in the OpenStack family. +It implements `OpenStack's Identity API`_. This document describes Keystone for contributors of the project, and assumes that you are already familiar with Keystone from an `end-user perspective`_. @@ -42,9 +42,18 @@ Getting Started :maxdepth: 1 setup + configuration + configuringservices community - testing +Man Pages +--------- + +.. toctree:: + :maxdepth: 1 + + man/keystone + man/keystone-manage Developers Documentation ======================== @@ -53,7 +62,8 @@ Developers Documentation developing architecture - sourcecode/autoindex + api_curl_examples + modules Indices and tables ================== diff --git a/docs/source/man/keystone-manage.rst b/docs/source/man/keystone-manage.rst index 9e9304f0..da5fc941 100644 --- a/docs/source/man/keystone-manage.rst +++ b/docs/source/man/keystone-manage.rst @@ -22,159 +22,202 @@ DESCRIPTION =========== keystone-manage is the command line tool that interacts with the keystone -service to configure Keystone +service to initialize and update data within Keystone. Keystone *must* be +opertional for the keystone-manage commands to function correctly. USAGE ===== ``keystone-manage [options] type action [additional args]`` -user ----- -* **user add** [username] [password] +General keystone-manage options: +-------------------------------- - adds a user to Keystone's data store +* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result +from the API call. +* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' +* ``--auth-token`` : provides the authorization token -* **user list** +``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command +``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: - lists all users + keystone-manage tenant create tenant_name=example_tenant -* **user disable** [username] +Invoking keystone-manage by itself will give you some usage information. - disables the user *username* +Available keystone-manage commands: + db_sync: Sync the database. + ec2: no docs + role: Role CRUD functions. + service: Service CRUD functions. + tenant: Tenant CRUD functions. + token: Token CRUD functions. + user: User CRUD functions. -tenant ------- - -* **tenant add** [tenant_name] +Tenants +------- - adds a tenant to Keystone's data store +Tenants are the high level grouping within Keystone that represent groups of +users. A tenant is the grouping that owns virtual machines within Nova, or +containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. -* **tenant list** +* tenant create - lists all users + keyword arguments + * tenant_name + * id (optional) -* **tenant disable** [tenant_name] +example:: + keystone-manage --id-only tenant create tenant_name=admin -role ----- +creates a tenant named "admin". -Roles are used to associated users to tenants. Two roles are defined related -to the Keystone service in it's configuration file :doc:`../keystone.conf` +* tenant delete -* **role add** [role_name] + keyword arguments + * tenant_id + +example:: + keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 - adds a role +* tenant update -* **role list** ([tenant_name]) + keyword arguments + * description + * name + * tenant_id - lists all roles, or all roles for tenant, if tenant_name is provided +example:: + keystone-manage tenant update \ + tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ + description="those other guys" \ + name=tog -* **role grant** [role_name] [username] ([tenant]) +Users +----- - grants a role to a specific user. Granted globally if tenant_name is not - provided or granted for a specific tenant if tenant_name is provided. +* user create -service -------- + keyword arguments + * name + * password + * email + +example:: + keystone-manage user --ks-id-only create \ + name=admin \ + password=secrete \ + email=admin@example.com + +* user delete -* **service add** [name] [type] [description] [owner_id] + keyword arguments - adds a service +* user list -* **service list** + keyword arguments - lists all services with id, name, and type +* user update_email -endpointTemplate ----------------- + keyword arguments -* **endpointTemplate add** [region] [service_name] [public_url] [admin_url] [internal_url] [enabled] [is_global] +* user update_enabled - Add a service endpoint for keystone. + keyword arguments - example:: +* user update_password + + keyword arguments - keystone-manage endpointTemplates add RegionOne \ - keystone \ - http://keystone_host:5000/v2.0 \ - http://keystone_host:35357/v2.0 \ - http://keystone_host:5000/v2.0 \ - 1 1 +* user update_tenant -* **endpointTemplate list** ([tenant_name]) + keyword arguments - lists endpoint templates with service, region, and public_url. Restricted to - tenant endpoints if tenant_name is provided. - -token +Roles ----- -* **token add** [token] [username] [tenant] [expiration] +* role create + + keyword arguments + * name - adds a token for a given user and tenant with an expiration +exmaple:: + keystone-manage role --ks-id-only create name=Admin + +* role add_user_to_tenant -* **token list** + keyword arguments + * role_id + * user_id + * tenant_id - lists all tokens +example:: -* **token delete** [token] + keystone-manage role add_user_to_tenant \ + role_id=19d1d3344873464d819c45f521ff9890 \ + user_id=08741d8ed88242ca88d1f61484a0fe3b \ + tenant_id=20601a7f1d94447daa4dff438cb1c209 + +* role remove_user_from_tenant - deletes the identified token +* role get_user_role_refs -endpoint +Services -------- -* **endpoint add** [tenant_name] [endpoint_template] +* service create - adds a tenant-specific endpoint + keyword arguments + * name + * service_type + * description -credentials ------------ +example:: + keystone-manage service create \ + name=nova \ + service_type=compute \ + description="Nova Compute Service" -* **credentials add** [username] [type] [key] [password] ([tenant_name]) OPTIONS ======= - --version show program's version number and exit - -h, --help show this help message and exit - -v, --verbose Print more verbose output - -d, --debug Print debugging output to console - -c PATH, --config-file=PATH Path to the config file to use. When not - specified (the default), we generally look at - the first argument specified to be a config - file, and if that is also missing, we search - standard directories for a config file. - -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT - specifies port to listen on (default is 5000) - --host=BIND_HOST, --bind-host=BIND_HOST - specifies host address to listen on (default - is all or 0.0.0.0) - -t, --trace-calls Turns on call tracing for troubleshooting - -a PORT, --admin-port=PORT Specifies port for Admin API to listen on - (default is 35357) - -Logging Options: -================ - -The following configuration options are specific to logging -functionality for this program. - - --log-config=PATH If this option is specified, the logging - configuration file specified is used and - overrides any other logging options specified. - Please see the Python logging module - documentation for details on logging - configuration files. - --log-date-format=FORMAT Format string for %(asctime)s in log records. - Default: %Y-%m-%d %H:%M:%S - --log-file=PATH (Optional) Name of log file to output to. If - not set, logging will go to stdout. - --log-dir=LOG_DIR (Optional) The directory to keep log files in - (will be prepended to --logfile) - +Options: + -h, --help show this help message and exit + --config-file=PATH Path to a config file to use. Multiple config files + can be specified, with values in later files taking + precedence. The default files used are: [] + -d, --debug Print debugging output + --nodebug Print debugging output + -v, --verbose Print more verbose output + --noverbose Print more verbose output + --log-config=PATH If this option is specified, the logging configuration + file specified is used and overrides any other logging + options specified. Please see the Python logging + module documentation for details on logging + configuration files. + --log-format=FORMAT A logging.Formatter log message format string which + may use any of the available logging.LogRecord + attributes. Default: none + --log-date-format=DATE_FORMAT + Format string for %(asctime)s in log records. Default: + none + --log-file=PATH (Optional) Name of log file to output to. If not set, + logging will go to stdout. + --log-dir=LOG_DIR (Optional) The directory to keep log files in (will be + prepended to --logfile) + --syslog-log-facility=SYSLOG_LOG_FACILITY + (Optional) The syslog facility to use when logging to + syslog (defaults to LOG_USER) + --use-syslog Use syslog for logging. + --nouse-syslog Use syslog for logging. + --endpoint=ENDPOINT + --auth-token=AUTH_TOKEN + authorization token + --id-only + --noid-only + FILES ===== diff --git a/docs/source/man/keystone.rst b/docs/source/man/keystone.rst index 48e062e4..74d0bb69 100644 --- a/docs/source/man/keystone.rst +++ b/docs/source/man/keystone.rst @@ -21,9 +21,7 @@ SYNOPSIS DESCRIPTION =========== -keystone starts both the service and administrative API servers for Keystone. -Use :doc:`keystone-control` to stop/start/restart and manage those services -once started. +keystone starts both the service and administrative APIs for Keystone. USAGE ===== @@ -32,47 +30,40 @@ USAGE Common Options: ^^^^^^^^^^^^^^^ - --version show program's version number and exit -h, --help show this help message and exit The following configuration options are common to all keystone programs.:: - -v, --verbose Print more verbose output - -d, --debug Print debugging output to console - -c PATH, --config-file=PATH Path to the config file to use. When not - specified (the default), we generally look at - the first argument specified to be a config - file, and if that is also missing, we search - standard directories for a config file. - -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT - specifies port to listen on (default is 5000) - --host=BIND_HOST, --bind-host=BIND_HOST - specifies host address to listen on (default - is all or 0.0.0.0) - -t, --trace-calls Turns on call tracing for troubleshooting - -a PORT, --admin-port=PORT Specifies port for Admin API to listen on - (default is 35357) - -Logging Options: -^^^^^^^^^^^^^^^^ - -The following configuration options are specific to logging -functionality for this program.:: - - --log-config=PATH If this option is specified, the logging - configuration file specified is used and - overrides any other logging options specified. - Please see the Python logging module - documentation for details on logging - configuration files. - --log-date-format=FORMAT Format string for %(asctime)s in log records. - Default: %Y-%m-%d %H:%M:%S - --log-file=PATH (Optional) Name of log file to output to. If - not set, logging will go to stdout. - --log-dir=LOG_DIR (Optional) The directory to keep log files in - (will be prepended to --logfile) - + -h, --help show this help message and exit + --config-file=PATH Path to a config file to use. Multiple config files + can be specified, with values in later files taking + precedence. The default files used are: [] + -d, --debug Print debugging output + --nodebug Print debugging output + -v, --verbose Print more verbose output + --noverbose Print more verbose output + --log-config=PATH If this option is specified, the logging configuration + file specified is used and overrides any other logging + options specified. Please see the Python logging + module documentation for details on logging + configuration files. + --log-format=FORMAT A logging.Formatter log message format string which + may use any of the available logging.LogRecord + attributes. Default: none + --log-date-format=DATE_FORMAT + Format string for %(asctime)s in log records. Default: + none + --log-file=PATH (Optional) Name of log file to output to. If not set, + logging will go to stdout. + --log-dir=LOG_DIR (Optional) The directory to keep log files in (will be + prepended to --logfile) + --syslog-log-facility=SYSLOG_LOG_FACILITY + (Optional) The syslog facility to use when logging to + syslog (defaults to LOG_USER) + --use-syslog Use syslog for logging. + --nouse-syslog Use syslog for logging. + FILES ===== diff --git a/docs/source/setup.rst b/docs/source/setup.rst index e608f09e..25a43655 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -18,12 +18,12 @@ Setting up a Keystone development environment ============================================= -This document describes setting up keystone directly from GitHub_ +This document describes getting the source from keystone's `GitHub repository`_ for development purposes. To install keystone from packaging, refer instead to Keystone's `User Documentation`_. -.. _GitHub: http://github.com/openstack/keystone +.. _`GitHub Repository`: http://github.com/openstack/keystone .. _`User Documentation`: http://docs.openstack.org/ Prerequisites @@ -51,7 +51,7 @@ different version of the above, please document your configuration here! Getting the latest code ======================= -You can clone our latest code from our `Github repository`:: +Make a clone of the code from our `Github repository`:: $ git clone https://github.com/openstack/keystone.git @@ -59,13 +59,17 @@ When that is complete, you can:: $ cd keystone -.. _`Github repository`: https://github.com/openstack/keystone - Installing dependencies ======================= -Keystone maintains a list of PyPi_ dependencies, designed for use by -pip_. +Keystone maintains two lists of dependencies: + + tools/pip-requires + tools/pip-requires-test + +The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of keystone itself. + +These depdendencies can be installed from PyPi_ using the python tool pip_. .. _PyPi: http://pypi.python.org/ .. _pip: http://pypi.python.org/pypi/pip @@ -89,29 +93,51 @@ Mac OS X Lion (requires MacPorts_):: .. _MacPorts: http://www.macports.org/ -PyPi Packages -------------- +PyPi Packages and VirtualEnv +---------------------------- -Assuming you have any necessary binary packages & header files available -on your system, you can then install PyPi dependencies. +We recommend establishing a virtualenv to run keystone within. Virtualenv limits the python environment +to just what you're installing as depdendencies, useful to keep a clean environment for working on +Keystone. The tools directory in keystone has a script already created to make this very simple:: -You may also need to prefix `pip install` with `sudo`, depending on your -environment:: + $ python tools/install_venv.py - # Describe dependencies (including non-PyPi dependencies) - $ cat tools/pip-requires +This will create a local virtual environment in the directory ``.venv``. +Once created, you can activate this virtualenv for your current shell using:: - # Install all PyPi dependencies (for production, testing, and development) - $ pip install -r tools/pip-requires + $ source .venv/bin/activate + +The virtual environment can be disabled using the command:: + + $ deactivate -Updating your PYTHONPATH -======================== +You can also use ``tools\with_venv.sh`` to prefix commands so that they run +within the virtual environment. For more information on virtual environments, +see virtualenv_. -There are a number of methods for getting Keystone into your PYTHON PATH, -the easiest of which is:: +.. _virtualenv: http://www.virtualenv.org/ +If you want to run keystone outside of a virtualenv, you can install the dependencies directly +into your system from the requires files:: + + # Install the dependencies for running keystone + $ pip install -r tools/pip-requires + + # Install the dependencies for developing, testing, and running keystone + $ pip install -r tools/pip-requires-test + # Fake-install the project by symlinking Keystone into your Python site-packages $ python setup.py develop + + +Verifying Keystone is set up +============================ + +Once set up, either directly or within a virtualenv, you should be able to invoke python and import +the libraries. If you're using a virtualenv, don't forget to activate it:: + + $ source .venv/bin/activate + $ python You should then be able to `import keystone` from your Python shell without issue:: @@ -124,8 +150,7 @@ If you want to check the version of Keystone you are running: >>> print keystone.version.version() 2012.1-dev - -If you can import keystone successfully, you should be ready to move on to :doc:`testing`. +If you can import keystone successfully, you should be ready to move on to :doc:`testing` and :doc:`developing` Troubleshooting =============== diff --git a/docs/source/testing.rst b/docs/source/testing.rst deleted file mode 100644 index 82a33604..00000000 --- a/docs/source/testing.rst +++ /dev/null @@ -1,77 +0,0 @@ -================ -Testing Keystone -================ - -Keystone uses a number of testing methodologies to ensure correctness. - -Running Built-In Tests -====================== - -To run the full suites of tests maintained within Keystone, run:: - - $ ./run_tests.sh --with-progress - -This shows realtime feedback during test execution, and iterates over -multiple configuration variations. - -This differs from how tests are executed from the continuous integration -environment. Specifically, Jenkins doesn't care about realtime progress, -and aborts after the first test failure (a fail-fast behavior):: - - $ ./run_tests.sh - -Testing Schema Migrations -========================= - -The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time. - -.. WARNING:: - - This may leave your database in an inconsistent state; attempt this in non-production environments only! - -This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control:: - - $ python keystone/backends/sqlalchemy/migrate_repo/manage.py test --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/ - -This command refers to a SQLite database used for testing purposes. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration. - -Writing Tests -============= - -Tests are maintained in the ``keystone.test`` module. Unit tests are -isolated from functional tests. - -Functional Tests ----------------- - -The ``keystone.test.functional.common`` module provides a ``unittest``-based -``httplib`` client which you can extend and use for your own tests. -Generally, functional tests should serve to illustrate intended use cases -and API behaviors. To help make your tests easier to read, the test client: - -- Authenticates with a known user name and password combination -- Asserts 2xx HTTP status codes (unless told otherwise) -- Abstracts keystone REST verbs & resources into single function calls - -Testing Multiple Configurations -------------------------------- - -Several variations of the default configuration are iterated over to -ensure test coverage of mutually exclusive featuresets, such as the -various backend options. - -These configuration templates are maintained in ``keystone/test/etc`` and -are iterated over by ``run_tests.py``. - -Further Testing -=============== - -devstack_ is the *best* way to quickly deploy keystone with the rest of the -OpenStack universe and should be critical step in your development workflow! - -You may also be interested in either the `OpenStack Continuous Integration Project`_ -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/openstack-integration-tests -- cgit From fec7598a07b4beca78fe31a549e5d3beb6c0dc5d Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 13:24:38 -0800 Subject: shifting older docs into old/ directory --- docs/source/adminAPI_curl_examples.rst | 387 -------------------- docs/source/configuration.rst | 2 +- docs/source/configuringservices.rst | 333 ----------------- docs/source/controllingservers.rst | 288 --------------- docs/source/endpoints.rst | 430 ---------------------- docs/source/extensions.rst | 183 ---------- docs/source/index.rst | 6 +- docs/source/middleware.rst | 169 --------- docs/source/middleware_architecture.rst | 529 ---------------------------- docs/source/migration.rst | 126 ------- docs/source/nova-api-paste.rst | 142 -------- docs/source/old/configuringservices.rst | 333 +++++++++++++++++ docs/source/old/controllingservers.rst | 288 +++++++++++++++ docs/source/old/endpoints.rst | 430 ++++++++++++++++++++++ docs/source/old/extensions.rst | 183 ++++++++++ docs/source/old/middleware.rst | 169 +++++++++ docs/source/old/middleware_architecture.rst | 529 ++++++++++++++++++++++++++++ docs/source/old/migration.rst | 126 +++++++ docs/source/old/nova-api-paste.rst | 142 ++++++++ docs/source/old/releases.rst | 36 ++ docs/source/old/services.rst | 92 +++++ docs/source/old/ssl.rst | 118 +++++++ docs/source/releases.rst | 36 -- docs/source/serviceAPI_curl_examples.rst | 69 ---- docs/source/services.rst | 92 ----- docs/source/ssl.rst | 118 ------- docs/source/usingkeystone.rst | 28 -- 27 files changed, 2450 insertions(+), 2934 deletions(-) delete mode 100644 docs/source/adminAPI_curl_examples.rst delete mode 100644 docs/source/configuringservices.rst delete mode 100644 docs/source/controllingservers.rst delete mode 100644 docs/source/endpoints.rst delete mode 100644 docs/source/extensions.rst delete mode 100644 docs/source/middleware.rst delete mode 100644 docs/source/middleware_architecture.rst delete mode 100644 docs/source/migration.rst delete mode 100644 docs/source/nova-api-paste.rst create mode 100644 docs/source/old/configuringservices.rst create mode 100644 docs/source/old/controllingservers.rst create mode 100644 docs/source/old/endpoints.rst create mode 100644 docs/source/old/extensions.rst create mode 100644 docs/source/old/middleware.rst create mode 100644 docs/source/old/middleware_architecture.rst create mode 100644 docs/source/old/migration.rst create mode 100644 docs/source/old/nova-api-paste.rst create mode 100644 docs/source/old/releases.rst create mode 100644 docs/source/old/services.rst create mode 100644 docs/source/old/ssl.rst delete mode 100644 docs/source/releases.rst delete mode 100644 docs/source/serviceAPI_curl_examples.rst delete mode 100644 docs/source/services.rst delete mode 100644 docs/source/ssl.rst delete mode 100644 docs/source/usingkeystone.rst (limited to 'docs/source') diff --git a/docs/source/adminAPI_curl_examples.rst b/docs/source/adminAPI_curl_examples.rst deleted file mode 100644 index 81f96c36..00000000 --- a/docs/source/adminAPI_curl_examples.rst +++ /dev/null @@ -1,387 +0,0 @@ -.. - Copyright 2011 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. - -============================= -Admin API Examples Using Curl -============================= - -These examples assume a default port value of 35357, and depend on the -``sampledata`` bundled with keystone. - -GET / -===== - -Disover API version information, links to documentation (PDF, HTML, WADL), -and supported media types:: - - $ curl http://0.0.0.0:35357 - -or:: - - $ curl http://0.0.0.0:35357/v2.0/ - -Returns:: - - { - "version":{ - "id":"v2.0", - "status":"beta", - "updated":"2011-11-19T00:00:00Z", - "links":[ - { - "rel":"self", - "href":"http://127.0.0.1:35357/v2.0/" - }, - { - "rel":"describedby", - "type":"text/html", - "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/" - }, - { - "rel":"describedby", - "type":"application/pdf", - "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf" - }, - { - "rel":"describedby", - "type":"application/vnd.sun.wadl+xml", - "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl" - } - ], - "media-types":[ - { - "base":"application/xml", - "type":"application/vnd.openstack.identity-v2.0+xml" - }, - { - "base":"application/json", - "type":"application/vnd.openstack.identity-v2.0+json" - } - ] - } - } - -GET /extensions -=============== - -Discover the API extensions enabled at the endpoint:: - - $ curl http://0.0.0.0:35357/extensions - -Returns:: - - { - "extensions":{ - "values":[] - } - } - -POST /tokens -============ - -Authenticate by exchanging credentials for an access token:: - - $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens - -Returns:: - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "serviceCatalog":[ - { - "endpoints":[ - { - "adminURL":"http://swift.admin-nets.local:8080/", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", - "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" - } - ], - "type":"object-store", - "name":"swift" - }, - { - "endpoints":[ - { - "adminURL":"http://cdn.admin-nets.local/v1.1/1", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:7777/v1.1/1", - "publicURL":"http://cdn.publicinternets.com/v1.1/1" - } - ], - "type":"object-store", - "name":"cdn" - } - ], - "user":{ - "id":"1", - "roles":[ - { - "tenantId":"1", - "id":"3", - "name":"Member" - } - ], - "name":"joeuser" - } - } - } - -.. note:: - - Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. - -GET /tokens/{token_id} -====================== - -.. note:: - - This call refers to a token known to be valid, ``887665443383838`` in this case. - -Validate a token:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 - -If the token is valid, returns:: - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "user":{ - "name":"joeuser", - "tenantName":"customer-x", - "id":"1", - "roles":[ - { - "serviceId":"1", - "id":"3", - "name":"Member" - } - ], - "tenantId":"1" - } - } - } - -HEAD /tokens/{token_id} -======================= - -This is a high-performance variant of the GET call documented above, which -by definition, returns no response body:: - - $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 - -... which returns ``200``, indicating the token is valid:: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: None - Date: Tue, 08 Nov 2011 23:07:44 GMT - -GET /tokens/{token_id}/endpoints -================================ - -List all endpoints for a token:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints - -Returns:: - - { - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", - "rel": "next" - } - ], - "endpoints": [ - { - "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", - "name": "swift", - "adminURL": "http://swift.admin-nets.local:8080/", - "region": "RegionOne", - "tenantId": 1, - "type": "object-store", - "id": 1, - "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" - }, - { - "internalURL": "http://localhost:8774/v1.0", - "name": "nova_compat", - "adminURL": "http://127.0.0.1:8774/v1.0", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 2, - "publicURL": "http://nova.publicinternets.com/v1.0/" - }, - { - "internalURL": "http://localhost:8774/v1.1", - "name": "nova", - "adminURL": "http://127.0.0.1:8774/v1.1", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 3, - "publicURL": "http://nova.publicinternets.com/v1.1/ - }, - { - "internalURL": "http://127.0.0.1:9292/v1.1/", - "name": "glance", - "adminURL": "http://nova.admin-nets.local/v1.1/", - "region": "RegionOne", - "tenantId": 1, - "type": "image", - "id": 4, - "publicURL": "http://glance.publicinternets.com/v1.1/" - }, - { - "internalURL": "http://127.0.0.1:7777/v1.1/1", - "name": "cdn", - "adminURL": "http://cdn.admin-nets.local/v1.1/1", - "region": "RegionOne", - "tenantId": 1, - "versionId": "1.1", - "versionList": "http://127.0.0.1:7777/", - "versionInfo": "http://127.0.0.1:7777/v1.1", - "type": "object-store", - "id": 5, - "publicURL": "http://cdn.publicinternets.com/v1.1/1" - } - ] - } - -GET /tenants -============ - -List all of the tenants in the system (requires an Admin ``X-Auth-Token``):: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants - -Returns:: - - { - "tenants_links": [], - "tenants": [ - { - "enabled": false, - "description": "None", - "name": "project-y", - "id": "3" - }, - { - "enabled": true, - "description": "None", - "name": "ANOTHER:TENANT", - "id": "2" - }, - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } - -GET /tenants/{tenant_id} -======================== - -Retrieve information about a tenant, by tenant ID:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1 - -Returns:: - - { - "tenant":{ - "enabled":true, - "description":"None", - "name":"customer-x", - "id":"1" - } - } - -GET /tenants/{tenant_id}/users/{user_id}/roles -============================================== - -List the roles a user has been granted on a tenant:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles - -Returns:: - - { - "roles_links":[], - "roles":[ - { - "id":"3", - "name":"Member" - } - ] - } - -GET /users/{user_id} -==================== - -Retrieve information about a user, by user ID:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1 - -Returns:: - - { - "user":{ - "tenantId":"1", - "enabled":true, - "id":"1", - "name":"joeuser" - } - } - -GET /users/{user_id}/roles -========================== - -Retrieve the roles granted to a user, given a user ID:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles - -Returns:: - - { - "roles_links":[], - "roles":[ - { - "id":"2", - "name":"KeystoneServiceAdmin" - } - ] - } diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 02fbd4b4..e16d1892 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -24,7 +24,7 @@ Configuring Keystone man/keystone-manage Once Keystone is installed, it is configured via a primary configuration file -(:doc:`keystone.conf`), possibly a separate logging configuration file, and +(``etc/keystone.conf``), possibly a separate logging configuration file, and initializing data into keystone using the command line client. diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst deleted file mode 100644 index 083c3ec5..00000000 --- a/docs/source/configuringservices.rst +++ /dev/null @@ -1,333 +0,0 @@ -.. - Copyright 2011 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. - -========================================== -Configuring Services to work with Keystone -========================================== - -.. toctree:: - :maxdepth: 1 - -Once Keystone is installed and running, services need to be configured to work -with it. These are the steps to configure a service to work with Keystone: - -1. Create or get credentials for the service to use - - A set of credentials are needed for each service (they may be - shared if you chose to). Depending on the service, these credentials are - either a username and password or a long-lived token.. - -2. Register the service, endpoints, roles and other entities - - In order for a service to have it's endpoints and roles show in the service - catalog returned by Keystone, a service record needs to be added for the - service. Endpoints and roles associated with that service can then be created. - - This can be done through the REST interface (using the OS-KSCATALOG extension) - or using keystone-manage. - -3. Install and configure middleware for the service to handle authentication - - Clients making calls to the service will pass in an authentication token. The - Keystone middleware will look for and validate that token, taking the - appropriate action. It will also retrive additional information from the token - such as user name, id, tenant name, id, roles, etc... - - The middleware will pass those data down to the service as headers. The - detailed description of this architecture is available here :doc:`middleware_architecture` - -Setting up credentials -====================== - -First admin user - bootstrapping --------------------------------- - -For a default installation of Keystone, before you can use the REST API, you -need to create your first initial user and grant that user the right to -administer Keystone. - -For the keystone service itself, two -Roles are pre-defined in the keystone configuration file -(:doc:`keystone.conf`). - - #Role that allows admin operations (access to all operations) - keystone-admin-role = Admin - - #Role that allows acting as service (validate tokens, register service, - etc...) - keystone-service-admin-role = KeystoneServiceAdmin - -In order to create your first user, once Keystone is running use -the `keystone-manage` command: - - $ keystone-manage user add admin secrete - $ keystone-manage role add Admin - $ keystone-manage role add KeystoneServiceAdmin - $ keystone-manage role grant Admin admin - $ keystone-manage role grant KeystoneServiceAdmin admin - -This creates the `admin` user (with a password of `secrete`), creates -two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to -the `admin` user. From here, you should now have the choice of using the -administrative API (as well as the :doc:`man/keystone-manage` commands) to -further configure keystone. There are a number of examples of how to use -that API at :doc:`adminAPI_curl_examples`. - - -Setting up services -=================== - -Defining Services and Service Endpoints ---------------------------------------- - -Keystone also acts as a service catalog to let other OpenStack systems know -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:: - - $ keystone-manage service add nova compute "Nova Compute Service" - $ keystone-manage service add glance image "Glance Image Service" - $ keystone-manage service add swift storage "Swift Object Storage Service" - $ keystone-manage service add keystone identity "Keystone Identity Service" - -Once the services are defined, we create endpoints for them. Each service -has three relevant URL's associated with it that are used in the command: - -* the public API URL -* an administrative API URL -* an internal URL - -The "internal URL" is an endpoint the generally offers the same API as the -public URL, but over a high-bandwidth, low-latency, unmetered (free) network. -You would use that to transfer images from nova to glance for example, and -not the Public URL which would go over the internet and be potentially chargeable. - -The "admin URL" is for administering the services and is not exposed or accessible -to customers without the apporpriate privileges. - -An example of setting up the endpoint for Nova:: - - $ keystone-manage endpointTemplates add RegionOne nova \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - 1 1 - -Glance:: - - $ keystone-manage endpointTemplates add RegionOne glance \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - 1 1 - -Swift:: - - $ keystone-manage endpointTemplates add RegionOne swift \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - http://swift.mydomain:8080/v1.0/ \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - 1 1 - -And setting up an endpoint for Keystone:: - - $ keystone-manage endpointTemplates add RegionOne keystone \ - http://keystone.mydomain:5000/v2.0 \ - http://keystone.mydomain:35357/v2.0 \ - http://keystone.mydomain:5000/v2.0 \ - 1 1 - - -Defining an Administrative Service Token ----------------------------------------- - -An Administrative Service Token is a bit of arbitrary text which is configured -in Keystone and used (typically configured into) Nova, Swift, Glance, and any -other OpenStack projects, to be able to use Keystone services. - -This token is an arbitrary text string, but must be identical between Keystone -and the services using Keystone. This token is bound to a user and tenant as -well, so those also need to be created prior to setting it up. - -The *admin* user was set up above, but we haven't created a tenant for that -user yet:: - - $ keystone-manage tenant add admin - -and while we're here, let's grant the admin user the 'Admin' role to the -'admin' tenant:: - - $ keystone-manage role add Admin - $ keystone-manage role grant Admin admin admin - -Now we can create a service token:: - - $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 - -This creates a service token of '999888777666' associated to the admin user, -admin tenant, and expires on February 5th, 2015. This token will be used when -configuring Nova, Glance, or other OpenStack services. - -Securing Communications with SSL --------------------------------- - -To encrypt traffic between services and Keystone, see :doc:`ssl` - - -Setting up OpenStack users -========================== - -Creating Tenants, Users, and Roles ----------------------------------- - -Let's set up a 'demo' tenant:: - - $ keystone-manage tenant add demo - -And add a 'demo' user with the password 'guest':: - - $ keystone-manage user add demo guest - -Now let's add a role of "Member" and grant 'demo' user that role -as it pertains to the tenant 'demo':: - - $ keystone-manage role add Member - $ keystone-manage role grant Member demo demo - -Let's also add the admin user as an Admin role to the demo tenant:: - - $ keystone-manage role grant Admin admin demo - -Creating EC2 credentials ------------------------- - -To add EC2 credentials for the `admin` and `demo` accounts:: - - $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' - $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' - -If you have a large number of credentials to create, you can put them all -into a single large file and import them using :doc:`man/keystone-import`. The -format of the document looks like:: - - credentials add admin EC2 'username' 'password' - credentials add admin EC2 'username' 'password' - -Then use:: - - $ keystone-import `filename` - - -Setting Up Middleware -===================== - -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. See :doc:`middleware` -for details on middleware and configuration parameters. - - -Configuring Nova to use Keystone --------------------------------- - -To configure Nova to use Keystone for authentication, the Nova API service -can be run against the api-paste file provided by Keystone. This is most -easily accomplished by setting the `--api_paste_config` flag in nova.conf to -point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file -included references to the WSGI authentication middleware provided with the -keystone installation. - -When configuring Nova, it is important to create a admin service token for -the service (from the Configuration step above) and include that as the key -'admin_token' in the nova-api-paste.ini. See the documented -:doc:`nova-api-paste` file for references. - -Configuring Swift to use Keystone ---------------------------------- - -Similar to Nova, swift can be configured to use Keystone for authentication -rather than it's built in 'tempauth'. - -1. Add a service endpoint for Swift to Keystone - -2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) - -3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. - Here's an example `/etc/swift/proxy-server.conf`:: - - [DEFAULT] - bind_port = 8888 - user = - - [pipeline:main] - pipeline = catch_errors cache keystone proxy-server - - [app:proxy-server] - use = egg:swift#proxy - account_autocreate = true - - [filter:keystone] - use = egg:keystone#tokenauth - auth_protocol = http - auth_host = 127.0.0.1 - auth_port = 35357 - admin_token = 999888777666 - delay_auth_decision = 0 - service_protocol = http - service_host = 127.0.0.1 - service_port = 8100 - service_pass = dTpw - cache = swift.cache - - [filter:cache] - use = egg:swift#memcache - set log_name = cache - - [filter:catch_errors] - use = egg:swift#catch_errors - - Note that the optional "cache" property in the keystone filter allows any - service (not just Swift) to register its memcache client in the WSGI - environment. If such a cache exists, Keystone middleware will utilize it - to store validated token information, which could result in better overall - performance. - -4. Restart swift - -5. Verify that keystone is providing authentication to Swift - -Use `swift` to check everything works (note: you currently have to create a -container or upload something as your first action to have the account -created; there's a Swift bug to be fixed soon):: - - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v - StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 - Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 - Account: AUTH_1234 - Containers: 1 - Objects: 0 - Bytes: 0 - Accept-Ranges: bytes - X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b - -.. WARNING:: - Keystone currently allows any valid token to do anything with any account. - diff --git a/docs/source/controllingservers.rst b/docs/source/controllingservers.rst deleted file mode 100644 index ba8bfc06..00000000 --- a/docs/source/controllingservers.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. - Copyright 2011 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. - -============================ -Controlling Keystone Servers -============================ - -This section describes the ways to start, stop, and reload the Keystone -services. - -Keystone Services ------------------ - -Keystone can serve a number of REST APIs and extensions on different TCP/IP -ports. - -The Service API -~~~~~~~~~~~~~~~~ - -The core Keystone -API is primarily a read-only API (the only write operation being POST /tokens -which authenticates a client, and returns a generated token). -This API is sufficient to use OpenStack if all users, roles, endpoints already -exist. This is often the case if Keystone is using an enterprise backend -and the backend is managed through other entperrise tools and business -processes. This core API is called the Service API and can be started -separately from the more complete Admin API. By default, Keystone runs -this API on port 5000. This is not an IANA assigned port and should not -be relied upon (instead, use the Admin API on port 35357 to look for -this endpoint - more on this later) - -The Service API is started using this command in the /bin directory:: - - $ ./keystone-auth - -The Admin API -~~~~~~~~~~~~~ - -Inn order for Keystone to be a fully functional service out of the box, -API extensions that provide full CRUD operations is included with Keystone. -This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 -extensions. These extensions provide a full set of create, read, update, delete -(CRUD) operations that can be used to manage Keystone objects through REST -calls. By default Keystone runs this full REST API on TCP/IP port 35357 -(assigned by IANA to Keystone). - -The Admin API is started using this command in the /bin directory:: - - $ ./keystone-admin - - -Both APIs can be loaded simultaneously (on different ports) using this command:: - - $ ./keystone - -Starting a server ------------------ - -There are two ways to start a Keystone service (either the Service API server -or the Admin API server): - -- Manually calling the server program -- Using the ``keystone-control`` server daemon wrapper program - -We recommend using the second way in production and the first for development -and debugging. - -Manually starting the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The first is by directly calling the server program, passing in command-line -options and a single argument for a ``paste.deploy`` configuration file to -use when configuring the server application. - -.. note:: - - Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` - configuration files that you can copy to a standard configuration directory and - adapt for your own uses. - -If you do `not` specify a configuration file on the command line, Keystone will -do its best to locate a configuration file in one of the -following directories, stopping at the first config file it finds: - -- ``$CWD`` -- ``~/.keystone`` -- ``~/`` -- ``/etc/keystone`` -- ``/etc`` - -The filename that is searched for is ``keystone.conf`` by default. - -If no configuration file is found, you will see an error, like:: - - $ keystone - ERROR: Unable to locate any configuration file. Cannot load application keystone - -Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: - - $ ./keystone -d - keystone-legacy-auth: INFO ************************************************** - keystone-legacy-auth: INFO Configuration options gathered from config file: - keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - keystone-legacy-auth: INFO ================================================ - keystone-legacy-auth: INFO admin_host 0.0.0.0 - keystone-legacy-auth: INFO admin_port 35357 - keystone-legacy-auth: INFO admin_ssl False - keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy - keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem - keystone-legacy-auth: INFO cert_required True - keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem - keystone-legacy-auth: INFO debug True - keystone-legacy-auth: INFO default_store sqlite - keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm - keystone-legacy-auth: INFO hash-password True - keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - keystone-legacy-auth: INFO keystone-admin-role Admin - keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin - keystone-legacy-auth: INFO log_dir . - keystone-legacy-auth: INFO log_file keystone.log - keystone-legacy-auth: INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - keystone-legacy-auth: INFO service_host 0.0.0.0 - keystone-legacy-auth: INFO service_port 5000 - keystone-legacy-auth: INFO service_ssl False - keystone-legacy-auth: INFO verbose False - keystone-legacy-auth: INFO ************************************************** - passlib.registry: INFO registered crypt handler 'sha512_crypt': - Starting the RAX-KEY extension - Starting the Legacy Authentication component - admin : INFO ************************************************** - admin : INFO Configuration options gathered from config file: - admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - admin : INFO ================================================ - admin : INFO admin_host 0.0.0.0 - admin : INFO admin_port 35357 - admin : INFO admin_ssl False - admin : INFO backends keystone.backends.sqlalchemy - admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem - admin : INFO cert_required True - admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem - admin : INFO debug True - admin : INFO default_store sqlite - admin : INFO extensions osksadm,oskscatalog,hpidm - admin : INFO hash-password True - admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - admin : INFO keystone-admin-role Admin - admin : INFO keystone-service-admin-role KeystoneServiceAdmin - admin : INFO log_dir . - admin : INFO log_file keystone.log - admin : INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - admin : INFO service_host 0.0.0.0 - admin : INFO service_port 5000 - admin : INFO service_ssl False - admin : INFO verbose False - admin : INFO ************************************************** - Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - Service API (ssl=False) listening on 0.0.0.0:5000 - Admin API (ssl=False) listening on 0.0.0.0:35357 - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ - - $ sudo keystone-registry keystone-registry.conf & - jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) - - $ ps aux | grep keystone - myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone - myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d - -Simply supply the configuration file as the first argument -and then any common options -you want to use (``-d`` was used above to show some of the debugging -output that the server shows when starting up. Call the server program -with ``--help`` to see all available options you can specify on the -command line.) - -Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) -for debugging. - -For more information on configuring the server via the ``paste.deploy`` -configuration files, see the section entitled -:doc:`Configuring Keystone ` - -Note that the server `daemonizes` itself by using the standard -shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend -using the ``keystone-control`` server daemon wrapper for daemonizing. See below -for more details on daemonization with ``keystone-control``. - -Using ``keystone-control`` to start the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The second way to start up a Keystone server is to use the ``keystone-control`` -program. ``keystone-control`` is a wrapper script that allows the user to -start, stop, restart, and reload the other Keystone server programs in -a fashion that is more conducive to automation and scripting. - -Servers started via the ``keystone-control`` program are always `daemonized`, -meaning that the server program process runs in the background. - -To start a Keystone server with ``keystone-control``, simply call -``keystone-control`` with a server and the word "start", followed by -any command-line options you wish to provide. Start the server with ``keystone-control`` -in the following way:: - - $ sudo keystone-control start [CONFPATH] - -.. note:: - - You must use the ``sudo`` program to run ``keystone-control`` currently, as the - pid files for the server programs are written to /var/run/keystone/ - -Start the ``keystone-admin`` server using ``keystone-control``:: - - $ sudo keystone-control admin start - Starting keystone-admin with /etc/keystone.conf - -The same ``paste.deploy`` configuration files are used by ``keystone-control`` -to start the Keystone server programs, and you can specify (as the example above -shows) a configuration file when starting the server. - -Stopping a server ------------------ - -If you started a Keystone server manually and did not use the ``&`` backgrounding -function, simply send a terminate signal to the server process by typing -``Ctrl-C`` - -If you started the Keystone server using ``keystone-control``, you can -use the ``keystone-control`` program to stop it:: - - $ sudo keystone-control stop - -For example:: - - $ sudo keystone-control auth stop - Stopping keystone-auth pid: 77401 signal: 15 - -Restarting a server -------------------- - -Restart the Keystone server using ``keystone-control``:: - - $ sudo keystone-control admin restart /etc/keystone.conf - Stopping keystone-admin pid: 77401 signal: 15 - Starting keystone-admin with /etc/keystone.conf diff --git a/docs/source/endpoints.rst b/docs/source/endpoints.rst deleted file mode 100644 index 84a42e09..00000000 --- a/docs/source/endpoints.rst +++ /dev/null @@ -1,430 +0,0 @@ -.. - Copyright 2011 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. - -================================ -Endpoints and Endpoint Templates -================================ - -.. toctree:: - :maxdepth: 1 - -What are Endpoints? -------------------- - -Simply, endpoints are URLs that point to OpenStack services. When you -authenticate to Keystone you get back a token which has a service catalog in -it. The service catalog is basically a list of the OpenStack services that -you have access to and the URLs you can use to get to them; their endpoints. - -Here is an example response from Keystone when you authenticate:: - - { - "access":{ - "token":{ - "id":"ab48a9efdfedb23ty3494", - "expires":"2010-11-01T03:32:15-05:00", - "tenant":{ - "id": "t1000", - "name": "My Project" - } - }, - "user":{ - "id":"u123", - "name":"jqsmith", - "roles":[{ - "id":"100", - "name":"compute:admin" - }, - { - "id":"101", - "name":"object-store:admin", - "tenantId":"t1000" - } - ], - "roles_links":[] - }, - "serviceCatalog":[{ - "name":"Nova", - "type":"compute", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://compute.north.host.com/v1/t1000", - "internalURL":"https://compute.north.internal/v1/t1000", - "region":"North", - "versionId":"1", - "versionInfo":"https://compute.north.host.com/v1/", - "versionList":"https://compute.north.host.com/" - }, - { - "tenantId":"t1000", - "publicURL":"https://compute.north.host.com/v1.1/t1000", - "internalURL":"https://compute.north.internal/v1.1/t1000", - "region":"North", - "versionId":"1.1", - "versionInfo":"https://compute.north.host.com/v1.1/", - "versionList":"https://compute.north.host.com/" - } - ], - "endpoints_links":[] - }, - { - "name":"Swift", - "type":"object-store", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://storage.north.host.com/v1/t1000", - "internalURL":"https://storage.north.internal/v1/t1000", - "region":"North", - "versionId":"1", - "versionInfo":"https://storage.north.host.com/v1/", - "versionList":"https://storage.north.host.com/" - }, - { - "tenantId":"t1000", - "publicURL":"https://storage.south.host.com/v1/t1000", - "internalURL":"https://storage.south.internal/v1/t1000", - "region":"South", - "versionId":"1", - "versionInfo":"https://storage.south.host.com/v1/", - "versionList":"https://storage.south.host.com/" - } - ] - }, - { - "name":"DNS-as-a-Service", - "type":"dnsextension:dns", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://dns.host.com/v2.0/t1000", - "versionId":"2.0", - "versionInfo":"https://dns.host.com/v2.0/", - "versionList":"https://dns.host.com/" - } - ] - } - ] - } - } - -Note the following about this response: - -#. There are two endpoints given to the Nova compute service. The only - difference between them is the version (1.0 vs. 1.1). This allows for code - written to look for the version 1.0 endpoint to still work even after the 1.1 - version is released. - -#. There are two endpoints for the Swift object-store service. The difference - between them is they are in different regions (North and South). - -#. Note the DNS service is global; it does not have a Region. Also, since DNS - is not a core OpenStack service, the endpoint type is "dnsextension:dns" - showing it is coming from an extension to the Keystone service. - -#. The Region, Tenant, and versionId are listed under the endpoint. You do not - (and should not) have to parse those out of the URL. In fact, they may not be - embedded in the URL if the service developer so chooses. - - -What do the fields in an Endpoint mean? ---------------------------------------- - -The schema definition for an endpoint is in endpoints.xsd under -keystone/content/common/xsd in the Keystone code repo. The fields are: - -id - A unique ID for the endpoint. - -type - The OpenStack-registered type (ex. 'compute', 'object-store', 'image service') - This can also be extended using the OpenStack Extension mechanism to support - non-core services. Extended services will be in the form ``extension:type`` - (e.g. ``dnsextension:dns``) - -name - This can be anything that the operator of OpenStack chooses. It could be a - brand or marketing name (ex. Rackspace Cloud Servers). - -region - This is a string that identifies the region where this endpoint exists. - Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or - 'Data Center 1', 'Data Center 2'. - The list of regions and what a region means is decided by the operator. The - spec treats them as opaque strings. - -publicURL - This is the URL to use to access that endpoint over the internet. - -internalURL - This is the URL to use to communicate between services. This is genenrally - a way to communicate between services over a high bandwidth, low latency, - unmetered (free, no bandwidth charges) network. An example would be if you - want to access a swift cluster from inside your Nova VMs and want to make - sure the communication stays local and does not go over a public network - and rack up your bandwidth charges. - -adminURL - This is the URL to use to administer the service. In Keystone, this URL - is only shown to users with the appropriate rights. - -tenantId - If an endpoint is specific to a tenant, the tenantId field identifies the - tenant that URL applies to. Some operators include the tenant in the - URLs for a service, while others may provide one endpoint and use some - other mechanism to identify the tenant. This field is therefore optional. - Having this field also means you do not have to parse the URL to identify - a tenant if the operator includes it in the URL. - -versionId - This identifies the version of the API contract that endpoint supports. - While many APIs include the version in the URL (ex: https://compute.host/v1), - this field allows you to identify the version without parsing the URL. It - therefore also allows operators and service developers to publish endpoints - that do not have versions embedded in the URL. - -versionInfo - This is the URL to call to get some information on the version. This returns - information in this format:: - - { - "version": { - "id": "v2.0", - "status": "CURRENT", - "updated": "2011-01-21T11:33:21-06:00", - "links": [ - { - "rel": "self", - "href": "http://identity.api.openstack.org/v2.0/" - }, { - "rel": "describedby", - "type": "application/pdf", - "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" - }, { - "rel": "describedby", - "type": "application/vnd.sun.wadl+xml", - "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" - } - ], - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.identity+xml;version=2.0" - }, { - "base": "application/json", - "type": "application/vnd.openstack.identity+json;version=2.0" - } - ] - } - } - -versionList - - This is the URL to call to find out which versions are supported at that - endpoint. The response is in this format:: - - { - "versions":[{ - "id":"v1.0", - "status":"DEPRECATED", - "updated":"2009-10-09T11:30:00Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.0/" - } - ] - }, - { - "id":"v1.1", - "status":"CURRENT", - "updated":"2010-12-12T18:30:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.1/" - } - ] - }, - { - "id":"v2.0", - "status":"BETA", - "updated":"2011-05-27T20:22:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v2.0/" - } - ] - } - ], - "versions_links":[] - } - - Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0. - It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA. - -What are Endpoint Templates? ----------------------------- - -Endpoint Templates are a way for an administrator to manage endpoints en masse. -They provide a way to define Endpoints that apply to many or all tenants -without having to a create each endpoint on each tenant manually. Without -Endpoint Templates, if I wanted to create Endpoints for each tenant in my -OpenStack deployment, I'd have to manually create a bunch of endpoints on -each tenant (probably when I created the tenant). And then I'd have to go change -them all whenever a service changed versions or I added a new service. - -To provide a simpler mechanism to manage endpoints on tenants, Keystone uses -Endpoint Templates. I can, for example, define a template with parametrized URLs -and set it's `global` to true and that will show up as an endpoint on all the tenants -I have. Here is an example: - -Define a global Endpoint Template:: - - $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1 - - The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global' - -This creates a global endpoint (global means it gets applied to all tenants automatically). - -Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example -authentication request for use against tenant 1:: - - $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens - -The response is:: - - { - "access": { - "serviceCatalog": [ - { - "endpoints": [ - { - "internalURL": "https://compute.north.example.local", - "publicURL": "https://compute.north.example.com/v1/1/", - "region": "North" - } - ], - "name": "nova", - "type": "compute" - } - ], - "token": { - "expires": "2012-02-05T00:00:00", - "id": "887665443383838", - "tenant": { - "id": "1", - "name": "customer-x" - } - }, - "user": { - "id": "1", - "name": "joeuser", - "roles": [ - { - "id": "3", - "name": "Member", - "tenantId": "1" - } - ] - } - } - } - -Notice the adminURL is not showing (this user is a regular user and does not -have rights to see the adminURL) and the tenant ID has been substituted in the -URL:: - - "publicURL": "https://compute.north.example.com/v1/1/", - -This endpoint will show up for all tenants. The OpenStack administrator does -not need to create the endpoint manually. - -.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). - - -What parameters can I use in a Template URL -------------------------------------------- - -Currently the only parameterization available is %tenant_id% which gets -substituted by the Tenant ID. - - -Endpoint Template Types: Global or not --------------------------------------- - -When the global flag is set to true on an Endpoint Template, it means it should -be available to all tenants. Whenever someone authenticates to a tenant, they -will see the Endpoint generated by that template. - -When the global flag is not set, the template only shows up when it is added to -a tenant manually. To add an endpoint to a tenant manually, you must create -the Endpoint and supply the Endpoint Template ID: - -Create the Endpoint Template:: - - $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 - - Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. - -Find the Endpoint Template ID:: - - $ ./keystone-manage endpointTemplates list - - All EndpointTemplates - id service type region enabled is_global Public URL Admin URL - ------------------------------------------------------------------------------- - 15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp - 16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp - -Add the Endpoint to the tenant:: - - $ ./keystone-manage endpoint add customer-x 16 - -Now, when the user authenticates, they get the endpoint:: - - { - "internalURL": "https://compute.west.example.local", - "publicURL": "https://compute.west.example.com/v1/1/", - "region": "West" - } - -Who can see the AdminURL? -------------------------- - -Users who have the Keystone `Admin` or `Service Admin` roles will see the -AdminURL when they authenticate or when they retrieve token information: - -Using an administrator token to authenticate, GET a client token's endpoints:: - - $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints - - { - "endpoints": [ - { - "adminURL": "https://compute.west.example.corp", - "id": 6, - "internalURL": "https://compute.west.example.local", - "name": "nova", - "publicURL": "https://compute.west.example.com/v1/1/", - "region": "West", - "tenantId": 1, - "type": "compute" - } - ], - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", - "rel": "next" - } - ] - } diff --git a/docs/source/extensions.rst b/docs/source/extensions.rst deleted file mode 100644 index 539bef39..00000000 --- a/docs/source/extensions.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. - Copyright 2011 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. - -========== -Extensions -========== - -Extensions support adding features and functions to OpenStack APIs at any time, without prior -approval or waiting for a new API and release cycles. - -The extension framework is in development and documented in extensions_ and extensionspresentation_. - -This document describes the extensions included with Keystone, how to enable and disable them, -and briefly touches on how to write your own extensions. - -.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html -.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions - -Built-in Extensions -------------------- - -Keystone ships with a number of extensions found under the -``keystone/contib/extensions`` folder. - -The following built-in extensions are included: - -OS-KSADM - - This is an extensions that supports managing users, tenants, and roles - through the API. Without this extensions, the ony way to manage those - objects is through keystone-manage or directly in the underlying database. - - This is an Admin API extension only. - -OS-KSCATALOG - - This extensions supports managing Endpoints and prrovides the Endpoint - Template mechanism for managing bulk endpoints. - - This is an Admin API extension only. - -OS-EC2 - - This extension adds support for EC2 credentials. - - This is an Admin and Service API extension. - -RAX-GRP - - This extension adds functionality the enables groups. - - This is an Admin and Service API extension. - -RAX-KEY - - This extensions adds support for authentication with an API Key (the core - Keystone API only supports username/password credentials) - - This is an Admin and Service API extension. - -HP-IDM - - This extension adds capability to filter roles with optional service IDs - for token validation to mitigate security risks with role name conflicts. - See https://bugs.launchpad.net/keystone/+bug/890411 for more details. - - This is an Admin API extension. Applicable to validate token (GET) - and check token (HEAD) APIs only. - -OS-KSVALIDATE - - This extensions supports admin calls to /tokens without having to specify - the token ID in the URL. Instead, the ID is supplied in a header called - X-Subject-Token. This is provided as an alternative to address any security - concerns that arise when token IDs are passed as part of the URL which is - often (and by default) logged to insecure media. - - This is an Admin API extension only. - -.. note:: - - The included extensions are in the process of being rewritten. Currently - osksadm, oskscatalog, hpidm, and osksvalidate work with this new - extensions design. - - -Enabling & Disabling Extensions -------------------------------- - -The Keystone conf file has a property called extensions. This property holds -the list of supported extensions that you want enabled. If you want to -add/remove an extension from being supported, add/remove the extension key -from this property. The key is the name of the folder of the extension -under the keystone/contrib/extensions folder. - -.. note:: - - If you want to load different extensions in the service API than the Admin API - you need to use different config files. - -Creating New Extensions ------------------------ - -#. **Adopt a unique organization abbreviation.** - - This prefix should uniquely identify your organization within the community. - The goal is to avoid schema and resource collisions with similiar extensions. - (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) - -#. **Adopt a unique extension abbreviation.** - - Select an abbreviation to identify your extension, and append to - your organization prefix using a hyphen (``-``), by convention - (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). - - This combination is referred to as your extension's prefix. - -#. **Determine the scope of your extension.** - - Extensions can enhance the Admin API, Service API or both. - -#. **Create a new module.** - - Create a module to isolate your namespace based on the extension prefix - you selected:: - - keystone/contrib/extensions/admin - - ... and/or:: - - keystone/contrib/extensions/service/ - - ... based on which API you are enhancing. - - .. note:: - - In the future, we will support loading external extensions. - -#. Add static extension files for JSON (``*.json``) and XML - (``*.xml``) to the new extension module. - - Refer to `Service Guide `_ - `Sample extension XML `_ - `Sample extension JSON `_ for the the content and structure. - -#. If your extension is adding additional methods override the base class - ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. - -#. **Document your work.** - - Provide documentation to support your extension. - - Extensions documentation, WADL, and XSD files can be stored in the - ``keystone/content`` folder. - -#. Add your extension name to the list of supported extensions in The - ``keystone.conf`` file. - -Which extensions are enabled? ------------------------------ - -Discover which extensions are available (service API):: - - curl http://localhost:5000/v2.0/extensions - -... or (admin API):: - - curl http://localhost:35357/v2.0/extensions - -The response will list the extensions available. diff --git a/docs/source/index.rst b/docs/source/index.rst index 427414d4..8b12ff93 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -42,8 +42,8 @@ Getting Started :maxdepth: 1 setup - configuration - configuringservices + configuration + configuringservices community Man Pages @@ -53,7 +53,7 @@ Man Pages :maxdepth: 1 man/keystone - man/keystone-manage + man/keystone-manage Developers Documentation ======================== diff --git a/docs/source/middleware.rst b/docs/source/middleware.rst deleted file mode 100644 index 69506ee2..00000000 --- a/docs/source/middleware.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. - Copyright 2011 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 -========== - -The Keystone middleware sits in front of an OpenStack service and handles authenticating -incoming requests. The middleware was designed according to `this spec`. - -The middleware is found in source under Keystone/middleware. - -The middleware supports two interfaces; WSGI and REST/HTTP. - -.. _`this spec`: http://wiki.openstack.org/openstack-authn - -REST & HTTP API -=============== - -If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per -HTTP standards, it will also return a WWW-Authenticate header informing the caller -of what protocols are supported. For Keystone authentication, the response syntax will be:: - - WWW-Authenticate: Keystone uri="url to Keystone server" - -The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token. - -The token is passed in using ther X-Auth-Token header. - -WSGI API (Headers) -================== - -Upon successful authentication the middleware sends the following -headers to the downstream WSGI app: - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -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-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-Roles - The roles associated with that user - - -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 = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 - -*The required configuration entries are:* - -auth_host - The IP address or DNS name of the Keystone server - -auth_port - The TCP/IP port of the Keystone server - -auth_protocol - The protocol of the Keystone server ('http' or 'https') - -auth_uri - The externally accessible URL of the Keystone server. This will be where unauthenticated - clients are redirected to. This is in the form of a URL. For example, if they make an - unauthenticated call, they get this response:: - - HTTP/1.1 401 Unauthorized - Www-Authenticate: Keystone uri='https://auth.example.com/' - Content-Length: 381 - - In this case, the auth_uri setting is set to https://auth.example.com/ - -admin_token - This is the long-lived token issued to the service to authenticate itself when calling - Keystone. See :doc:`configuration` for more information on setting this up. - - -*Optional parameters are:* - -delay_auth_decision - Whether the middleware should reject invalid or unauthenticated calls directly or not. If not, - it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS - header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the - service can then decide if it wants to honor the call or not. This is useful if the service offers - some resources publicly, for example. - -auth_timeout - The amount of time to wait before timing out a call to Keystone (in seconds) - -memcache_hosts - This is used to point to a memcached server (in ip:port format). If supplied, - the middleware will cache tokens and data retrieved from Keystone in memcached - to minimize calls made to Keystone and optimize performance. - -.. warning:: - Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone, - the service will not know and will continue to honor the token as it has them stored in memcached. - Also note that tokens and data stored in memcached are not encrypted. The memcached server must - be trusted and on a secure network. - - -*Parameters needed in a distributed topology.* In this configuration, the middleware is running -on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture` -for details on different deployment topologies): - -service_host - The IP address or DNS name of the location of the service (since it is remote - and not automatically down the WSGI chain) - -service_port - The TCP/IP port of the remote service. - -service_protocol - The protocol of the service ('http' or 'https') - -service_pass - The basic auth password used to authenticate to the service (so the service - knows the call is coming from a server that has validated the token and not from - an untrusted source or spoofer) - -service_timeout - The amount of time to wait for the service to respond before timing out. diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst deleted file mode 100644 index a8c38f3c..00000000 --- a/docs/source/middleware_architecture.rst +++ /dev/null @@ -1,529 +0,0 @@ -.. - Copyright 2011 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 multiple authentication protocols -in a pluggable manner in OpenStack. By providing support for authentication via -pluggable authentication components, this architecture allows OpenStack -services to be integrated easily into existing deployment environments. It also -provides a path by which to implement support for emerging authentication -standards such as OAUTH. - -Rationale and Goals -=================== - -Keystone is the Identity service for OpenStack. To support the easy integrating -of OpenStack with existing authentication and identity management systems, -Keystone supports talking to multiple backends like LDAP. -And to support different deployment needs, it can support multiple -authentication protocols via pluggable 'authentication components' implemented -as WSGI middleware. - -In this document, we describe the responsibilities of the authentication -middleware. We describe how these interact with underlying OpenStack services -and how existing services can be modified to take advantage of pluggable -authentication. The goal is to allow OpenStack services to be integrated easily -into existing deployment environments and to provide a path by which to -implement support for emerging authentication standards such as OAUTH. - -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. - -At a high level, an authentication component is simply a reverse proxy that -intercepts HTTP calls from clients. Once it has verified a user's identity, the -authentication component extends the call with information about the current -user and forwards the request to the OpenStack service. Otherwise, if a user's -identity is not verified, the message is rejected before it gets to the -service. This is illustrated in :ref:`authComponent`. - -.. _authComponent: - -Authentication Component ------------------------- - -Figure 1. Authentication Component - -.. image:: images/graphs_authComp.svg - :width: 100% - :height: 180 - :alt: An Authentication Component - -Authentication components may operate in 'delegated mode'. In this mode, the -decision reject an unauthenticated client is delegated to the OpenStack -service. Delegated mode is 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. Note that it is always the responsibility -of the Authentication Component to transmit reject messages 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) - -In this architecture, we define interactions between the authentication component -and the OpenStack service. Interactions between the client and the -authentication component are defined only for exceptional cases. For example, -we define the message that should be returned when the OpenStack service is -down. Other interactions, however, are defined by the underlying authentication -protocol and the OpenStack service and are considered out of scope. - -.. _deployStrategies: - -Deployment Strategies -===================== - -An authentication component may be integrated directly into the service -implementation, or it may be deployed separately as an HTTP reverse proxy. This -is illustrated in :ref:`deployment`, showing both approaches to -authentication, labeled Option (a) and Option (b). - -.. _deployment: - -Authentication Component Deployments Options --------------------------------------------- - -Figure 3. Authentication Component Deployments Options - -.. image:: images/images_layouts.svg - :width: 100% - :height: 180 - :alt: Authentication Component Deployments Options - -In Option (a), the component is integrated into the service implementation. In -this case, communication between the authentication component and the service -can be efficiently implemented via a method call. In Option (b), the component -is deployed separately and communication between the service and the component -involves an HTTP request. In both cases, unauthenticated requests are filtered -before they reach the service. - -Each approach offers some benefits. Option (a) offers low latency and ease of -initial implementation, making it possibly most appropriate as a starting point -for simple configurations. Option (b) offers several key advantages that may be -of particular value in complex and dynamic configurations. It offers the -ability to scale horizontally in cases where authentication is computationally -expensive, such as when verifying digital signatures. Option (b) also allows -authentication components to be written in different programming languages. -Finally, Option (b) allows multiple authentication components to be deployed in -front of the same service. - -OpenStack services can support both embedded (Option (a)) and external (Option -(b)) deployment strategies. Individual authentication components should support -either strategy or they |may| support both strategies. In order to support -option (a), authentication components written in the Python programming -language should be written as WSGI middleware components (in accordance with -the Web Server Gateway Interface (WSGI) standard [PEP-333]_. - -Additionally, services should support the ability to swap between different -embedded or external authentication components via configuration options. - -Exchanging User Information -=========================== - -If a request is successfully authenticated, the authentication component must -extend the request by adding an ``X-Authorization`` header. The header |must| -be formatted as illustrated in :ref:`xAuthHeader`. - -.. _xAuthHeader: - -X-Authorization Header ----------------------- - -Example 1. X-Authorization Header:: - - X-Authorization: Proxy JoeUser - -Here, `Proxy` denotes that the authentication occurred via a proxy (in this -case authentication component) and ''JoeUser'' is the name of the user who -issued the request. - -.. note: - - We considered using an ``Authorization`` header rather than an - ``X-Authorization``, thereby following normal HTTP semantics. There are some - cases, however, where multiple ``Authorization`` headers need to be transmitted - in a single request. We want to assure ourselves that this will not break - common clients before we recommend the approach. - -Authentication components |may| extend the request with additional -information. For example, an authentication system may add additional headers -or modify the target URI to pass authentication information to the back-end -service. Additionally, an authentication component |may| strip sensitive -information — a plain text password, for example — from the request. That said, -an authentication component |should| pass the majority of the request -unmodified. - -Reverse Proxy Authentication ----------------------------- - -An OpenStack service |should| verify that it is receiving requests from a -trusted authentication component. This is particularly important in cases where -the authentication component and the OpenStack service are deployed separately. -In order to trust incoming requests, the OpenStack service should therefore -authenticate the authentication component. To avoid confusion, we call this -'reverse proxy authentication', since in this case the authentication -component is acting as an HTTP reverse proxy. - -Any HTTP-based authentication scheme may be used for reverse proxy -authentication; however, all OpenStack services and all authentication -components |must| support HTTP Basic Authentication as defined in -[RFC-2617]_. - -Whether or not reverse proxy authentication is required is strictly a -deployment concern. For example, an operations team may opt to utilize firewall -rules instead of an authentication protocol to verify the integrity of incoming -request. Because of this, both OpenStack services and authentication components -|must| also allow for unauthenticated communication. - -In cases where reverse proxy authentication is used, the authorization -component may receive an HTTP 401 authentication error or an HTTP 403 -authorization error. These errors indicate that the component does not have -access to the underlying OpenStack service. The authentication component -|must not| return these errors to the client application. Instead, the -component |must| return a 500 internal error. This is illustrated in -:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component -|should| format the errors in a manner that does not break the service -contract defined by the OpenStack service. :ref:`proxyAuthDelegated` -illustrates proxy authorization in delegated mode. Delegated mode is discussed -in detail in the next section. - -.. _proxyAuth: - -Reverse Proxy Authentication ----------------------------- - -Figure 4. Reverse Proxy Authentication - -.. image:: images/graphs_proxyAuth.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication - -.. _proxyAuthDelegated: - -Reverse Proxy Authentication (Delegated Mode) ---------------------------------------------- - -Figure 5. Reverse Proxy Authentication (Delegated Mode) - -.. image:: images/graphs_delegate_forbiden_proxy.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication (Delegated Mode) - -Delegated Mode -============== -In some cases, the decision to reject an unauthenticated request should be -delegated to the OpenStack service. An unauthenticated request may be -appropriate in cases when anonymous access is allowed. In order to support -these cases, an authentication component may be placed in Delegated Mode. In -this mode, the component forwards requests to the OpenStack service when the -client's identity has been confirmed or is indeterminate — that is when -credentials are missing. The authentication component directly rejects requests -with invalid credentials. Authentication components |must| extend the -request by adding an `X-Identity-Status` header. The identity status header -|must| contain one of the following values: - -Identity Status Values ----------------------- - -Confirmed - A `confirmed` value indicates that valid credentials were sent and identity - has been confirmed. The service can trust that the request has been sent on - behalf of the user specified in the `X-Authorization` header. - -Indeterminate - An `indeterminate` value indicates that no credentials were sent and - identity has not been confirmed. In this case, the service will receive an - `X-Authorization` header with no user entry as illustrated in - :ref:`xauth-header-indeterminate`. - -.. _xauth-header-indeterminate: - -Indeterminate Identity Headers ------------------------------- - -Example 2. Indeterminate Identity Headers:: - - X-Identity-Status: Indeterminate - X-Authorization: Proxy - -Services |may| reject a delegated request by issuing an HTTP 401 -authentication error or an HTTP 403 authorization error. These responses -|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as -illustrated in :ref:`unauthHeaders`. - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -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-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-Roles - The roles associated with that user - -.. _unauthHeaders: - -Delegated WWW-Authenticate Header ---------------------------------- - -:: - - WWW-Authenticate: Delegated - -It is important to note that the actual reject message will likely be modified -by the authentication component in order to comply with the authentication -scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and -:ref:`delegateRejectOAuth` below. - -.. _delegateRejectBasic: - -Delegated Reject Basic Auth ---------------------------- - -.. image:: images/graphs_delegate_reject_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Basic Auth - -.. _delegateRejectOAuth: - -Delegated Reject OAuth ----------------------- - -.. image:: images/graphs_delegate_reject_oauth.svg - :width: 100% - :height: 180 - :alt: Delegated Reject OAuth - -The presence of the `WWW-Authenticate` header with a value of `Delegated` -distinguishes a client authentication/authorization failure from a component -failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In -:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. -In :ref:`proxyAuthDelegated`, it is the authentication component itself which is -unauthorized. - -.. _delegateForbidden: - -Delegated Reject Forbidden --------------------------- - -Figure 8. Delegated Reject Forbidden - -.. image:: images/graphs_delegate_forbiden_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Forbidden - -Authentication components |must| support both delegated and undelegated -(standard) modes. Delegated mode |should| be configured via a configuration -option. Delegated mode |should| be disabled by default. - -OpenStack services are not required to support delegated mode. If a service -does not support delegated mode, it |must| respond with a 501 not implemented -error and an `WWW-Authenticate` header with a value of `Delegated`. The -authentication component |must not| return the error to the client -application. Instead, the component |must| return a 500 internal error; this is -illustrated in :ref:`delegateUnimplemented`. The component |should| -format the error in a manner that does not break the service contract defined -by the OpenStack service. The component should also log the error such that it -that will inform operators of the misconfiguration. - -.. _delegateUnimplemented: - -Unimplemented Delegated Mode ----------------------------- - -.. image:: images/graphs_delegate_unimplemented.svg - :width: 100% - :height: 180 - :alt: Unimplemented Delegated Mode - -Handling Direct Client Connections -================================== - -Requests from the authentication component to an OpenStack service |must| -contain an ``X-Authorization`` header. If the header is missing, and reverse -proxy authentication fails or is switched off, the OpenStack service |may| -assume that the request is coming directly from a client application. In this -case, the OpenStack service |must| redirect the request to the authentication -component by issuing an HTTP 305 User Proxy redirect. This is illustrated in -:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header -specifying the authentication component's URL as shown in :ref:`redirect-response`. - -.. _redirect: - -Auth Component Redirect ------------------------ - -.. image:: images/graphs_305.svg - :width: 100% - :height: 280 - :alt: Auth Component Redirect - -.. _redirect-response: - -Auth Component Redirect Response --------------------------------- - -:: - - HTTP/1.1 305 Use Proxy - Date: Thu, 28 Oct 2011 07:41:16 GMT - Location: http://sample.auth.openstack.com/path/to/resource - -Using Multiple Authentication Components -======================================== - -There are some use cases when a service provider might want to consider using -multiple authentication components for different purposes. For instance, a -service provider may have one authentication scheme to authenticate the users -of the service and another one to authenticate the administrators or operations -personnel that maintain the service. For such scenarios, we propose using a -mapper as illustrated in :ref:`multiAuth`. - -.. _multiAuth: - -Multiple Authentication Components ----------------------------------- - -.. image:: images/graphs_mapper.svg - :width: 100% - :height: 320 - :alt: Multiple Authentication Components - -At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls -from clients and routes the request to the appropriate authentication -component. A mapper can make the routing decisions based on a number of routing -rules that map a resource to a specific authentication component. For example, -a request URI may determine whether a call should be authenticated via one -authentication component or another. - -Note that neither the authentication component nor the OpenStack service need -be aware of the mapper. Any external authentication component can be used -alongside others. Mappers may provide a means by which to offer support for -anonymous or guest access to a subset of service resources. A mapper may be -implemented via a traditional reverse proxy server such as Pound or Zeus. - -The Default Component -===================== - -Individual services |must| be distributed with a simple integrated -authentication component by default. Providing such a component lowers barriers -to the deployment of individual services. This is especially important to] -developers who may want to deploy OpenStack services on their own machines. -Also, since there is no direct dependency on an external authentication system, -OpenStack services can be deployed individually, without the need to stand up -and configure additional services. Finally, having a standard authentication -component that all services share promotes a separation of concerns. That is, -as a community we are explicitly stating that services should not develop their -own authentication mechanisms. Additional authentication components may be -developed, of course, but these components should not be intimately coupled to -any one particular service. - -As discussed in :ref:`deployStrategies`, an authentication component may be -integrated directly into the service implementation (Option (a)), or it may be -deployed separately as an HTTP reverse proxy (Option (b)). The default -component should be implemented to support Option (a) and services should -maintain support for Option (b). One way to achieve this is to provide a -method that allows the disabling of the default authentication component via -configuration. This is illustrated in :ref:`both`. Here, requests are -sent directly to the OpenStack service when the default authentication -component is disabled. - -We will discuss the design of the default component in an upcoming blueprint. - -.. _both: - -Disabled Embedded Component ---------------------------- - -.. image:: images/graphs_both.svg - :width: 100% - :height: 250 - :alt: Disabled Embedded Component - -Questions and Answers -===================== - -#. Why do authentication components send reject messages? Why not have - OpenStack services reject requests themselves? - - The content and format of an authentication failed message is determined by - the authentication scheme (or protocol). For the service to respond - appropriately, it would have to be aware of the authentication scheme in - which it participates; this defeats the purpose of pluggable authentication - components. - -#. Why require support for deploying authentication components in separate - nodes? - - The deployment strategy is very flexible. It allows for authentication - components to be horizontally scalable. It allows for components to be written - in different languages. Finally, it allows different authentication components - to be deployed simultaneously as described above. - -References -========== - -.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface - v1.0.'' http://www.python.org/dev/peps/pep-0333/. - -.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. - P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest - Access Authentication.'' http://tools.ietf.org/html/rfc2617. - -.. |must| replace:: must must -.. |should| replace:: should should -.. |may| replace:: may may -.. |must not| replace:: "must not" "must not" - diff --git a/docs/source/migration.rst b/docs/source/migration.rst deleted file mode 100644 index 460d980b..00000000 --- a/docs/source/migration.rst +++ /dev/null @@ -1,126 +0,0 @@ -=================== -Database Migrations -=================== - -Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage -migrations. - -Migrations are tracked using a metadata table (``migrate_version``), which -allows keystone to compare the state of your database to the state it -expects, and to move between versions. - -.. WARNING:: - - Backup your database before applying migrations. Migrations may - attempt to modify both your schema and data, and could result in data - loss. - - Always review the behavior of migrations in a staging environment - before applying them in production. - -Getting Started -=============== - -Your initial approach to migrations should depend on whether you have an -empty database or a schema full of data. - -Starting with an empty database -------------------------------- - -If you have an empty database for keystone to work with, you can simply -run:: - - $ ./bin/keystone-manage database sync - -This command will initialize your metadata table, and run through all the -schema & data migrations necessary to bring your database in sync with -keystone. That's it! - -Starting with an existing database ----------------------------------- - -Place an existing database under version control to enable migration -support:: - - $ ./bin/keystone-manage database version_control - -This command simply creates a ``migrate_version`` table, set at -``version_number`` 0, which indicates that no migrations have been applied. - -If you are starting with an existing schema, you can jump to a specific -schema version without performing migrations using the ``database goto`` -command. For example, if you're starting from a diablo-compatible -database, set your current database ``version_number`` to ``1`` using:: - - $ ./bin/keystone-manage database goto - -Determine your appropriate database ``version_number`` by referencing the -following table: - - +------------+-------------+ - | Release | ``version`` | - +============+=============+ - | pre-diablo | (see below) | - +------------+-------------+ - | diablo | 1 | - +------------+-------------+ - | essex-m1 | 3 | - +------------+-------------+ - | essex-m2 | 4 | - +------------+-------------+ - -From there, you can upgrade normally (see :ref:`upgrading`). - -Starting with a pre-diablo database (cactus) --------------------------------------------- - -You'll need to manually migrate your database to a diablo-compatible -schema, and continue forward from there (if desired) using migrations. - -.. _upgrading: - -Upgrading & Downgrading -======================= - -.. note:: - - Attempting to start keystone with an outdated schema will cause - keystone to abort, to avoid corrupting your data. - -Upgrade to the latest version automatically:: - - $ ./bin/keystone-manage database sync - -Check your current schema version:: - - $ ./bin/keystone-manage database version - -Jump to a specific version without performing migrations:: - - $ ./bin/keystone-manage database goto - -Upgrade to a specific version:: - - $ ./bin/keystone-manage database upgrade - -Downgrade to a specific version (will likely result in data loss!):: - - $ ./bin/keystone-manage database downgrade - -Opting Out of Migrations -======================== - -If you don't want to use migrations (e.g. if you want to manage your -schema manually), keystone will complain in your logs on startup, but -won't actually stop you from doing so. - -It's recommended that you use migrations to get up and running, but if -you want to manage migrations manually after that, simply drop the -``migrate_version`` table:: - - DROP TABLE migrate_version; - -Useful Links -============ - -Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst deleted file mode 100644 index 586bac72..00000000 --- a/docs/source/nova-api-paste.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. - Copyright 2011 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. - -nova-api-paste example -====================== -:: - - ####### - # EC2 # - ####### - - [composite:ec2] - use = egg:Paste#urlmap - /: ec2versions - /services/Cloud: ec2cloud - /services/Admin: ec2admin - /latest: ec2metadata - /2007-01-19: ec2metadata - /2007-03-01: ec2metadata - /2007-08-29: ec2metadata - /2007-10-10: ec2metadata - /2007-12-15: ec2metadata - /2008-02-01: ec2metadata - /2008-09-01: ec2metadata - /2009-04-04: ec2metadata - /1.0: ec2metadata - - [pipeline:ec2cloud] - pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor - - [pipeline:ec2admin] - pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor - - [pipeline:ec2metadata] - pipeline = logrequest ec2md - - [pipeline:ec2versions] - pipeline = logrequest ec2ver - - [filter:logrequest] - paste.filter_factory = nova.api.ec2:RequestLogging.factory - - [filter:ec2lockout] - paste.filter_factory = nova.api.ec2:Lockout.factory - - [filter:totoken] - paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory - - [filter:ec2noauth] - paste.filter_factory = nova.api.ec2:NoAuth.factory - - [filter:authenticate] - paste.filter_factory = nova.api.ec2:Authenticate.factory - - [filter:cloudrequest] - controller = nova.api.ec2.cloud.CloudController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:adminrequest] - controller = nova.api.ec2.admin.AdminController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:authorizer] - paste.filter_factory = nova.api.ec2:Authorizer.factory - - [app:ec2executor] - paste.app_factory = nova.api.ec2:Executor.factory - - [app:ec2ver] - paste.app_factory = nova.api.ec2:Versions.factory - - [app:ec2md] - paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory - - ############# - # Openstack # - ############# - - [composite:osapi] - use = egg:Paste#urlmap - /: osversions - /v1.1: openstackapi - - [pipeline:openstackapi] - pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp - - [filter:faultwrap] - paste.filter_factory = nova.api.openstack:FaultWrapper.factory - - [filter:auth] - paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory - - [filter:noauth] - paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory - - [filter:ratelimit] - paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory - - [filter:extensions] - paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory - - [app:osapiapp] - paste.app_factory = nova.api.openstack:APIRouter.factory - - [pipeline:osversions] - pipeline = faultwrap osversionapp - - [app:osversionapp] - paste.app_factory = nova.api.openstack.versions:Versions.factory - - ########## - # Shared # - ########## - - [filter:keystonecontext] - paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory - - [filter:authtoken] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_protocol = http - service_host = 127.0.0.1 - service_port = 5000 - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://127.0.0.1:5000/ - admin_token = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/old/configuringservices.rst b/docs/source/old/configuringservices.rst new file mode 100644 index 00000000..083c3ec5 --- /dev/null +++ b/docs/source/old/configuringservices.rst @@ -0,0 +1,333 @@ +.. + Copyright 2011 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. + +========================================== +Configuring Services to work with Keystone +========================================== + +.. toctree:: + :maxdepth: 1 + +Once Keystone is installed and running, services need to be configured to work +with it. These are the steps to configure a service to work with Keystone: + +1. Create or get credentials for the service to use + + A set of credentials are needed for each service (they may be + shared if you chose to). Depending on the service, these credentials are + either a username and password or a long-lived token.. + +2. Register the service, endpoints, roles and other entities + + In order for a service to have it's endpoints and roles show in the service + catalog returned by Keystone, a service record needs to be added for the + service. Endpoints and roles associated with that service can then be created. + + This can be done through the REST interface (using the OS-KSCATALOG extension) + or using keystone-manage. + +3. Install and configure middleware for the service to handle authentication + + Clients making calls to the service will pass in an authentication token. The + Keystone middleware will look for and validate that token, taking the + appropriate action. It will also retrive additional information from the token + such as user name, id, tenant name, id, roles, etc... + + The middleware will pass those data down to the service as headers. The + detailed description of this architecture is available here :doc:`middleware_architecture` + +Setting up credentials +====================== + +First admin user - bootstrapping +-------------------------------- + +For a default installation of Keystone, before you can use the REST API, you +need to create your first initial user and grant that user the right to +administer Keystone. + +For the keystone service itself, two +Roles are pre-defined in the keystone configuration file +(:doc:`keystone.conf`). + + #Role that allows admin operations (access to all operations) + keystone-admin-role = Admin + + #Role that allows acting as service (validate tokens, register service, + etc...) + keystone-service-admin-role = KeystoneServiceAdmin + +In order to create your first user, once Keystone is running use +the `keystone-manage` command: + + $ keystone-manage user add admin secrete + $ keystone-manage role add Admin + $ keystone-manage role add KeystoneServiceAdmin + $ keystone-manage role grant Admin admin + $ keystone-manage role grant KeystoneServiceAdmin admin + +This creates the `admin` user (with a password of `secrete`), creates +two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to +the `admin` user. From here, you should now have the choice of using the +administrative API (as well as the :doc:`man/keystone-manage` commands) to +further configure keystone. There are a number of examples of how to use +that API at :doc:`adminAPI_curl_examples`. + + +Setting up services +=================== + +Defining Services and Service Endpoints +--------------------------------------- + +Keystone also acts as a service catalog to let other OpenStack systems know +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:: + + $ keystone-manage service add nova compute "Nova Compute Service" + $ keystone-manage service add glance image "Glance Image Service" + $ keystone-manage service add swift storage "Swift Object Storage Service" + $ keystone-manage service add keystone identity "Keystone Identity Service" + +Once the services are defined, we create endpoints for them. Each service +has three relevant URL's associated with it that are used in the command: + +* the public API URL +* an administrative API URL +* an internal URL + +The "internal URL" is an endpoint the generally offers the same API as the +public URL, but over a high-bandwidth, low-latency, unmetered (free) network. +You would use that to transfer images from nova to glance for example, and +not the Public URL which would go over the internet and be potentially chargeable. + +The "admin URL" is for administering the services and is not exposed or accessible +to customers without the apporpriate privileges. + +An example of setting up the endpoint for Nova:: + + $ keystone-manage endpointTemplates add RegionOne nova \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + 1 1 + +Glance:: + + $ keystone-manage endpointTemplates add RegionOne glance \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + 1 1 + +Swift:: + + $ keystone-manage endpointTemplates add RegionOne swift \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + http://swift.mydomain:8080/v1.0/ \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + 1 1 + +And setting up an endpoint for Keystone:: + + $ keystone-manage endpointTemplates add RegionOne keystone \ + http://keystone.mydomain:5000/v2.0 \ + http://keystone.mydomain:35357/v2.0 \ + http://keystone.mydomain:5000/v2.0 \ + 1 1 + + +Defining an Administrative Service Token +---------------------------------------- + +An Administrative Service Token is a bit of arbitrary text which is configured +in Keystone and used (typically configured into) Nova, Swift, Glance, and any +other OpenStack projects, to be able to use Keystone services. + +This token is an arbitrary text string, but must be identical between Keystone +and the services using Keystone. This token is bound to a user and tenant as +well, so those also need to be created prior to setting it up. + +The *admin* user was set up above, but we haven't created a tenant for that +user yet:: + + $ keystone-manage tenant add admin + +and while we're here, let's grant the admin user the 'Admin' role to the +'admin' tenant:: + + $ keystone-manage role add Admin + $ keystone-manage role grant Admin admin admin + +Now we can create a service token:: + + $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 + +This creates a service token of '999888777666' associated to the admin user, +admin tenant, and expires on February 5th, 2015. This token will be used when +configuring Nova, Glance, or other OpenStack services. + +Securing Communications with SSL +-------------------------------- + +To encrypt traffic between services and Keystone, see :doc:`ssl` + + +Setting up OpenStack users +========================== + +Creating Tenants, Users, and Roles +---------------------------------- + +Let's set up a 'demo' tenant:: + + $ keystone-manage tenant add demo + +And add a 'demo' user with the password 'guest':: + + $ keystone-manage user add demo guest + +Now let's add a role of "Member" and grant 'demo' user that role +as it pertains to the tenant 'demo':: + + $ keystone-manage role add Member + $ keystone-manage role grant Member demo demo + +Let's also add the admin user as an Admin role to the demo tenant:: + + $ keystone-manage role grant Admin admin demo + +Creating EC2 credentials +------------------------ + +To add EC2 credentials for the `admin` and `demo` accounts:: + + $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' + $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' + +If you have a large number of credentials to create, you can put them all +into a single large file and import them using :doc:`man/keystone-import`. The +format of the document looks like:: + + credentials add admin EC2 'username' 'password' + credentials add admin EC2 'username' 'password' + +Then use:: + + $ keystone-import `filename` + + +Setting Up Middleware +===================== + +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. See :doc:`middleware` +for details on middleware and configuration parameters. + + +Configuring Nova to use Keystone +-------------------------------- + +To configure Nova to use Keystone for authentication, the Nova API service +can be run against the api-paste file provided by Keystone. This is most +easily accomplished by setting the `--api_paste_config` flag in nova.conf to +point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file +included references to the WSGI authentication middleware provided with the +keystone installation. + +When configuring Nova, it is important to create a admin service token for +the service (from the Configuration step above) and include that as the key +'admin_token' in the nova-api-paste.ini. See the documented +:doc:`nova-api-paste` file for references. + +Configuring Swift to use Keystone +--------------------------------- + +Similar to Nova, swift can be configured to use Keystone for authentication +rather than it's built in 'tempauth'. + +1. Add a service endpoint for Swift to Keystone + +2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) + +3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. + Here's an example `/etc/swift/proxy-server.conf`:: + + [DEFAULT] + bind_port = 8888 + user = + + [pipeline:main] + pipeline = catch_errors cache keystone proxy-server + + [app:proxy-server] + use = egg:swift#proxy + account_autocreate = true + + [filter:keystone] + use = egg:keystone#tokenauth + auth_protocol = http + auth_host = 127.0.0.1 + auth_port = 35357 + admin_token = 999888777666 + delay_auth_decision = 0 + service_protocol = http + service_host = 127.0.0.1 + service_port = 8100 + service_pass = dTpw + cache = swift.cache + + [filter:cache] + use = egg:swift#memcache + set log_name = cache + + [filter:catch_errors] + use = egg:swift#catch_errors + + Note that the optional "cache" property in the keystone filter allows any + service (not just Swift) to register its memcache client in the WSGI + environment. If such a cache exists, Keystone middleware will utilize it + to store validated token information, which could result in better overall + performance. + +4. Restart swift + +5. Verify that keystone is providing authentication to Swift + +Use `swift` to check everything works (note: you currently have to create a +container or upload something as your first action to have the account +created; there's a Swift bug to be fixed soon):: + + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v + StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 + Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 + Account: AUTH_1234 + Containers: 1 + Objects: 0 + Bytes: 0 + Accept-Ranges: bytes + X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b + +.. WARNING:: + Keystone currently allows any valid token to do anything with any account. + diff --git a/docs/source/old/controllingservers.rst b/docs/source/old/controllingservers.rst new file mode 100644 index 00000000..ba8bfc06 --- /dev/null +++ b/docs/source/old/controllingservers.rst @@ -0,0 +1,288 @@ +.. + Copyright 2011 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. + +============================ +Controlling Keystone Servers +============================ + +This section describes the ways to start, stop, and reload the Keystone +services. + +Keystone Services +----------------- + +Keystone can serve a number of REST APIs and extensions on different TCP/IP +ports. + +The Service API +~~~~~~~~~~~~~~~~ + +The core Keystone +API is primarily a read-only API (the only write operation being POST /tokens +which authenticates a client, and returns a generated token). +This API is sufficient to use OpenStack if all users, roles, endpoints already +exist. This is often the case if Keystone is using an enterprise backend +and the backend is managed through other entperrise tools and business +processes. This core API is called the Service API and can be started +separately from the more complete Admin API. By default, Keystone runs +this API on port 5000. This is not an IANA assigned port and should not +be relied upon (instead, use the Admin API on port 35357 to look for +this endpoint - more on this later) + +The Service API is started using this command in the /bin directory:: + + $ ./keystone-auth + +The Admin API +~~~~~~~~~~~~~ + +Inn order for Keystone to be a fully functional service out of the box, +API extensions that provide full CRUD operations is included with Keystone. +This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 +extensions. These extensions provide a full set of create, read, update, delete +(CRUD) operations that can be used to manage Keystone objects through REST +calls. By default Keystone runs this full REST API on TCP/IP port 35357 +(assigned by IANA to Keystone). + +The Admin API is started using this command in the /bin directory:: + + $ ./keystone-admin + + +Both APIs can be loaded simultaneously (on different ports) using this command:: + + $ ./keystone + +Starting a server +----------------- + +There are two ways to start a Keystone service (either the Service API server +or the Admin API server): + +- Manually calling the server program +- Using the ``keystone-control`` server daemon wrapper program + +We recommend using the second way in production and the first for development +and debugging. + +Manually starting the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first is by directly calling the server program, passing in command-line +options and a single argument for a ``paste.deploy`` configuration file to +use when configuring the server application. + +.. note:: + + Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` + configuration files that you can copy to a standard configuration directory and + adapt for your own uses. + +If you do `not` specify a configuration file on the command line, Keystone will +do its best to locate a configuration file in one of the +following directories, stopping at the first config file it finds: + +- ``$CWD`` +- ``~/.keystone`` +- ``~/`` +- ``/etc/keystone`` +- ``/etc`` + +The filename that is searched for is ``keystone.conf`` by default. + +If no configuration file is found, you will see an error, like:: + + $ keystone + ERROR: Unable to locate any configuration file. Cannot load application keystone + +Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: + + $ ./keystone -d + keystone-legacy-auth: INFO ************************************************** + keystone-legacy-auth: INFO Configuration options gathered from config file: + keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + keystone-legacy-auth: INFO ================================================ + keystone-legacy-auth: INFO admin_host 0.0.0.0 + keystone-legacy-auth: INFO admin_port 35357 + keystone-legacy-auth: INFO admin_ssl False + keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy + keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem + keystone-legacy-auth: INFO cert_required True + keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem + keystone-legacy-auth: INFO debug True + keystone-legacy-auth: INFO default_store sqlite + keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm + keystone-legacy-auth: INFO hash-password True + keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + keystone-legacy-auth: INFO keystone-admin-role Admin + keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin + keystone-legacy-auth: INFO log_dir . + keystone-legacy-auth: INFO log_file keystone.log + keystone-legacy-auth: INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + keystone-legacy-auth: INFO service_host 0.0.0.0 + keystone-legacy-auth: INFO service_port 5000 + keystone-legacy-auth: INFO service_ssl False + keystone-legacy-auth: INFO verbose False + keystone-legacy-auth: INFO ************************************************** + passlib.registry: INFO registered crypt handler 'sha512_crypt': + Starting the RAX-KEY extension + Starting the Legacy Authentication component + admin : INFO ************************************************** + admin : INFO Configuration options gathered from config file: + admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + admin : INFO ================================================ + admin : INFO admin_host 0.0.0.0 + admin : INFO admin_port 35357 + admin : INFO admin_ssl False + admin : INFO backends keystone.backends.sqlalchemy + admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem + admin : INFO cert_required True + admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem + admin : INFO debug True + admin : INFO default_store sqlite + admin : INFO extensions osksadm,oskscatalog,hpidm + admin : INFO hash-password True + admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + admin : INFO keystone-admin-role Admin + admin : INFO keystone-service-admin-role KeystoneServiceAdmin + admin : INFO log_dir . + admin : INFO log_file keystone.log + admin : INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + admin : INFO service_host 0.0.0.0 + admin : INFO service_port 5000 + admin : INFO service_ssl False + admin : INFO verbose False + admin : INFO ************************************************** + Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + Service API (ssl=False) listening on 0.0.0.0:5000 + Admin API (ssl=False) listening on 0.0.0.0:35357 + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ + + $ sudo keystone-registry keystone-registry.conf & + jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) + + $ ps aux | grep keystone + myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone + myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d + +Simply supply the configuration file as the first argument +and then any common options +you want to use (``-d`` was used above to show some of the debugging +output that the server shows when starting up. Call the server program +with ``--help`` to see all available options you can specify on the +command line.) + +Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) +for debugging. + +For more information on configuring the server via the ``paste.deploy`` +configuration files, see the section entitled +:doc:`Configuring Keystone ` + +Note that the server `daemonizes` itself by using the standard +shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend +using the ``keystone-control`` server daemon wrapper for daemonizing. See below +for more details on daemonization with ``keystone-control``. + +Using ``keystone-control`` to start the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The second way to start up a Keystone server is to use the ``keystone-control`` +program. ``keystone-control`` is a wrapper script that allows the user to +start, stop, restart, and reload the other Keystone server programs in +a fashion that is more conducive to automation and scripting. + +Servers started via the ``keystone-control`` program are always `daemonized`, +meaning that the server program process runs in the background. + +To start a Keystone server with ``keystone-control``, simply call +``keystone-control`` with a server and the word "start", followed by +any command-line options you wish to provide. Start the server with ``keystone-control`` +in the following way:: + + $ sudo keystone-control start [CONFPATH] + +.. note:: + + You must use the ``sudo`` program to run ``keystone-control`` currently, as the + pid files for the server programs are written to /var/run/keystone/ + +Start the ``keystone-admin`` server using ``keystone-control``:: + + $ sudo keystone-control admin start + Starting keystone-admin with /etc/keystone.conf + +The same ``paste.deploy`` configuration files are used by ``keystone-control`` +to start the Keystone server programs, and you can specify (as the example above +shows) a configuration file when starting the server. + +Stopping a server +----------------- + +If you started a Keystone server manually and did not use the ``&`` backgrounding +function, simply send a terminate signal to the server process by typing +``Ctrl-C`` + +If you started the Keystone server using ``keystone-control``, you can +use the ``keystone-control`` program to stop it:: + + $ sudo keystone-control stop + +For example:: + + $ sudo keystone-control auth stop + Stopping keystone-auth pid: 77401 signal: 15 + +Restarting a server +------------------- + +Restart the Keystone server using ``keystone-control``:: + + $ sudo keystone-control admin restart /etc/keystone.conf + Stopping keystone-admin pid: 77401 signal: 15 + Starting keystone-admin with /etc/keystone.conf diff --git a/docs/source/old/endpoints.rst b/docs/source/old/endpoints.rst new file mode 100644 index 00000000..84a42e09 --- /dev/null +++ b/docs/source/old/endpoints.rst @@ -0,0 +1,430 @@ +.. + Copyright 2011 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. + +================================ +Endpoints and Endpoint Templates +================================ + +.. toctree:: + :maxdepth: 1 + +What are Endpoints? +------------------- + +Simply, endpoints are URLs that point to OpenStack services. When you +authenticate to Keystone you get back a token which has a service catalog in +it. The service catalog is basically a list of the OpenStack services that +you have access to and the URLs you can use to get to them; their endpoints. + +Here is an example response from Keystone when you authenticate:: + + { + "access":{ + "token":{ + "id":"ab48a9efdfedb23ty3494", + "expires":"2010-11-01T03:32:15-05:00", + "tenant":{ + "id": "t1000", + "name": "My Project" + } + }, + "user":{ + "id":"u123", + "name":"jqsmith", + "roles":[{ + "id":"100", + "name":"compute:admin" + }, + { + "id":"101", + "name":"object-store:admin", + "tenantId":"t1000" + } + ], + "roles_links":[] + }, + "serviceCatalog":[{ + "name":"Nova", + "type":"compute", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1/t1000", + "internalURL":"https://compute.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://compute.north.host.com/v1/", + "versionList":"https://compute.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1.1/t1000", + "internalURL":"https://compute.north.internal/v1.1/t1000", + "region":"North", + "versionId":"1.1", + "versionInfo":"https://compute.north.host.com/v1.1/", + "versionList":"https://compute.north.host.com/" + } + ], + "endpoints_links":[] + }, + { + "name":"Swift", + "type":"object-store", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://storage.north.host.com/v1/t1000", + "internalURL":"https://storage.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://storage.north.host.com/v1/", + "versionList":"https://storage.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://storage.south.host.com/v1/t1000", + "internalURL":"https://storage.south.internal/v1/t1000", + "region":"South", + "versionId":"1", + "versionInfo":"https://storage.south.host.com/v1/", + "versionList":"https://storage.south.host.com/" + } + ] + }, + { + "name":"DNS-as-a-Service", + "type":"dnsextension:dns", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://dns.host.com/v2.0/t1000", + "versionId":"2.0", + "versionInfo":"https://dns.host.com/v2.0/", + "versionList":"https://dns.host.com/" + } + ] + } + ] + } + } + +Note the following about this response: + +#. There are two endpoints given to the Nova compute service. The only + difference between them is the version (1.0 vs. 1.1). This allows for code + written to look for the version 1.0 endpoint to still work even after the 1.1 + version is released. + +#. There are two endpoints for the Swift object-store service. The difference + between them is they are in different regions (North and South). + +#. Note the DNS service is global; it does not have a Region. Also, since DNS + is not a core OpenStack service, the endpoint type is "dnsextension:dns" + showing it is coming from an extension to the Keystone service. + +#. The Region, Tenant, and versionId are listed under the endpoint. You do not + (and should not) have to parse those out of the URL. In fact, they may not be + embedded in the URL if the service developer so chooses. + + +What do the fields in an Endpoint mean? +--------------------------------------- + +The schema definition for an endpoint is in endpoints.xsd under +keystone/content/common/xsd in the Keystone code repo. The fields are: + +id + A unique ID for the endpoint. + +type + The OpenStack-registered type (ex. 'compute', 'object-store', 'image service') + This can also be extended using the OpenStack Extension mechanism to support + non-core services. Extended services will be in the form ``extension:type`` + (e.g. ``dnsextension:dns``) + +name + This can be anything that the operator of OpenStack chooses. It could be a + brand or marketing name (ex. Rackspace Cloud Servers). + +region + This is a string that identifies the region where this endpoint exists. + Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or + 'Data Center 1', 'Data Center 2'. + The list of regions and what a region means is decided by the operator. The + spec treats them as opaque strings. + +publicURL + This is the URL to use to access that endpoint over the internet. + +internalURL + This is the URL to use to communicate between services. This is genenrally + a way to communicate between services over a high bandwidth, low latency, + unmetered (free, no bandwidth charges) network. An example would be if you + want to access a swift cluster from inside your Nova VMs and want to make + sure the communication stays local and does not go over a public network + and rack up your bandwidth charges. + +adminURL + This is the URL to use to administer the service. In Keystone, this URL + is only shown to users with the appropriate rights. + +tenantId + If an endpoint is specific to a tenant, the tenantId field identifies the + tenant that URL applies to. Some operators include the tenant in the + URLs for a service, while others may provide one endpoint and use some + other mechanism to identify the tenant. This field is therefore optional. + Having this field also means you do not have to parse the URL to identify + a tenant if the operator includes it in the URL. + +versionId + This identifies the version of the API contract that endpoint supports. + While many APIs include the version in the URL (ex: https://compute.host/v1), + this field allows you to identify the version without parsing the URL. It + therefore also allows operators and service developers to publish endpoints + that do not have versions embedded in the URL. + +versionInfo + This is the URL to call to get some information on the version. This returns + information in this format:: + + { + "version": { + "id": "v2.0", + "status": "CURRENT", + "updated": "2011-01-21T11:33:21-06:00", + "links": [ + { + "rel": "self", + "href": "http://identity.api.openstack.org/v2.0/" + }, { + "rel": "describedby", + "type": "application/pdf", + "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" + }, { + "rel": "describedby", + "type": "application/vnd.sun.wadl+xml", + "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" + } + ], + "media-types": [ + { + "base": "application/xml", + "type": "application/vnd.openstack.identity+xml;version=2.0" + }, { + "base": "application/json", + "type": "application/vnd.openstack.identity+json;version=2.0" + } + ] + } + } + +versionList + + This is the URL to call to find out which versions are supported at that + endpoint. The response is in this format:: + + { + "versions":[{ + "id":"v1.0", + "status":"DEPRECATED", + "updated":"2009-10-09T11:30:00Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.0/" + } + ] + }, + { + "id":"v1.1", + "status":"CURRENT", + "updated":"2010-12-12T18:30:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.1/" + } + ] + }, + { + "id":"v2.0", + "status":"BETA", + "updated":"2011-05-27T20:22:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v2.0/" + } + ] + } + ], + "versions_links":[] + } + + Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0. + It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA. + +What are Endpoint Templates? +---------------------------- + +Endpoint Templates are a way for an administrator to manage endpoints en masse. +They provide a way to define Endpoints that apply to many or all tenants +without having to a create each endpoint on each tenant manually. Without +Endpoint Templates, if I wanted to create Endpoints for each tenant in my +OpenStack deployment, I'd have to manually create a bunch of endpoints on +each tenant (probably when I created the tenant). And then I'd have to go change +them all whenever a service changed versions or I added a new service. + +To provide a simpler mechanism to manage endpoints on tenants, Keystone uses +Endpoint Templates. I can, for example, define a template with parametrized URLs +and set it's `global` to true and that will show up as an endpoint on all the tenants +I have. Here is an example: + +Define a global Endpoint Template:: + + $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1 + + The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global' + +This creates a global endpoint (global means it gets applied to all tenants automatically). + +Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example +authentication request for use against tenant 1:: + + $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens + +The response is:: + + { + "access": { + "serviceCatalog": [ + { + "endpoints": [ + { + "internalURL": "https://compute.north.example.local", + "publicURL": "https://compute.north.example.com/v1/1/", + "region": "North" + } + ], + "name": "nova", + "type": "compute" + } + ], + "token": { + "expires": "2012-02-05T00:00:00", + "id": "887665443383838", + "tenant": { + "id": "1", + "name": "customer-x" + } + }, + "user": { + "id": "1", + "name": "joeuser", + "roles": [ + { + "id": "3", + "name": "Member", + "tenantId": "1" + } + ] + } + } + } + +Notice the adminURL is not showing (this user is a regular user and does not +have rights to see the adminURL) and the tenant ID has been substituted in the +URL:: + + "publicURL": "https://compute.north.example.com/v1/1/", + +This endpoint will show up for all tenants. The OpenStack administrator does +not need to create the endpoint manually. + +.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). + + +What parameters can I use in a Template URL +------------------------------------------- + +Currently the only parameterization available is %tenant_id% which gets +substituted by the Tenant ID. + + +Endpoint Template Types: Global or not +-------------------------------------- + +When the global flag is set to true on an Endpoint Template, it means it should +be available to all tenants. Whenever someone authenticates to a tenant, they +will see the Endpoint generated by that template. + +When the global flag is not set, the template only shows up when it is added to +a tenant manually. To add an endpoint to a tenant manually, you must create +the Endpoint and supply the Endpoint Template ID: + +Create the Endpoint Template:: + + $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 + + Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. + +Find the Endpoint Template ID:: + + $ ./keystone-manage endpointTemplates list + + All EndpointTemplates + id service type region enabled is_global Public URL Admin URL + ------------------------------------------------------------------------------- + 15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp + 16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp + +Add the Endpoint to the tenant:: + + $ ./keystone-manage endpoint add customer-x 16 + +Now, when the user authenticates, they get the endpoint:: + + { + "internalURL": "https://compute.west.example.local", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West" + } + +Who can see the AdminURL? +------------------------- + +Users who have the Keystone `Admin` or `Service Admin` roles will see the +AdminURL when they authenticate or when they retrieve token information: + +Using an administrator token to authenticate, GET a client token's endpoints:: + + $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + + { + "endpoints": [ + { + "adminURL": "https://compute.west.example.corp", + "id": 6, + "internalURL": "https://compute.west.example.local", + "name": "nova", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West", + "tenantId": 1, + "type": "compute" + } + ], + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", + "rel": "next" + } + ] + } diff --git a/docs/source/old/extensions.rst b/docs/source/old/extensions.rst new file mode 100644 index 00000000..539bef39 --- /dev/null +++ b/docs/source/old/extensions.rst @@ -0,0 +1,183 @@ +.. + Copyright 2011 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. + +========== +Extensions +========== + +Extensions support adding features and functions to OpenStack APIs at any time, without prior +approval or waiting for a new API and release cycles. + +The extension framework is in development and documented in extensions_ and extensionspresentation_. + +This document describes the extensions included with Keystone, how to enable and disable them, +and briefly touches on how to write your own extensions. + +.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html +.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions + +Built-in Extensions +------------------- + +Keystone ships with a number of extensions found under the +``keystone/contib/extensions`` folder. + +The following built-in extensions are included: + +OS-KSADM + + This is an extensions that supports managing users, tenants, and roles + through the API. Without this extensions, the ony way to manage those + objects is through keystone-manage or directly in the underlying database. + + This is an Admin API extension only. + +OS-KSCATALOG + + This extensions supports managing Endpoints and prrovides the Endpoint + Template mechanism for managing bulk endpoints. + + This is an Admin API extension only. + +OS-EC2 + + This extension adds support for EC2 credentials. + + This is an Admin and Service API extension. + +RAX-GRP + + This extension adds functionality the enables groups. + + This is an Admin and Service API extension. + +RAX-KEY + + This extensions adds support for authentication with an API Key (the core + Keystone API only supports username/password credentials) + + This is an Admin and Service API extension. + +HP-IDM + + This extension adds capability to filter roles with optional service IDs + for token validation to mitigate security risks with role name conflicts. + See https://bugs.launchpad.net/keystone/+bug/890411 for more details. + + This is an Admin API extension. Applicable to validate token (GET) + and check token (HEAD) APIs only. + +OS-KSVALIDATE + + This extensions supports admin calls to /tokens without having to specify + the token ID in the URL. Instead, the ID is supplied in a header called + X-Subject-Token. This is provided as an alternative to address any security + concerns that arise when token IDs are passed as part of the URL which is + often (and by default) logged to insecure media. + + This is an Admin API extension only. + +.. note:: + + The included extensions are in the process of being rewritten. Currently + osksadm, oskscatalog, hpidm, and osksvalidate work with this new + extensions design. + + +Enabling & Disabling Extensions +------------------------------- + +The Keystone conf file has a property called extensions. This property holds +the list of supported extensions that you want enabled. If you want to +add/remove an extension from being supported, add/remove the extension key +from this property. The key is the name of the folder of the extension +under the keystone/contrib/extensions folder. + +.. note:: + + If you want to load different extensions in the service API than the Admin API + you need to use different config files. + +Creating New Extensions +----------------------- + +#. **Adopt a unique organization abbreviation.** + + This prefix should uniquely identify your organization within the community. + The goal is to avoid schema and resource collisions with similiar extensions. + (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) + +#. **Adopt a unique extension abbreviation.** + + Select an abbreviation to identify your extension, and append to + your organization prefix using a hyphen (``-``), by convention + (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). + + This combination is referred to as your extension's prefix. + +#. **Determine the scope of your extension.** + + Extensions can enhance the Admin API, Service API or both. + +#. **Create a new module.** + + Create a module to isolate your namespace based on the extension prefix + you selected:: + + keystone/contrib/extensions/admin + + ... and/or:: + + keystone/contrib/extensions/service/ + + ... based on which API you are enhancing. + + .. note:: + + In the future, we will support loading external extensions. + +#. Add static extension files for JSON (``*.json``) and XML + (``*.xml``) to the new extension module. + + Refer to `Service Guide `_ + `Sample extension XML `_ + `Sample extension JSON `_ for the the content and structure. + +#. If your extension is adding additional methods override the base class + ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. + +#. **Document your work.** + + Provide documentation to support your extension. + + Extensions documentation, WADL, and XSD files can be stored in the + ``keystone/content`` folder. + +#. Add your extension name to the list of supported extensions in The + ``keystone.conf`` file. + +Which extensions are enabled? +----------------------------- + +Discover which extensions are available (service API):: + + curl http://localhost:5000/v2.0/extensions + +... or (admin API):: + + curl http://localhost:35357/v2.0/extensions + +The response will list the extensions available. diff --git a/docs/source/old/middleware.rst b/docs/source/old/middleware.rst new file mode 100644 index 00000000..69506ee2 --- /dev/null +++ b/docs/source/old/middleware.rst @@ -0,0 +1,169 @@ +.. + Copyright 2011 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 +========== + +The Keystone middleware sits in front of an OpenStack service and handles authenticating +incoming requests. The middleware was designed according to `this spec`. + +The middleware is found in source under Keystone/middleware. + +The middleware supports two interfaces; WSGI and REST/HTTP. + +.. _`this spec`: http://wiki.openstack.org/openstack-authn + +REST & HTTP API +=============== + +If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per +HTTP standards, it will also return a WWW-Authenticate header informing the caller +of what protocols are supported. For Keystone authentication, the response syntax will be:: + + WWW-Authenticate: Keystone uri="url to Keystone server" + +The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token. + +The token is passed in using ther X-Auth-Token header. + +WSGI API (Headers) +================== + +Upon successful authentication the middleware sends the following +headers to the downstream WSGI app: + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +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-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-Roles + The roles associated with that user + + +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 = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 + +*The required configuration entries are:* + +auth_host + The IP address or DNS name of the Keystone server + +auth_port + The TCP/IP port of the Keystone server + +auth_protocol + The protocol of the Keystone server ('http' or 'https') + +auth_uri + The externally accessible URL of the Keystone server. This will be where unauthenticated + clients are redirected to. This is in the form of a URL. For example, if they make an + unauthenticated call, they get this response:: + + HTTP/1.1 401 Unauthorized + Www-Authenticate: Keystone uri='https://auth.example.com/' + Content-Length: 381 + + In this case, the auth_uri setting is set to https://auth.example.com/ + +admin_token + This is the long-lived token issued to the service to authenticate itself when calling + Keystone. See :doc:`configuration` for more information on setting this up. + + +*Optional parameters are:* + +delay_auth_decision + Whether the middleware should reject invalid or unauthenticated calls directly or not. If not, + it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS + header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the + service can then decide if it wants to honor the call or not. This is useful if the service offers + some resources publicly, for example. + +auth_timeout + The amount of time to wait before timing out a call to Keystone (in seconds) + +memcache_hosts + This is used to point to a memcached server (in ip:port format). If supplied, + the middleware will cache tokens and data retrieved from Keystone in memcached + to minimize calls made to Keystone and optimize performance. + +.. warning:: + Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone, + the service will not know and will continue to honor the token as it has them stored in memcached. + Also note that tokens and data stored in memcached are not encrypted. The memcached server must + be trusted and on a secure network. + + +*Parameters needed in a distributed topology.* In this configuration, the middleware is running +on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture` +for details on different deployment topologies): + +service_host + The IP address or DNS name of the location of the service (since it is remote + and not automatically down the WSGI chain) + +service_port + The TCP/IP port of the remote service. + +service_protocol + The protocol of the service ('http' or 'https') + +service_pass + The basic auth password used to authenticate to the service (so the service + knows the call is coming from a server that has validated the token and not from + an untrusted source or spoofer) + +service_timeout + The amount of time to wait for the service to respond before timing out. diff --git a/docs/source/old/middleware_architecture.rst b/docs/source/old/middleware_architecture.rst new file mode 100644 index 00000000..a8c38f3c --- /dev/null +++ b/docs/source/old/middleware_architecture.rst @@ -0,0 +1,529 @@ +.. + Copyright 2011 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 multiple authentication protocols +in a pluggable manner in OpenStack. By providing support for authentication via +pluggable authentication components, this architecture allows OpenStack +services to be integrated easily into existing deployment environments. It also +provides a path by which to implement support for emerging authentication +standards such as OAUTH. + +Rationale and Goals +=================== + +Keystone is the Identity service for OpenStack. To support the easy integrating +of OpenStack with existing authentication and identity management systems, +Keystone supports talking to multiple backends like LDAP. +And to support different deployment needs, it can support multiple +authentication protocols via pluggable 'authentication components' implemented +as WSGI middleware. + +In this document, we describe the responsibilities of the authentication +middleware. We describe how these interact with underlying OpenStack services +and how existing services can be modified to take advantage of pluggable +authentication. The goal is to allow OpenStack services to be integrated easily +into existing deployment environments and to provide a path by which to +implement support for emerging authentication standards such as OAUTH. + +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. + +At a high level, an authentication component is simply a reverse proxy that +intercepts HTTP calls from clients. Once it has verified a user's identity, the +authentication component extends the call with information about the current +user and forwards the request to the OpenStack service. Otherwise, if a user's +identity is not verified, the message is rejected before it gets to the +service. This is illustrated in :ref:`authComponent`. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +Authentication components may operate in 'delegated mode'. In this mode, the +decision reject an unauthenticated client is delegated to the OpenStack +service. Delegated mode is 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. Note that it is always the responsibility +of the Authentication Component to transmit reject messages 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) + +In this architecture, we define interactions between the authentication component +and the OpenStack service. Interactions between the client and the +authentication component are defined only for exceptional cases. For example, +we define the message that should be returned when the OpenStack service is +down. Other interactions, however, are defined by the underlying authentication +protocol and the OpenStack service and are considered out of scope. + +.. _deployStrategies: + +Deployment Strategies +===================== + +An authentication component may be integrated directly into the service +implementation, or it may be deployed separately as an HTTP reverse proxy. This +is illustrated in :ref:`deployment`, showing both approaches to +authentication, labeled Option (a) and Option (b). + +.. _deployment: + +Authentication Component Deployments Options +-------------------------------------------- + +Figure 3. Authentication Component Deployments Options + +.. image:: images/images_layouts.svg + :width: 100% + :height: 180 + :alt: Authentication Component Deployments Options + +In Option (a), the component is integrated into the service implementation. In +this case, communication between the authentication component and the service +can be efficiently implemented via a method call. In Option (b), the component +is deployed separately and communication between the service and the component +involves an HTTP request. In both cases, unauthenticated requests are filtered +before they reach the service. + +Each approach offers some benefits. Option (a) offers low latency and ease of +initial implementation, making it possibly most appropriate as a starting point +for simple configurations. Option (b) offers several key advantages that may be +of particular value in complex and dynamic configurations. It offers the +ability to scale horizontally in cases where authentication is computationally +expensive, such as when verifying digital signatures. Option (b) also allows +authentication components to be written in different programming languages. +Finally, Option (b) allows multiple authentication components to be deployed in +front of the same service. + +OpenStack services can support both embedded (Option (a)) and external (Option +(b)) deployment strategies. Individual authentication components should support +either strategy or they |may| support both strategies. In order to support +option (a), authentication components written in the Python programming +language should be written as WSGI middleware components (in accordance with +the Web Server Gateway Interface (WSGI) standard [PEP-333]_. + +Additionally, services should support the ability to swap between different +embedded or external authentication components via configuration options. + +Exchanging User Information +=========================== + +If a request is successfully authenticated, the authentication component must +extend the request by adding an ``X-Authorization`` header. The header |must| +be formatted as illustrated in :ref:`xAuthHeader`. + +.. _xAuthHeader: + +X-Authorization Header +---------------------- + +Example 1. X-Authorization Header:: + + X-Authorization: Proxy JoeUser + +Here, `Proxy` denotes that the authentication occurred via a proxy (in this +case authentication component) and ''JoeUser'' is the name of the user who +issued the request. + +.. note: + + We considered using an ``Authorization`` header rather than an + ``X-Authorization``, thereby following normal HTTP semantics. There are some + cases, however, where multiple ``Authorization`` headers need to be transmitted + in a single request. We want to assure ourselves that this will not break + common clients before we recommend the approach. + +Authentication components |may| extend the request with additional +information. For example, an authentication system may add additional headers +or modify the target URI to pass authentication information to the back-end +service. Additionally, an authentication component |may| strip sensitive +information — a plain text password, for example — from the request. That said, +an authentication component |should| pass the majority of the request +unmodified. + +Reverse Proxy Authentication +---------------------------- + +An OpenStack service |should| verify that it is receiving requests from a +trusted authentication component. This is particularly important in cases where +the authentication component and the OpenStack service are deployed separately. +In order to trust incoming requests, the OpenStack service should therefore +authenticate the authentication component. To avoid confusion, we call this +'reverse proxy authentication', since in this case the authentication +component is acting as an HTTP reverse proxy. + +Any HTTP-based authentication scheme may be used for reverse proxy +authentication; however, all OpenStack services and all authentication +components |must| support HTTP Basic Authentication as defined in +[RFC-2617]_. + +Whether or not reverse proxy authentication is required is strictly a +deployment concern. For example, an operations team may opt to utilize firewall +rules instead of an authentication protocol to verify the integrity of incoming +request. Because of this, both OpenStack services and authentication components +|must| also allow for unauthenticated communication. + +In cases where reverse proxy authentication is used, the authorization +component may receive an HTTP 401 authentication error or an HTTP 403 +authorization error. These errors indicate that the component does not have +access to the underlying OpenStack service. The authentication component +|must not| return these errors to the client application. Instead, the +component |must| return a 500 internal error. This is illustrated in +:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component +|should| format the errors in a manner that does not break the service +contract defined by the OpenStack service. :ref:`proxyAuthDelegated` +illustrates proxy authorization in delegated mode. Delegated mode is discussed +in detail in the next section. + +.. _proxyAuth: + +Reverse Proxy Authentication +---------------------------- + +Figure 4. Reverse Proxy Authentication + +.. image:: images/graphs_proxyAuth.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication + +.. _proxyAuthDelegated: + +Reverse Proxy Authentication (Delegated Mode) +--------------------------------------------- + +Figure 5. Reverse Proxy Authentication (Delegated Mode) + +.. image:: images/graphs_delegate_forbiden_proxy.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication (Delegated Mode) + +Delegated Mode +============== +In some cases, the decision to reject an unauthenticated request should be +delegated to the OpenStack service. An unauthenticated request may be +appropriate in cases when anonymous access is allowed. In order to support +these cases, an authentication component may be placed in Delegated Mode. In +this mode, the component forwards requests to the OpenStack service when the +client's identity has been confirmed or is indeterminate — that is when +credentials are missing. The authentication component directly rejects requests +with invalid credentials. Authentication components |must| extend the +request by adding an `X-Identity-Status` header. The identity status header +|must| contain one of the following values: + +Identity Status Values +---------------------- + +Confirmed + A `confirmed` value indicates that valid credentials were sent and identity + has been confirmed. The service can trust that the request has been sent on + behalf of the user specified in the `X-Authorization` header. + +Indeterminate + An `indeterminate` value indicates that no credentials were sent and + identity has not been confirmed. In this case, the service will receive an + `X-Authorization` header with no user entry as illustrated in + :ref:`xauth-header-indeterminate`. + +.. _xauth-header-indeterminate: + +Indeterminate Identity Headers +------------------------------ + +Example 2. Indeterminate Identity Headers:: + + X-Identity-Status: Indeterminate + X-Authorization: Proxy + +Services |may| reject a delegated request by issuing an HTTP 401 +authentication error or an HTTP 403 authorization error. These responses +|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as +illustrated in :ref:`unauthHeaders`. + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +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-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-Roles + The roles associated with that user + +.. _unauthHeaders: + +Delegated WWW-Authenticate Header +--------------------------------- + +:: + + WWW-Authenticate: Delegated + +It is important to note that the actual reject message will likely be modified +by the authentication component in order to comply with the authentication +scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and +:ref:`delegateRejectOAuth` below. + +.. _delegateRejectBasic: + +Delegated Reject Basic Auth +--------------------------- + +.. image:: images/graphs_delegate_reject_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Basic Auth + +.. _delegateRejectOAuth: + +Delegated Reject OAuth +---------------------- + +.. image:: images/graphs_delegate_reject_oauth.svg + :width: 100% + :height: 180 + :alt: Delegated Reject OAuth + +The presence of the `WWW-Authenticate` header with a value of `Delegated` +distinguishes a client authentication/authorization failure from a component +failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In +:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. +In :ref:`proxyAuthDelegated`, it is the authentication component itself which is +unauthorized. + +.. _delegateForbidden: + +Delegated Reject Forbidden +-------------------------- + +Figure 8. Delegated Reject Forbidden + +.. image:: images/graphs_delegate_forbiden_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Forbidden + +Authentication components |must| support both delegated and undelegated +(standard) modes. Delegated mode |should| be configured via a configuration +option. Delegated mode |should| be disabled by default. + +OpenStack services are not required to support delegated mode. If a service +does not support delegated mode, it |must| respond with a 501 not implemented +error and an `WWW-Authenticate` header with a value of `Delegated`. The +authentication component |must not| return the error to the client +application. Instead, the component |must| return a 500 internal error; this is +illustrated in :ref:`delegateUnimplemented`. The component |should| +format the error in a manner that does not break the service contract defined +by the OpenStack service. The component should also log the error such that it +that will inform operators of the misconfiguration. + +.. _delegateUnimplemented: + +Unimplemented Delegated Mode +---------------------------- + +.. image:: images/graphs_delegate_unimplemented.svg + :width: 100% + :height: 180 + :alt: Unimplemented Delegated Mode + +Handling Direct Client Connections +================================== + +Requests from the authentication component to an OpenStack service |must| +contain an ``X-Authorization`` header. If the header is missing, and reverse +proxy authentication fails or is switched off, the OpenStack service |may| +assume that the request is coming directly from a client application. In this +case, the OpenStack service |must| redirect the request to the authentication +component by issuing an HTTP 305 User Proxy redirect. This is illustrated in +:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header +specifying the authentication component's URL as shown in :ref:`redirect-response`. + +.. _redirect: + +Auth Component Redirect +----------------------- + +.. image:: images/graphs_305.svg + :width: 100% + :height: 280 + :alt: Auth Component Redirect + +.. _redirect-response: + +Auth Component Redirect Response +-------------------------------- + +:: + + HTTP/1.1 305 Use Proxy + Date: Thu, 28 Oct 2011 07:41:16 GMT + Location: http://sample.auth.openstack.com/path/to/resource + +Using Multiple Authentication Components +======================================== + +There are some use cases when a service provider might want to consider using +multiple authentication components for different purposes. For instance, a +service provider may have one authentication scheme to authenticate the users +of the service and another one to authenticate the administrators or operations +personnel that maintain the service. For such scenarios, we propose using a +mapper as illustrated in :ref:`multiAuth`. + +.. _multiAuth: + +Multiple Authentication Components +---------------------------------- + +.. image:: images/graphs_mapper.svg + :width: 100% + :height: 320 + :alt: Multiple Authentication Components + +At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls +from clients and routes the request to the appropriate authentication +component. A mapper can make the routing decisions based on a number of routing +rules that map a resource to a specific authentication component. For example, +a request URI may determine whether a call should be authenticated via one +authentication component or another. + +Note that neither the authentication component nor the OpenStack service need +be aware of the mapper. Any external authentication component can be used +alongside others. Mappers may provide a means by which to offer support for +anonymous or guest access to a subset of service resources. A mapper may be +implemented via a traditional reverse proxy server such as Pound or Zeus. + +The Default Component +===================== + +Individual services |must| be distributed with a simple integrated +authentication component by default. Providing such a component lowers barriers +to the deployment of individual services. This is especially important to] +developers who may want to deploy OpenStack services on their own machines. +Also, since there is no direct dependency on an external authentication system, +OpenStack services can be deployed individually, without the need to stand up +and configure additional services. Finally, having a standard authentication +component that all services share promotes a separation of concerns. That is, +as a community we are explicitly stating that services should not develop their +own authentication mechanisms. Additional authentication components may be +developed, of course, but these components should not be intimately coupled to +any one particular service. + +As discussed in :ref:`deployStrategies`, an authentication component may be +integrated directly into the service implementation (Option (a)), or it may be +deployed separately as an HTTP reverse proxy (Option (b)). The default +component should be implemented to support Option (a) and services should +maintain support for Option (b). One way to achieve this is to provide a +method that allows the disabling of the default authentication component via +configuration. This is illustrated in :ref:`both`. Here, requests are +sent directly to the OpenStack service when the default authentication +component is disabled. + +We will discuss the design of the default component in an upcoming blueprint. + +.. _both: + +Disabled Embedded Component +--------------------------- + +.. image:: images/graphs_both.svg + :width: 100% + :height: 250 + :alt: Disabled Embedded Component + +Questions and Answers +===================== + +#. Why do authentication components send reject messages? Why not have + OpenStack services reject requests themselves? + + The content and format of an authentication failed message is determined by + the authentication scheme (or protocol). For the service to respond + appropriately, it would have to be aware of the authentication scheme in + which it participates; this defeats the purpose of pluggable authentication + components. + +#. Why require support for deploying authentication components in separate + nodes? + + The deployment strategy is very flexible. It allows for authentication + components to be horizontally scalable. It allows for components to be written + in different languages. Finally, it allows different authentication components + to be deployed simultaneously as described above. + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. + +.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. + P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest + Access Authentication.'' http://tools.ietf.org/html/rfc2617. + +.. |must| replace:: must must +.. |should| replace:: should should +.. |may| replace:: may may +.. |must not| replace:: "must not" "must not" + diff --git a/docs/source/old/migration.rst b/docs/source/old/migration.rst new file mode 100644 index 00000000..460d980b --- /dev/null +++ b/docs/source/old/migration.rst @@ -0,0 +1,126 @@ +=================== +Database Migrations +=================== + +Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage +migrations. + +Migrations are tracked using a metadata table (``migrate_version``), which +allows keystone to compare the state of your database to the state it +expects, and to move between versions. + +.. WARNING:: + + Backup your database before applying migrations. Migrations may + attempt to modify both your schema and data, and could result in data + loss. + + Always review the behavior of migrations in a staging environment + before applying them in production. + +Getting Started +=============== + +Your initial approach to migrations should depend on whether you have an +empty database or a schema full of data. + +Starting with an empty database +------------------------------- + +If you have an empty database for keystone to work with, you can simply +run:: + + $ ./bin/keystone-manage database sync + +This command will initialize your metadata table, and run through all the +schema & data migrations necessary to bring your database in sync with +keystone. That's it! + +Starting with an existing database +---------------------------------- + +Place an existing database under version control to enable migration +support:: + + $ ./bin/keystone-manage database version_control + +This command simply creates a ``migrate_version`` table, set at +``version_number`` 0, which indicates that no migrations have been applied. + +If you are starting with an existing schema, you can jump to a specific +schema version without performing migrations using the ``database goto`` +command. For example, if you're starting from a diablo-compatible +database, set your current database ``version_number`` to ``1`` using:: + + $ ./bin/keystone-manage database goto + +Determine your appropriate database ``version_number`` by referencing the +following table: + + +------------+-------------+ + | Release | ``version`` | + +============+=============+ + | pre-diablo | (see below) | + +------------+-------------+ + | diablo | 1 | + +------------+-------------+ + | essex-m1 | 3 | + +------------+-------------+ + | essex-m2 | 4 | + +------------+-------------+ + +From there, you can upgrade normally (see :ref:`upgrading`). + +Starting with a pre-diablo database (cactus) +-------------------------------------------- + +You'll need to manually migrate your database to a diablo-compatible +schema, and continue forward from there (if desired) using migrations. + +.. _upgrading: + +Upgrading & Downgrading +======================= + +.. note:: + + Attempting to start keystone with an outdated schema will cause + keystone to abort, to avoid corrupting your data. + +Upgrade to the latest version automatically:: + + $ ./bin/keystone-manage database sync + +Check your current schema version:: + + $ ./bin/keystone-manage database version + +Jump to a specific version without performing migrations:: + + $ ./bin/keystone-manage database goto + +Upgrade to a specific version:: + + $ ./bin/keystone-manage database upgrade + +Downgrade to a specific version (will likely result in data loss!):: + + $ ./bin/keystone-manage database downgrade + +Opting Out of Migrations +======================== + +If you don't want to use migrations (e.g. if you want to manage your +schema manually), keystone will complain in your logs on startup, but +won't actually stop you from doing so. + +It's recommended that you use migrations to get up and running, but if +you want to manage migrations manually after that, simply drop the +``migrate_version`` table:: + + DROP TABLE migrate_version; + +Useful Links +============ + +Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/docs/source/old/nova-api-paste.rst b/docs/source/old/nova-api-paste.rst new file mode 100644 index 00000000..586bac72 --- /dev/null +++ b/docs/source/old/nova-api-paste.rst @@ -0,0 +1,142 @@ +.. + Copyright 2011 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. + +nova-api-paste example +====================== +:: + + ####### + # EC2 # + ####### + + [composite:ec2] + use = egg:Paste#urlmap + /: ec2versions + /services/Cloud: ec2cloud + /services/Admin: ec2admin + /latest: ec2metadata + /2007-01-19: ec2metadata + /2007-03-01: ec2metadata + /2007-08-29: ec2metadata + /2007-10-10: ec2metadata + /2007-12-15: ec2metadata + /2008-02-01: ec2metadata + /2008-09-01: ec2metadata + /2009-04-04: ec2metadata + /1.0: ec2metadata + + [pipeline:ec2cloud] + pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor + + [pipeline:ec2admin] + pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor + + [pipeline:ec2metadata] + pipeline = logrequest ec2md + + [pipeline:ec2versions] + pipeline = logrequest ec2ver + + [filter:logrequest] + paste.filter_factory = nova.api.ec2:RequestLogging.factory + + [filter:ec2lockout] + paste.filter_factory = nova.api.ec2:Lockout.factory + + [filter:totoken] + paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory + + [filter:ec2noauth] + paste.filter_factory = nova.api.ec2:NoAuth.factory + + [filter:authenticate] + paste.filter_factory = nova.api.ec2:Authenticate.factory + + [filter:cloudrequest] + controller = nova.api.ec2.cloud.CloudController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:adminrequest] + controller = nova.api.ec2.admin.AdminController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:authorizer] + paste.filter_factory = nova.api.ec2:Authorizer.factory + + [app:ec2executor] + paste.app_factory = nova.api.ec2:Executor.factory + + [app:ec2ver] + paste.app_factory = nova.api.ec2:Versions.factory + + [app:ec2md] + paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory + + ############# + # Openstack # + ############# + + [composite:osapi] + use = egg:Paste#urlmap + /: osversions + /v1.1: openstackapi + + [pipeline:openstackapi] + pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp + + [filter:faultwrap] + paste.filter_factory = nova.api.openstack:FaultWrapper.factory + + [filter:auth] + paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory + + [filter:noauth] + paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory + + [filter:ratelimit] + paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory + + [filter:extensions] + paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory + + [app:osapiapp] + paste.app_factory = nova.api.openstack:APIRouter.factory + + [pipeline:osversions] + pipeline = faultwrap osversionapp + + [app:osversionapp] + paste.app_factory = nova.api.openstack.versions:Versions.factory + + ########## + # Shared # + ########## + + [filter:keystonecontext] + paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory + + [filter:authtoken] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + service_protocol = http + service_host = 127.0.0.1 + service_port = 5000 + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/old/releases.rst b/docs/source/old/releases.rst new file mode 100644 index 00000000..a4b698d7 --- /dev/null +++ b/docs/source/old/releases.rst @@ -0,0 +1,36 @@ +============= +Release notes +============= + + +E3 (January 26, 2012) +========================================== +* Contract compliance: version response and ATOM, 300 multiple choice +* Global endpoints returned for unscoped calls +* adminUrl only shown to admin clients +* Endpoints have unique ID +* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) +* Default tenant scope optionally returned when authenticating +* Vary header returned for caching proxies + +* Portable identifiers: modifiable, string identifiers in database backend +* Much improved keystone-manage command (see --help and docs) +* OS-KSVALIDATE extension to support not passing tokens in URL +* OS-KSEC2 and OS-KSS3 extensions respond on /tokens +* HP-IDM extension to filter roles to a given service ID +* Additional caching options in middleware (memcache and swift cache) + +* Enhanced configuration management (in line with other OpenStack projects) +* Additional logging +* Enhanced tracer tool (-t or --trace-calls) + +See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 + + +E2 (December 15, 2011) +======================== +* D5 compatibility middleware +* Database versioning +* Much more documentation: http://keystone.openstack.org + +See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/docs/source/old/services.rst b/docs/source/old/services.rst new file mode 100644 index 00000000..d1c33381 --- /dev/null +++ b/docs/source/old/services.rst @@ -0,0 +1,92 @@ +.. + Copyright 2011 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. + +================ +Services +================ + +.. toctree:: + :maxdepth: 1 + + +What are services? +================== + +Keystone includes service registry and service catalog functionality which it +uses to respond to client authentication requests with information useful to +clients in locating the list of available services they can access. + +The Service entity in Keystone represents an OpenStack service that is integrated +with Keystone. The Service entity is also used as a reference from roles, endpoints, +and endpoint templates. + +Keystone also includes an authorization mechanism to allow a service to own +its own roles and endpoints and prevent other services from changing or +modifying them. + +Who can create services? +======================== + +Any user with the Admin or Service Admin roles in Keystone may create services. + +How are services created? +========================= + +Services can be created using ``keystone-manage`` or through the REST API using +the OS-KSADM extension calls. + +Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: + + $ keystone-manage add service compute nova 'This is a sample compute service' + +Using the REST API (see `extensions dev guide `_ for details):: + + $ curl -H "Content-type: application/json" -X POST -d '{ + "OS-KSADM:service": { + "name": "nova", + "type": "compute", + "description": "This is a sample compute service" + } + }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ + +How is service ownership determined? +==================================== + +Currently, the way to assign ownership to a service is to provide the owner's +user id in the keystone-manage add command:: + + $ keystone-manage add service nova compute 'This is a sample compute service' joeuser + +This will assign ownership to the new service to joeuser. + +When a service has an owner, then only that owner (or a global Admin) can create and manage +roles that start with that service name (ex: "nova:admin") and manage endpoints +and endpoint templates associated with that service. + +Listing services +================ + +Using ``keystone-manage``, the list of services and their owners can be listed:: + + $ keystone-manage service list + + id name type owner_id description + ------------------------------------------------------------------------------- + 1 compute nova joeuser This is a sample compute service + +Using the REST API, call ``GET /v2.0/OS-KSADM/services`` + +.. note: The rest API does not yet support service ownership diff --git a/docs/source/old/ssl.rst b/docs/source/old/ssl.rst new file mode 100644 index 00000000..839e951e --- /dev/null +++ b/docs/source/old/ssl.rst @@ -0,0 +1,118 @@ +.. + Copyright 2011 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. + +=========================== +x.509 Client Authentication +=========================== + +Purpose +======= + +Allows the Keystone middleware to authenticate itself with the Keystone server +via an x.509 client certificate. Both Service API and Admin API may be secured +with this feature. + +Certificates +============ + +The following types of certificates are required. A set of certficates is provided +in the examples/ssl directory with the Keystone distribution for testing. Here +is the description of each of them and their purpose: + +ca.pem + Certificate Authority chain to validate against. + +keystone.pem + Public certificate for Keystone server. + +middleware-key.pem + Public and private certificate for Keystone middleware. + +cakey.pem + Private key for the CA. + +keystonekey.pem + Private key for the Keystone server. + +Note that you may choose whatever names you want for these certificates, or combine +the public/private keys in the same file if you wish. These certificates are just +provided as an example. + +Configuration +============= + +By default, the Keystone server does not use SSL. To enable SSL with client authentication, +modify the etc/keystone.conf file accordingly: + +1. To enable SSL for Service API:: + + service_ssl = True + +2. To enable SSL for Admin API:: + + admin_ssl = True + +3. To enable SSL client authentication:: + + cert_required = True + +4. Set the location of the Keystone certificate file (example):: + + certfile = /etc/keystone/ca/certs/keystone.pem + +5. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/private/keystonekey.pem + +6. Set the location of the CA chain:: + + ca_certs = /etc/keystone/ca/certs/ca.pem + +Middleware +========== + +Add the following to your middleware configuration to support x.509 client authentication. +If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters +in steps 3) and 4) may be commented out. + +1. Specify 'https' as the auth_protocol:: + + auth_protocol = https + +2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured + for SSL:: + + auth_uri = https://localhost:5000/ + +3. Set the location of the middleware certificate file (example):: + + certfile = /etc/keystone/ca/certs/middleware-key.pem + +4. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/certs/middleware-key.pem + +For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example +service in the examples/echo directory. + +Testing +======= + +You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory +and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with +the path to the client certificate:: + + python echo_client.py -s diff --git a/docs/source/releases.rst b/docs/source/releases.rst deleted file mode 100644 index a4b698d7..00000000 --- a/docs/source/releases.rst +++ /dev/null @@ -1,36 +0,0 @@ -============= -Release notes -============= - - -E3 (January 26, 2012) -========================================== -* Contract compliance: version response and ATOM, 300 multiple choice -* Global endpoints returned for unscoped calls -* adminUrl only shown to admin clients -* Endpoints have unique ID -* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) -* Default tenant scope optionally returned when authenticating -* Vary header returned for caching proxies - -* Portable identifiers: modifiable, string identifiers in database backend -* Much improved keystone-manage command (see --help and docs) -* OS-KSVALIDATE extension to support not passing tokens in URL -* OS-KSEC2 and OS-KSS3 extensions respond on /tokens -* HP-IDM extension to filter roles to a given service ID -* Additional caching options in middleware (memcache and swift cache) - -* Enhanced configuration management (in line with other OpenStack projects) -* Additional logging -* Enhanced tracer tool (-t or --trace-calls) - -See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 - - -E2 (December 15, 2011) -======================== -* D5 compatibility middleware -* Database versioning -* Much more documentation: http://keystone.openstack.org - -See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/docs/source/serviceAPI_curl_examples.rst b/docs/source/serviceAPI_curl_examples.rst deleted file mode 100644 index d05afc9f..00000000 --- a/docs/source/serviceAPI_curl_examples.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. - Copyright 2011 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. - -=============================== -Service API Examples Using Curl -=============================== - -The service API is defined to be a subset of the Admin API and, by -default, runs on port 5000. - -GET / -===== - -This call is identical to that documented for the Admin API, except -that it uses port 5000, instead of port 35357, by default:: - - $ curl http://0.0.0.0:5000 - -or:: - - $ curl http://0.0.0.0:5000/v2.0/ - -See the `Admin API Examples Using Curl`_ for more info. - -.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html - -GET /extensions -=============== - -This call is identical to that documented for the Admin API. - -POST /tokens -============ - -This call is identical to that documented for the Admin API. - -GET /tenants -============ - -List all of the tenants your token can access:: - - $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants - -Returns:: - - { - "tenants_links": [], - "tenants": [ - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } diff --git a/docs/source/services.rst b/docs/source/services.rst deleted file mode 100644 index d1c33381..00000000 --- a/docs/source/services.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. - Copyright 2011 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. - -================ -Services -================ - -.. toctree:: - :maxdepth: 1 - - -What are services? -================== - -Keystone includes service registry and service catalog functionality which it -uses to respond to client authentication requests with information useful to -clients in locating the list of available services they can access. - -The Service entity in Keystone represents an OpenStack service that is integrated -with Keystone. The Service entity is also used as a reference from roles, endpoints, -and endpoint templates. - -Keystone also includes an authorization mechanism to allow a service to own -its own roles and endpoints and prevent other services from changing or -modifying them. - -Who can create services? -======================== - -Any user with the Admin or Service Admin roles in Keystone may create services. - -How are services created? -========================= - -Services can be created using ``keystone-manage`` or through the REST API using -the OS-KSADM extension calls. - -Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: - - $ keystone-manage add service compute nova 'This is a sample compute service' - -Using the REST API (see `extensions dev guide `_ for details):: - - $ curl -H "Content-type: application/json" -X POST -d '{ - "OS-KSADM:service": { - "name": "nova", - "type": "compute", - "description": "This is a sample compute service" - } - }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ - -How is service ownership determined? -==================================== - -Currently, the way to assign ownership to a service is to provide the owner's -user id in the keystone-manage add command:: - - $ keystone-manage add service nova compute 'This is a sample compute service' joeuser - -This will assign ownership to the new service to joeuser. - -When a service has an owner, then only that owner (or a global Admin) can create and manage -roles that start with that service name (ex: "nova:admin") and manage endpoints -and endpoint templates associated with that service. - -Listing services -================ - -Using ``keystone-manage``, the list of services and their owners can be listed:: - - $ keystone-manage service list - - id name type owner_id description - ------------------------------------------------------------------------------- - 1 compute nova joeuser This is a sample compute service - -Using the REST API, call ``GET /v2.0/OS-KSADM/services`` - -.. note: The rest API does not yet support service ownership diff --git a/docs/source/ssl.rst b/docs/source/ssl.rst deleted file mode 100644 index 839e951e..00000000 --- a/docs/source/ssl.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. - Copyright 2011 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. - -=========================== -x.509 Client Authentication -=========================== - -Purpose -======= - -Allows the Keystone middleware to authenticate itself with the Keystone server -via an x.509 client certificate. Both Service API and Admin API may be secured -with this feature. - -Certificates -============ - -The following types of certificates are required. A set of certficates is provided -in the examples/ssl directory with the Keystone distribution for testing. Here -is the description of each of them and their purpose: - -ca.pem - Certificate Authority chain to validate against. - -keystone.pem - Public certificate for Keystone server. - -middleware-key.pem - Public and private certificate for Keystone middleware. - -cakey.pem - Private key for the CA. - -keystonekey.pem - Private key for the Keystone server. - -Note that you may choose whatever names you want for these certificates, or combine -the public/private keys in the same file if you wish. These certificates are just -provided as an example. - -Configuration -============= - -By default, the Keystone server does not use SSL. To enable SSL with client authentication, -modify the etc/keystone.conf file accordingly: - -1. To enable SSL for Service API:: - - service_ssl = True - -2. To enable SSL for Admin API:: - - admin_ssl = True - -3. To enable SSL client authentication:: - - cert_required = True - -4. Set the location of the Keystone certificate file (example):: - - certfile = /etc/keystone/ca/certs/keystone.pem - -5. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/private/keystonekey.pem - -6. Set the location of the CA chain:: - - ca_certs = /etc/keystone/ca/certs/ca.pem - -Middleware -========== - -Add the following to your middleware configuration to support x.509 client authentication. -If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters -in steps 3) and 4) may be commented out. - -1. Specify 'https' as the auth_protocol:: - - auth_protocol = https - -2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured - for SSL:: - - auth_uri = https://localhost:5000/ - -3. Set the location of the middleware certificate file (example):: - - certfile = /etc/keystone/ca/certs/middleware-key.pem - -4. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/certs/middleware-key.pem - -For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example -service in the examples/echo directory. - -Testing -======= - -You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory -and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with -the path to the client certificate:: - - python echo_client.py -s diff --git a/docs/source/usingkeystone.rst b/docs/source/usingkeystone.rst deleted file mode 100644 index bb52a94d..00000000 --- a/docs/source/usingkeystone.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. - Copyright 2011 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. - -============== -Using Keystone -============== - -Curl examples -------------- - -.. toctree:: - :maxdepth: 1 - - adminAPI_curl_examples - serviceAPI_curl_examples -- cgit From 1908a2d7ba14b830648078e6871fba0e6644fdf5 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 13:47:29 -0800 Subject: format tweaks and moving old docs --- docs/source/backends.rst | 188 ---------- docs/source/configuringservices.rst | 174 +++++++++ docs/source/index.rst | 6 + docs/source/middleware_architecture.rst | 529 ++++++++++++++++++++++++++++ docs/source/nova-api-paste.rst | 142 ++++++++ docs/source/old/backends.rst | 188 ++++++++++ docs/source/old/configuringservices.rst | 333 ----------------- docs/source/old/middleware_architecture.rst | 529 ---------------------------- docs/source/old/nova-api-paste.rst | 142 -------- docs/source/setup.rst | 2 +- 10 files changed, 1040 insertions(+), 1193 deletions(-) delete mode 100644 docs/source/backends.rst create mode 100644 docs/source/configuringservices.rst create mode 100644 docs/source/middleware_architecture.rst create mode 100644 docs/source/nova-api-paste.rst create mode 100644 docs/source/old/backends.rst delete mode 100644 docs/source/old/configuringservices.rst delete mode 100644 docs/source/old/middleware_architecture.rst delete mode 100644 docs/source/old/nova-api-paste.rst (limited to 'docs/source') diff --git a/docs/source/backends.rst b/docs/source/backends.rst deleted file mode 100644 index b3fc2d91..00000000 --- a/docs/source/backends.rst +++ /dev/null @@ -1,188 +0,0 @@ -.. - Copyright 2011 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. - -======== -Backends -======== - -Keystone supports multiple types of data stores for things like users, tenants, and -tokens, including SQL, LDAP, and memcache. - -SQL -=== - -In the default backend configuration (SQL-only), Keystone depends on the following database tables. - -``users`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Unqiue username used for authentication via ``passwordCredentials``. -``password`` - Password used for authentication via ``passwordCredentials``. - - Salted and hashed using ``passlib``. -``email`` - Email address (uniqueness is expected, but not enforced). -``enabled`` - If false, the user is unable to authenticate and the user's tokens will fail validation. -``tenant_id`` - Default tenant for the user. - -``tokens`` ----------- - -``id`` - The actual token provided after successful authentication (*plaintext*). -``user_id`` - References the user who owns the token. -``tenant_id`` - (*optional*) References the tenant the token is scoped to. -``expires`` - Indicates the expiration date of the token, after which the token can no longer be validated successfully. - -``tenants`` ------------ - -``id`` - Auto-incremented primary key. -``name`` - Unique string identifying the tenant. -``desc`` - Description of the tenant. -``enabled`` - If false, users are unable to scope to the tenant. - -``roles`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Name of the role. - - If the role is owned by a service, the role name **must** follow the convention:: - - serviceName:roleName -``desc`` - Description of the role. -``service_id`` - (*optional*) References the service that owns the role. - -``user_roles`` --------------- - -Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). - -``id`` - Auto-incremented primary key. -``user_id`` - References the user the role is granted to. -``role_id`` - References the granted role. -``tenant_id`` - (*optional*) References a tenant upon which this grant is applies. - -``services`` ------------- - -``id`` - Auto-incremented primary key. -``name`` - Unique name of the service. -``type`` - Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). - - This can also be extended to support non-core services. Extended services - follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). -``desc`` - Describes the service. -``owner_id`` - (*optional*) References the user who owns the service. - -``credentials`` ---------------- - -Currently only used for Amazon EC2 credential storage, this table is designed to support multiple -types of credentials in the future. - -``id`` - Auto-incremented primary key. -``user_id`` - References the user who owns the credential. -``tenant_id`` - References the tenant upon which the credential is valid. -``types`` - Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). -``key`` - Amazon EC2 access key. -``secret`` - Amazon EC2 secret key. - -``endpoints`` -------------- - -Tenant-specific endpoints map endpoint templates to specific tenants. -The ``tenant_id`` which appears here replaces the -``%tenant_id%`` template variable in the specified endpoint template. - -``id`` - Auto-incremented primary key. -``tenant_id`` - References the tenant this endpoint applies to. -``endpoint_template_id`` - The endpoint template to appear in the user's service catalog. - -``endpoint_templates`` ----------------------- - -A multi-purpose model for the service catalog which can be: - -- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. -- Provided to all users as-is, when ``is_global`` is true. - -``id`` - Auto-incremented primary key. -``region`` - Identifies the geographic region the endpoint is physically located within. -``service_id`` - TODO: References the service which owns the endpoints? -``public_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint available on the public Internet. -``admin_url`` - Appears in the service catalog [#first]_. - - Users of this endpoint must have an Admin or ServiceAdmin role. -``internal_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint on an internal, unmetered network. -``enabled`` - If false, this endpoint template will not appear in the service catalog. -``is_global`` - If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. -``version_id`` - Identifies the version of the API contract that endpoint supports. -``version_list`` - A URL which lists versions supported by the endpoint. -``version_info`` - A URL which provides detailed version info regarding the service. - -.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst new file mode 100644 index 00000000..88bb9c15 --- /dev/null +++ b/docs/source/configuringservices.rst @@ -0,0 +1,174 @@ +.. + Copyright 2011 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. + +========================================== +Configuring Services to work with Keystone +========================================== + +.. toctree:: + :maxdepth: 1 + + nova-api-paste + middleware_architecture + +Once Keystone is installed and running (see :doc:`configuration`), services need to be configured to work +with it. To do this, we primarily install and configure middleware for the OpenStack service to handle authentication tasks or otherwise interact with Keystone. + +In general: +* Clients making calls to the service will pass in an authentication token. +* The Keystone middleware will look for and validate that token, taking the appropriate action. +* It will also retrive additional information from the token such as user name, id, tenant name, id, roles, etc... + +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` + +Setting up credentials +====================== + +Admin Token +----------- + +For a default installation of Keystone, before you can use the REST API, you +need to define an authorization token. This is configured in the 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 + +This is a "shared secret" between keystone and other openstack services, and will need to be set the +same between those services in order for keystone services to function correctly. + +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. + +Setting up services +=================== + +Defining Services +----------------- + +Keystone also acts as a service catalog to let other OpenStack systems know +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:: + + keystone-manage service create name=nova service_type=compute description="Nova Compute Service" + keystone-manage service create name=ec2 service_type=ec2 description="EC2 Compatibility Layer" + keystone-manage service create name=glance service_type=image description="Glance Image Service" + keystone-manage service create name=keystone service_type=identity description="Keystone Identity Service" + keystone-manage service create name=swift service_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 +===================== + +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. + +Configuring Nova to use Keystone +-------------------------------- + +To configure Nova to use Keystone for authentication, the Nova API service +can be run against the api-paste file provided by Keystone. This is most +easily accomplished by setting the `--api_paste_config` flag in nova.conf to +point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file +included references to the WSGI authentication middleware provided with the +keystone installation. + +When configuring Nova, it is important to create a admin service token for +the service (from the Configuration step above) and include that as the key +'admin_token' in the nova-api-paste.ini. See the documented +:doc:`nova-api-paste` file for references. + +Configuring Swift to use Keystone +--------------------------------- + +Similar to Nova, swift can be configured to use Keystone for authentication +rather than it's built in 'tempauth'. + +1. Add a service endpoint for Swift to Keystone + +2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) + +3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. + Here's an example `/etc/swift/proxy-server.conf`:: + + [DEFAULT] + bind_port = 8888 + user = + + [pipeline:main] + pipeline = catch_errors cache keystone proxy-server + + [app:proxy-server] + use = egg:swift#proxy + account_autocreate = true + + [filter:keystone] + use = egg:keystone#tokenauth + auth_protocol = http + auth_host = 127.0.0.1 + auth_port = 35357 + admin_token = 999888777666 + delay_auth_decision = 0 + service_protocol = http + service_host = 127.0.0.1 + service_port = 8100 + service_pass = dTpw + cache = swift.cache + + [filter:cache] + use = egg:swift#memcache + set log_name = cache + + [filter:catch_errors] + use = egg:swift#catch_errors + + Note that the optional "cache" property in the keystone filter allows any + service (not just Swift) to register its memcache client in the WSGI + environment. If such a cache exists, Keystone middleware will utilize it + to store validated token information, which could result in better overall + performance. + +4. Restart swift + +5. Verify that keystone is providing authentication to Swift + +Use `swift` to check everything works (note: you currently have to create a +container or upload something as your first action to have the account +created; there's a Swift bug to be fixed soon):: + + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v + StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 + Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 + Account: AUTH_1234 + Containers: 1 + Objects: 0 + Bytes: 0 + Accept-Ranges: bytes + X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b + +.. WARNING:: + Keystone currently allows any valid token to do anything with any account. + diff --git a/docs/source/index.rst b/docs/source/index.rst index 8b12ff93..5d7c80fa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -63,6 +63,12 @@ Developers Documentation developing architecture api_curl_examples + +Code Documentation +================== +.. toctree:: + :maxdepth: 1 + modules Indices and tables diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst new file mode 100644 index 00000000..a8c38f3c --- /dev/null +++ b/docs/source/middleware_architecture.rst @@ -0,0 +1,529 @@ +.. + Copyright 2011 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 multiple authentication protocols +in a pluggable manner in OpenStack. By providing support for authentication via +pluggable authentication components, this architecture allows OpenStack +services to be integrated easily into existing deployment environments. It also +provides a path by which to implement support for emerging authentication +standards such as OAUTH. + +Rationale and Goals +=================== + +Keystone is the Identity service for OpenStack. To support the easy integrating +of OpenStack with existing authentication and identity management systems, +Keystone supports talking to multiple backends like LDAP. +And to support different deployment needs, it can support multiple +authentication protocols via pluggable 'authentication components' implemented +as WSGI middleware. + +In this document, we describe the responsibilities of the authentication +middleware. We describe how these interact with underlying OpenStack services +and how existing services can be modified to take advantage of pluggable +authentication. The goal is to allow OpenStack services to be integrated easily +into existing deployment environments and to provide a path by which to +implement support for emerging authentication standards such as OAUTH. + +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. + +At a high level, an authentication component is simply a reverse proxy that +intercepts HTTP calls from clients. Once it has verified a user's identity, the +authentication component extends the call with information about the current +user and forwards the request to the OpenStack service. Otherwise, if a user's +identity is not verified, the message is rejected before it gets to the +service. This is illustrated in :ref:`authComponent`. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +Authentication components may operate in 'delegated mode'. In this mode, the +decision reject an unauthenticated client is delegated to the OpenStack +service. Delegated mode is 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. Note that it is always the responsibility +of the Authentication Component to transmit reject messages 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) + +In this architecture, we define interactions between the authentication component +and the OpenStack service. Interactions between the client and the +authentication component are defined only for exceptional cases. For example, +we define the message that should be returned when the OpenStack service is +down. Other interactions, however, are defined by the underlying authentication +protocol and the OpenStack service and are considered out of scope. + +.. _deployStrategies: + +Deployment Strategies +===================== + +An authentication component may be integrated directly into the service +implementation, or it may be deployed separately as an HTTP reverse proxy. This +is illustrated in :ref:`deployment`, showing both approaches to +authentication, labeled Option (a) and Option (b). + +.. _deployment: + +Authentication Component Deployments Options +-------------------------------------------- + +Figure 3. Authentication Component Deployments Options + +.. image:: images/images_layouts.svg + :width: 100% + :height: 180 + :alt: Authentication Component Deployments Options + +In Option (a), the component is integrated into the service implementation. In +this case, communication between the authentication component and the service +can be efficiently implemented via a method call. In Option (b), the component +is deployed separately and communication between the service and the component +involves an HTTP request. In both cases, unauthenticated requests are filtered +before they reach the service. + +Each approach offers some benefits. Option (a) offers low latency and ease of +initial implementation, making it possibly most appropriate as a starting point +for simple configurations. Option (b) offers several key advantages that may be +of particular value in complex and dynamic configurations. It offers the +ability to scale horizontally in cases where authentication is computationally +expensive, such as when verifying digital signatures. Option (b) also allows +authentication components to be written in different programming languages. +Finally, Option (b) allows multiple authentication components to be deployed in +front of the same service. + +OpenStack services can support both embedded (Option (a)) and external (Option +(b)) deployment strategies. Individual authentication components should support +either strategy or they |may| support both strategies. In order to support +option (a), authentication components written in the Python programming +language should be written as WSGI middleware components (in accordance with +the Web Server Gateway Interface (WSGI) standard [PEP-333]_. + +Additionally, services should support the ability to swap between different +embedded or external authentication components via configuration options. + +Exchanging User Information +=========================== + +If a request is successfully authenticated, the authentication component must +extend the request by adding an ``X-Authorization`` header. The header |must| +be formatted as illustrated in :ref:`xAuthHeader`. + +.. _xAuthHeader: + +X-Authorization Header +---------------------- + +Example 1. X-Authorization Header:: + + X-Authorization: Proxy JoeUser + +Here, `Proxy` denotes that the authentication occurred via a proxy (in this +case authentication component) and ''JoeUser'' is the name of the user who +issued the request. + +.. note: + + We considered using an ``Authorization`` header rather than an + ``X-Authorization``, thereby following normal HTTP semantics. There are some + cases, however, where multiple ``Authorization`` headers need to be transmitted + in a single request. We want to assure ourselves that this will not break + common clients before we recommend the approach. + +Authentication components |may| extend the request with additional +information. For example, an authentication system may add additional headers +or modify the target URI to pass authentication information to the back-end +service. Additionally, an authentication component |may| strip sensitive +information — a plain text password, for example — from the request. That said, +an authentication component |should| pass the majority of the request +unmodified. + +Reverse Proxy Authentication +---------------------------- + +An OpenStack service |should| verify that it is receiving requests from a +trusted authentication component. This is particularly important in cases where +the authentication component and the OpenStack service are deployed separately. +In order to trust incoming requests, the OpenStack service should therefore +authenticate the authentication component. To avoid confusion, we call this +'reverse proxy authentication', since in this case the authentication +component is acting as an HTTP reverse proxy. + +Any HTTP-based authentication scheme may be used for reverse proxy +authentication; however, all OpenStack services and all authentication +components |must| support HTTP Basic Authentication as defined in +[RFC-2617]_. + +Whether or not reverse proxy authentication is required is strictly a +deployment concern. For example, an operations team may opt to utilize firewall +rules instead of an authentication protocol to verify the integrity of incoming +request. Because of this, both OpenStack services and authentication components +|must| also allow for unauthenticated communication. + +In cases where reverse proxy authentication is used, the authorization +component may receive an HTTP 401 authentication error or an HTTP 403 +authorization error. These errors indicate that the component does not have +access to the underlying OpenStack service. The authentication component +|must not| return these errors to the client application. Instead, the +component |must| return a 500 internal error. This is illustrated in +:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component +|should| format the errors in a manner that does not break the service +contract defined by the OpenStack service. :ref:`proxyAuthDelegated` +illustrates proxy authorization in delegated mode. Delegated mode is discussed +in detail in the next section. + +.. _proxyAuth: + +Reverse Proxy Authentication +---------------------------- + +Figure 4. Reverse Proxy Authentication + +.. image:: images/graphs_proxyAuth.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication + +.. _proxyAuthDelegated: + +Reverse Proxy Authentication (Delegated Mode) +--------------------------------------------- + +Figure 5. Reverse Proxy Authentication (Delegated Mode) + +.. image:: images/graphs_delegate_forbiden_proxy.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication (Delegated Mode) + +Delegated Mode +============== +In some cases, the decision to reject an unauthenticated request should be +delegated to the OpenStack service. An unauthenticated request may be +appropriate in cases when anonymous access is allowed. In order to support +these cases, an authentication component may be placed in Delegated Mode. In +this mode, the component forwards requests to the OpenStack service when the +client's identity has been confirmed or is indeterminate — that is when +credentials are missing. The authentication component directly rejects requests +with invalid credentials. Authentication components |must| extend the +request by adding an `X-Identity-Status` header. The identity status header +|must| contain one of the following values: + +Identity Status Values +---------------------- + +Confirmed + A `confirmed` value indicates that valid credentials were sent and identity + has been confirmed. The service can trust that the request has been sent on + behalf of the user specified in the `X-Authorization` header. + +Indeterminate + An `indeterminate` value indicates that no credentials were sent and + identity has not been confirmed. In this case, the service will receive an + `X-Authorization` header with no user entry as illustrated in + :ref:`xauth-header-indeterminate`. + +.. _xauth-header-indeterminate: + +Indeterminate Identity Headers +------------------------------ + +Example 2. Indeterminate Identity Headers:: + + X-Identity-Status: Indeterminate + X-Authorization: Proxy + +Services |may| reject a delegated request by issuing an HTTP 401 +authentication error or an HTTP 403 authorization error. These responses +|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as +illustrated in :ref:`unauthHeaders`. + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +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-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-Roles + The roles associated with that user + +.. _unauthHeaders: + +Delegated WWW-Authenticate Header +--------------------------------- + +:: + + WWW-Authenticate: Delegated + +It is important to note that the actual reject message will likely be modified +by the authentication component in order to comply with the authentication +scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and +:ref:`delegateRejectOAuth` below. + +.. _delegateRejectBasic: + +Delegated Reject Basic Auth +--------------------------- + +.. image:: images/graphs_delegate_reject_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Basic Auth + +.. _delegateRejectOAuth: + +Delegated Reject OAuth +---------------------- + +.. image:: images/graphs_delegate_reject_oauth.svg + :width: 100% + :height: 180 + :alt: Delegated Reject OAuth + +The presence of the `WWW-Authenticate` header with a value of `Delegated` +distinguishes a client authentication/authorization failure from a component +failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In +:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. +In :ref:`proxyAuthDelegated`, it is the authentication component itself which is +unauthorized. + +.. _delegateForbidden: + +Delegated Reject Forbidden +-------------------------- + +Figure 8. Delegated Reject Forbidden + +.. image:: images/graphs_delegate_forbiden_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Forbidden + +Authentication components |must| support both delegated and undelegated +(standard) modes. Delegated mode |should| be configured via a configuration +option. Delegated mode |should| be disabled by default. + +OpenStack services are not required to support delegated mode. If a service +does not support delegated mode, it |must| respond with a 501 not implemented +error and an `WWW-Authenticate` header with a value of `Delegated`. The +authentication component |must not| return the error to the client +application. Instead, the component |must| return a 500 internal error; this is +illustrated in :ref:`delegateUnimplemented`. The component |should| +format the error in a manner that does not break the service contract defined +by the OpenStack service. The component should also log the error such that it +that will inform operators of the misconfiguration. + +.. _delegateUnimplemented: + +Unimplemented Delegated Mode +---------------------------- + +.. image:: images/graphs_delegate_unimplemented.svg + :width: 100% + :height: 180 + :alt: Unimplemented Delegated Mode + +Handling Direct Client Connections +================================== + +Requests from the authentication component to an OpenStack service |must| +contain an ``X-Authorization`` header. If the header is missing, and reverse +proxy authentication fails or is switched off, the OpenStack service |may| +assume that the request is coming directly from a client application. In this +case, the OpenStack service |must| redirect the request to the authentication +component by issuing an HTTP 305 User Proxy redirect. This is illustrated in +:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header +specifying the authentication component's URL as shown in :ref:`redirect-response`. + +.. _redirect: + +Auth Component Redirect +----------------------- + +.. image:: images/graphs_305.svg + :width: 100% + :height: 280 + :alt: Auth Component Redirect + +.. _redirect-response: + +Auth Component Redirect Response +-------------------------------- + +:: + + HTTP/1.1 305 Use Proxy + Date: Thu, 28 Oct 2011 07:41:16 GMT + Location: http://sample.auth.openstack.com/path/to/resource + +Using Multiple Authentication Components +======================================== + +There are some use cases when a service provider might want to consider using +multiple authentication components for different purposes. For instance, a +service provider may have one authentication scheme to authenticate the users +of the service and another one to authenticate the administrators or operations +personnel that maintain the service. For such scenarios, we propose using a +mapper as illustrated in :ref:`multiAuth`. + +.. _multiAuth: + +Multiple Authentication Components +---------------------------------- + +.. image:: images/graphs_mapper.svg + :width: 100% + :height: 320 + :alt: Multiple Authentication Components + +At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls +from clients and routes the request to the appropriate authentication +component. A mapper can make the routing decisions based on a number of routing +rules that map a resource to a specific authentication component. For example, +a request URI may determine whether a call should be authenticated via one +authentication component or another. + +Note that neither the authentication component nor the OpenStack service need +be aware of the mapper. Any external authentication component can be used +alongside others. Mappers may provide a means by which to offer support for +anonymous or guest access to a subset of service resources. A mapper may be +implemented via a traditional reverse proxy server such as Pound or Zeus. + +The Default Component +===================== + +Individual services |must| be distributed with a simple integrated +authentication component by default. Providing such a component lowers barriers +to the deployment of individual services. This is especially important to] +developers who may want to deploy OpenStack services on their own machines. +Also, since there is no direct dependency on an external authentication system, +OpenStack services can be deployed individually, without the need to stand up +and configure additional services. Finally, having a standard authentication +component that all services share promotes a separation of concerns. That is, +as a community we are explicitly stating that services should not develop their +own authentication mechanisms. Additional authentication components may be +developed, of course, but these components should not be intimately coupled to +any one particular service. + +As discussed in :ref:`deployStrategies`, an authentication component may be +integrated directly into the service implementation (Option (a)), or it may be +deployed separately as an HTTP reverse proxy (Option (b)). The default +component should be implemented to support Option (a) and services should +maintain support for Option (b). One way to achieve this is to provide a +method that allows the disabling of the default authentication component via +configuration. This is illustrated in :ref:`both`. Here, requests are +sent directly to the OpenStack service when the default authentication +component is disabled. + +We will discuss the design of the default component in an upcoming blueprint. + +.. _both: + +Disabled Embedded Component +--------------------------- + +.. image:: images/graphs_both.svg + :width: 100% + :height: 250 + :alt: Disabled Embedded Component + +Questions and Answers +===================== + +#. Why do authentication components send reject messages? Why not have + OpenStack services reject requests themselves? + + The content and format of an authentication failed message is determined by + the authentication scheme (or protocol). For the service to respond + appropriately, it would have to be aware of the authentication scheme in + which it participates; this defeats the purpose of pluggable authentication + components. + +#. Why require support for deploying authentication components in separate + nodes? + + The deployment strategy is very flexible. It allows for authentication + components to be horizontally scalable. It allows for components to be written + in different languages. Finally, it allows different authentication components + to be deployed simultaneously as described above. + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. + +.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. + P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest + Access Authentication.'' http://tools.ietf.org/html/rfc2617. + +.. |must| replace:: must must +.. |should| replace:: should should +.. |may| replace:: may may +.. |must not| replace:: "must not" "must not" + diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst new file mode 100644 index 00000000..586bac72 --- /dev/null +++ b/docs/source/nova-api-paste.rst @@ -0,0 +1,142 @@ +.. + Copyright 2011 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. + +nova-api-paste example +====================== +:: + + ####### + # EC2 # + ####### + + [composite:ec2] + use = egg:Paste#urlmap + /: ec2versions + /services/Cloud: ec2cloud + /services/Admin: ec2admin + /latest: ec2metadata + /2007-01-19: ec2metadata + /2007-03-01: ec2metadata + /2007-08-29: ec2metadata + /2007-10-10: ec2metadata + /2007-12-15: ec2metadata + /2008-02-01: ec2metadata + /2008-09-01: ec2metadata + /2009-04-04: ec2metadata + /1.0: ec2metadata + + [pipeline:ec2cloud] + pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor + + [pipeline:ec2admin] + pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor + + [pipeline:ec2metadata] + pipeline = logrequest ec2md + + [pipeline:ec2versions] + pipeline = logrequest ec2ver + + [filter:logrequest] + paste.filter_factory = nova.api.ec2:RequestLogging.factory + + [filter:ec2lockout] + paste.filter_factory = nova.api.ec2:Lockout.factory + + [filter:totoken] + paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory + + [filter:ec2noauth] + paste.filter_factory = nova.api.ec2:NoAuth.factory + + [filter:authenticate] + paste.filter_factory = nova.api.ec2:Authenticate.factory + + [filter:cloudrequest] + controller = nova.api.ec2.cloud.CloudController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:adminrequest] + controller = nova.api.ec2.admin.AdminController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:authorizer] + paste.filter_factory = nova.api.ec2:Authorizer.factory + + [app:ec2executor] + paste.app_factory = nova.api.ec2:Executor.factory + + [app:ec2ver] + paste.app_factory = nova.api.ec2:Versions.factory + + [app:ec2md] + paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory + + ############# + # Openstack # + ############# + + [composite:osapi] + use = egg:Paste#urlmap + /: osversions + /v1.1: openstackapi + + [pipeline:openstackapi] + pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp + + [filter:faultwrap] + paste.filter_factory = nova.api.openstack:FaultWrapper.factory + + [filter:auth] + paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory + + [filter:noauth] + paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory + + [filter:ratelimit] + paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory + + [filter:extensions] + paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory + + [app:osapiapp] + paste.app_factory = nova.api.openstack:APIRouter.factory + + [pipeline:osversions] + pipeline = faultwrap osversionapp + + [app:osversionapp] + paste.app_factory = nova.api.openstack.versions:Versions.factory + + ########## + # Shared # + ########## + + [filter:keystonecontext] + paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory + + [filter:authtoken] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + service_protocol = http + service_host = 127.0.0.1 + service_port = 5000 + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/old/backends.rst b/docs/source/old/backends.rst new file mode 100644 index 00000000..b3fc2d91 --- /dev/null +++ b/docs/source/old/backends.rst @@ -0,0 +1,188 @@ +.. + Copyright 2011 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. + +======== +Backends +======== + +Keystone supports multiple types of data stores for things like users, tenants, and +tokens, including SQL, LDAP, and memcache. + +SQL +=== + +In the default backend configuration (SQL-only), Keystone depends on the following database tables. + +``users`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Unqiue username used for authentication via ``passwordCredentials``. +``password`` + Password used for authentication via ``passwordCredentials``. + + Salted and hashed using ``passlib``. +``email`` + Email address (uniqueness is expected, but not enforced). +``enabled`` + If false, the user is unable to authenticate and the user's tokens will fail validation. +``tenant_id`` + Default tenant for the user. + +``tokens`` +---------- + +``id`` + The actual token provided after successful authentication (*plaintext*). +``user_id`` + References the user who owns the token. +``tenant_id`` + (*optional*) References the tenant the token is scoped to. +``expires`` + Indicates the expiration date of the token, after which the token can no longer be validated successfully. + +``tenants`` +----------- + +``id`` + Auto-incremented primary key. +``name`` + Unique string identifying the tenant. +``desc`` + Description of the tenant. +``enabled`` + If false, users are unable to scope to the tenant. + +``roles`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Name of the role. + + If the role is owned by a service, the role name **must** follow the convention:: + + serviceName:roleName +``desc`` + Description of the role. +``service_id`` + (*optional*) References the service that owns the role. + +``user_roles`` +-------------- + +Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). + +``id`` + Auto-incremented primary key. +``user_id`` + References the user the role is granted to. +``role_id`` + References the granted role. +``tenant_id`` + (*optional*) References a tenant upon which this grant is applies. + +``services`` +------------ + +``id`` + Auto-incremented primary key. +``name`` + Unique name of the service. +``type`` + Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). + + This can also be extended to support non-core services. Extended services + follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). +``desc`` + Describes the service. +``owner_id`` + (*optional*) References the user who owns the service. + +``credentials`` +--------------- + +Currently only used for Amazon EC2 credential storage, this table is designed to support multiple +types of credentials in the future. + +``id`` + Auto-incremented primary key. +``user_id`` + References the user who owns the credential. +``tenant_id`` + References the tenant upon which the credential is valid. +``types`` + Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). +``key`` + Amazon EC2 access key. +``secret`` + Amazon EC2 secret key. + +``endpoints`` +------------- + +Tenant-specific endpoints map endpoint templates to specific tenants. +The ``tenant_id`` which appears here replaces the +``%tenant_id%`` template variable in the specified endpoint template. + +``id`` + Auto-incremented primary key. +``tenant_id`` + References the tenant this endpoint applies to. +``endpoint_template_id`` + The endpoint template to appear in the user's service catalog. + +``endpoint_templates`` +---------------------- + +A multi-purpose model for the service catalog which can be: + +- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. +- Provided to all users as-is, when ``is_global`` is true. + +``id`` + Auto-incremented primary key. +``region`` + Identifies the geographic region the endpoint is physically located within. +``service_id`` + TODO: References the service which owns the endpoints? +``public_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint available on the public Internet. +``admin_url`` + Appears in the service catalog [#first]_. + + Users of this endpoint must have an Admin or ServiceAdmin role. +``internal_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint on an internal, unmetered network. +``enabled`` + If false, this endpoint template will not appear in the service catalog. +``is_global`` + If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. +``version_id`` + Identifies the version of the API contract that endpoint supports. +``version_list`` + A URL which lists versions supported by the endpoint. +``version_info`` + A URL which provides detailed version info regarding the service. + +.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/docs/source/old/configuringservices.rst b/docs/source/old/configuringservices.rst deleted file mode 100644 index 083c3ec5..00000000 --- a/docs/source/old/configuringservices.rst +++ /dev/null @@ -1,333 +0,0 @@ -.. - Copyright 2011 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. - -========================================== -Configuring Services to work with Keystone -========================================== - -.. toctree:: - :maxdepth: 1 - -Once Keystone is installed and running, services need to be configured to work -with it. These are the steps to configure a service to work with Keystone: - -1. Create or get credentials for the service to use - - A set of credentials are needed for each service (they may be - shared if you chose to). Depending on the service, these credentials are - either a username and password or a long-lived token.. - -2. Register the service, endpoints, roles and other entities - - In order for a service to have it's endpoints and roles show in the service - catalog returned by Keystone, a service record needs to be added for the - service. Endpoints and roles associated with that service can then be created. - - This can be done through the REST interface (using the OS-KSCATALOG extension) - or using keystone-manage. - -3. Install and configure middleware for the service to handle authentication - - Clients making calls to the service will pass in an authentication token. The - Keystone middleware will look for and validate that token, taking the - appropriate action. It will also retrive additional information from the token - such as user name, id, tenant name, id, roles, etc... - - The middleware will pass those data down to the service as headers. The - detailed description of this architecture is available here :doc:`middleware_architecture` - -Setting up credentials -====================== - -First admin user - bootstrapping --------------------------------- - -For a default installation of Keystone, before you can use the REST API, you -need to create your first initial user and grant that user the right to -administer Keystone. - -For the keystone service itself, two -Roles are pre-defined in the keystone configuration file -(:doc:`keystone.conf`). - - #Role that allows admin operations (access to all operations) - keystone-admin-role = Admin - - #Role that allows acting as service (validate tokens, register service, - etc...) - keystone-service-admin-role = KeystoneServiceAdmin - -In order to create your first user, once Keystone is running use -the `keystone-manage` command: - - $ keystone-manage user add admin secrete - $ keystone-manage role add Admin - $ keystone-manage role add KeystoneServiceAdmin - $ keystone-manage role grant Admin admin - $ keystone-manage role grant KeystoneServiceAdmin admin - -This creates the `admin` user (with a password of `secrete`), creates -two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to -the `admin` user. From here, you should now have the choice of using the -administrative API (as well as the :doc:`man/keystone-manage` commands) to -further configure keystone. There are a number of examples of how to use -that API at :doc:`adminAPI_curl_examples`. - - -Setting up services -=================== - -Defining Services and Service Endpoints ---------------------------------------- - -Keystone also acts as a service catalog to let other OpenStack systems know -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:: - - $ keystone-manage service add nova compute "Nova Compute Service" - $ keystone-manage service add glance image "Glance Image Service" - $ keystone-manage service add swift storage "Swift Object Storage Service" - $ keystone-manage service add keystone identity "Keystone Identity Service" - -Once the services are defined, we create endpoints for them. Each service -has three relevant URL's associated with it that are used in the command: - -* the public API URL -* an administrative API URL -* an internal URL - -The "internal URL" is an endpoint the generally offers the same API as the -public URL, but over a high-bandwidth, low-latency, unmetered (free) network. -You would use that to transfer images from nova to glance for example, and -not the Public URL which would go over the internet and be potentially chargeable. - -The "admin URL" is for administering the services and is not exposed or accessible -to customers without the apporpriate privileges. - -An example of setting up the endpoint for Nova:: - - $ keystone-manage endpointTemplates add RegionOne nova \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - 1 1 - -Glance:: - - $ keystone-manage endpointTemplates add RegionOne glance \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - 1 1 - -Swift:: - - $ keystone-manage endpointTemplates add RegionOne swift \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - http://swift.mydomain:8080/v1.0/ \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - 1 1 - -And setting up an endpoint for Keystone:: - - $ keystone-manage endpointTemplates add RegionOne keystone \ - http://keystone.mydomain:5000/v2.0 \ - http://keystone.mydomain:35357/v2.0 \ - http://keystone.mydomain:5000/v2.0 \ - 1 1 - - -Defining an Administrative Service Token ----------------------------------------- - -An Administrative Service Token is a bit of arbitrary text which is configured -in Keystone and used (typically configured into) Nova, Swift, Glance, and any -other OpenStack projects, to be able to use Keystone services. - -This token is an arbitrary text string, but must be identical between Keystone -and the services using Keystone. This token is bound to a user and tenant as -well, so those also need to be created prior to setting it up. - -The *admin* user was set up above, but we haven't created a tenant for that -user yet:: - - $ keystone-manage tenant add admin - -and while we're here, let's grant the admin user the 'Admin' role to the -'admin' tenant:: - - $ keystone-manage role add Admin - $ keystone-manage role grant Admin admin admin - -Now we can create a service token:: - - $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 - -This creates a service token of '999888777666' associated to the admin user, -admin tenant, and expires on February 5th, 2015. This token will be used when -configuring Nova, Glance, or other OpenStack services. - -Securing Communications with SSL --------------------------------- - -To encrypt traffic between services and Keystone, see :doc:`ssl` - - -Setting up OpenStack users -========================== - -Creating Tenants, Users, and Roles ----------------------------------- - -Let's set up a 'demo' tenant:: - - $ keystone-manage tenant add demo - -And add a 'demo' user with the password 'guest':: - - $ keystone-manage user add demo guest - -Now let's add a role of "Member" and grant 'demo' user that role -as it pertains to the tenant 'demo':: - - $ keystone-manage role add Member - $ keystone-manage role grant Member demo demo - -Let's also add the admin user as an Admin role to the demo tenant:: - - $ keystone-manage role grant Admin admin demo - -Creating EC2 credentials ------------------------- - -To add EC2 credentials for the `admin` and `demo` accounts:: - - $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' - $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' - -If you have a large number of credentials to create, you can put them all -into a single large file and import them using :doc:`man/keystone-import`. The -format of the document looks like:: - - credentials add admin EC2 'username' 'password' - credentials add admin EC2 'username' 'password' - -Then use:: - - $ keystone-import `filename` - - -Setting Up Middleware -===================== - -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. See :doc:`middleware` -for details on middleware and configuration parameters. - - -Configuring Nova to use Keystone --------------------------------- - -To configure Nova to use Keystone for authentication, the Nova API service -can be run against the api-paste file provided by Keystone. This is most -easily accomplished by setting the `--api_paste_config` flag in nova.conf to -point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file -included references to the WSGI authentication middleware provided with the -keystone installation. - -When configuring Nova, it is important to create a admin service token for -the service (from the Configuration step above) and include that as the key -'admin_token' in the nova-api-paste.ini. See the documented -:doc:`nova-api-paste` file for references. - -Configuring Swift to use Keystone ---------------------------------- - -Similar to Nova, swift can be configured to use Keystone for authentication -rather than it's built in 'tempauth'. - -1. Add a service endpoint for Swift to Keystone - -2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) - -3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. - Here's an example `/etc/swift/proxy-server.conf`:: - - [DEFAULT] - bind_port = 8888 - user = - - [pipeline:main] - pipeline = catch_errors cache keystone proxy-server - - [app:proxy-server] - use = egg:swift#proxy - account_autocreate = true - - [filter:keystone] - use = egg:keystone#tokenauth - auth_protocol = http - auth_host = 127.0.0.1 - auth_port = 35357 - admin_token = 999888777666 - delay_auth_decision = 0 - service_protocol = http - service_host = 127.0.0.1 - service_port = 8100 - service_pass = dTpw - cache = swift.cache - - [filter:cache] - use = egg:swift#memcache - set log_name = cache - - [filter:catch_errors] - use = egg:swift#catch_errors - - Note that the optional "cache" property in the keystone filter allows any - service (not just Swift) to register its memcache client in the WSGI - environment. If such a cache exists, Keystone middleware will utilize it - to store validated token information, which could result in better overall - performance. - -4. Restart swift - -5. Verify that keystone is providing authentication to Swift - -Use `swift` to check everything works (note: you currently have to create a -container or upload something as your first action to have the account -created; there's a Swift bug to be fixed soon):: - - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v - StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 - Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 - Account: AUTH_1234 - Containers: 1 - Objects: 0 - Bytes: 0 - Accept-Ranges: bytes - X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b - -.. WARNING:: - Keystone currently allows any valid token to do anything with any account. - diff --git a/docs/source/old/middleware_architecture.rst b/docs/source/old/middleware_architecture.rst deleted file mode 100644 index a8c38f3c..00000000 --- a/docs/source/old/middleware_architecture.rst +++ /dev/null @@ -1,529 +0,0 @@ -.. - Copyright 2011 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 multiple authentication protocols -in a pluggable manner in OpenStack. By providing support for authentication via -pluggable authentication components, this architecture allows OpenStack -services to be integrated easily into existing deployment environments. It also -provides a path by which to implement support for emerging authentication -standards such as OAUTH. - -Rationale and Goals -=================== - -Keystone is the Identity service for OpenStack. To support the easy integrating -of OpenStack with existing authentication and identity management systems, -Keystone supports talking to multiple backends like LDAP. -And to support different deployment needs, it can support multiple -authentication protocols via pluggable 'authentication components' implemented -as WSGI middleware. - -In this document, we describe the responsibilities of the authentication -middleware. We describe how these interact with underlying OpenStack services -and how existing services can be modified to take advantage of pluggable -authentication. The goal is to allow OpenStack services to be integrated easily -into existing deployment environments and to provide a path by which to -implement support for emerging authentication standards such as OAUTH. - -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. - -At a high level, an authentication component is simply a reverse proxy that -intercepts HTTP calls from clients. Once it has verified a user's identity, the -authentication component extends the call with information about the current -user and forwards the request to the OpenStack service. Otherwise, if a user's -identity is not verified, the message is rejected before it gets to the -service. This is illustrated in :ref:`authComponent`. - -.. _authComponent: - -Authentication Component ------------------------- - -Figure 1. Authentication Component - -.. image:: images/graphs_authComp.svg - :width: 100% - :height: 180 - :alt: An Authentication Component - -Authentication components may operate in 'delegated mode'. In this mode, the -decision reject an unauthenticated client is delegated to the OpenStack -service. Delegated mode is 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. Note that it is always the responsibility -of the Authentication Component to transmit reject messages 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) - -In this architecture, we define interactions between the authentication component -and the OpenStack service. Interactions between the client and the -authentication component are defined only for exceptional cases. For example, -we define the message that should be returned when the OpenStack service is -down. Other interactions, however, are defined by the underlying authentication -protocol and the OpenStack service and are considered out of scope. - -.. _deployStrategies: - -Deployment Strategies -===================== - -An authentication component may be integrated directly into the service -implementation, or it may be deployed separately as an HTTP reverse proxy. This -is illustrated in :ref:`deployment`, showing both approaches to -authentication, labeled Option (a) and Option (b). - -.. _deployment: - -Authentication Component Deployments Options --------------------------------------------- - -Figure 3. Authentication Component Deployments Options - -.. image:: images/images_layouts.svg - :width: 100% - :height: 180 - :alt: Authentication Component Deployments Options - -In Option (a), the component is integrated into the service implementation. In -this case, communication between the authentication component and the service -can be efficiently implemented via a method call. In Option (b), the component -is deployed separately and communication between the service and the component -involves an HTTP request. In both cases, unauthenticated requests are filtered -before they reach the service. - -Each approach offers some benefits. Option (a) offers low latency and ease of -initial implementation, making it possibly most appropriate as a starting point -for simple configurations. Option (b) offers several key advantages that may be -of particular value in complex and dynamic configurations. It offers the -ability to scale horizontally in cases where authentication is computationally -expensive, such as when verifying digital signatures. Option (b) also allows -authentication components to be written in different programming languages. -Finally, Option (b) allows multiple authentication components to be deployed in -front of the same service. - -OpenStack services can support both embedded (Option (a)) and external (Option -(b)) deployment strategies. Individual authentication components should support -either strategy or they |may| support both strategies. In order to support -option (a), authentication components written in the Python programming -language should be written as WSGI middleware components (in accordance with -the Web Server Gateway Interface (WSGI) standard [PEP-333]_. - -Additionally, services should support the ability to swap between different -embedded or external authentication components via configuration options. - -Exchanging User Information -=========================== - -If a request is successfully authenticated, the authentication component must -extend the request by adding an ``X-Authorization`` header. The header |must| -be formatted as illustrated in :ref:`xAuthHeader`. - -.. _xAuthHeader: - -X-Authorization Header ----------------------- - -Example 1. X-Authorization Header:: - - X-Authorization: Proxy JoeUser - -Here, `Proxy` denotes that the authentication occurred via a proxy (in this -case authentication component) and ''JoeUser'' is the name of the user who -issued the request. - -.. note: - - We considered using an ``Authorization`` header rather than an - ``X-Authorization``, thereby following normal HTTP semantics. There are some - cases, however, where multiple ``Authorization`` headers need to be transmitted - in a single request. We want to assure ourselves that this will not break - common clients before we recommend the approach. - -Authentication components |may| extend the request with additional -information. For example, an authentication system may add additional headers -or modify the target URI to pass authentication information to the back-end -service. Additionally, an authentication component |may| strip sensitive -information — a plain text password, for example — from the request. That said, -an authentication component |should| pass the majority of the request -unmodified. - -Reverse Proxy Authentication ----------------------------- - -An OpenStack service |should| verify that it is receiving requests from a -trusted authentication component. This is particularly important in cases where -the authentication component and the OpenStack service are deployed separately. -In order to trust incoming requests, the OpenStack service should therefore -authenticate the authentication component. To avoid confusion, we call this -'reverse proxy authentication', since in this case the authentication -component is acting as an HTTP reverse proxy. - -Any HTTP-based authentication scheme may be used for reverse proxy -authentication; however, all OpenStack services and all authentication -components |must| support HTTP Basic Authentication as defined in -[RFC-2617]_. - -Whether or not reverse proxy authentication is required is strictly a -deployment concern. For example, an operations team may opt to utilize firewall -rules instead of an authentication protocol to verify the integrity of incoming -request. Because of this, both OpenStack services and authentication components -|must| also allow for unauthenticated communication. - -In cases where reverse proxy authentication is used, the authorization -component may receive an HTTP 401 authentication error or an HTTP 403 -authorization error. These errors indicate that the component does not have -access to the underlying OpenStack service. The authentication component -|must not| return these errors to the client application. Instead, the -component |must| return a 500 internal error. This is illustrated in -:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component -|should| format the errors in a manner that does not break the service -contract defined by the OpenStack service. :ref:`proxyAuthDelegated` -illustrates proxy authorization in delegated mode. Delegated mode is discussed -in detail in the next section. - -.. _proxyAuth: - -Reverse Proxy Authentication ----------------------------- - -Figure 4. Reverse Proxy Authentication - -.. image:: images/graphs_proxyAuth.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication - -.. _proxyAuthDelegated: - -Reverse Proxy Authentication (Delegated Mode) ---------------------------------------------- - -Figure 5. Reverse Proxy Authentication (Delegated Mode) - -.. image:: images/graphs_delegate_forbiden_proxy.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication (Delegated Mode) - -Delegated Mode -============== -In some cases, the decision to reject an unauthenticated request should be -delegated to the OpenStack service. An unauthenticated request may be -appropriate in cases when anonymous access is allowed. In order to support -these cases, an authentication component may be placed in Delegated Mode. In -this mode, the component forwards requests to the OpenStack service when the -client's identity has been confirmed or is indeterminate — that is when -credentials are missing. The authentication component directly rejects requests -with invalid credentials. Authentication components |must| extend the -request by adding an `X-Identity-Status` header. The identity status header -|must| contain one of the following values: - -Identity Status Values ----------------------- - -Confirmed - A `confirmed` value indicates that valid credentials were sent and identity - has been confirmed. The service can trust that the request has been sent on - behalf of the user specified in the `X-Authorization` header. - -Indeterminate - An `indeterminate` value indicates that no credentials were sent and - identity has not been confirmed. In this case, the service will receive an - `X-Authorization` header with no user entry as illustrated in - :ref:`xauth-header-indeterminate`. - -.. _xauth-header-indeterminate: - -Indeterminate Identity Headers ------------------------------- - -Example 2. Indeterminate Identity Headers:: - - X-Identity-Status: Indeterminate - X-Authorization: Proxy - -Services |may| reject a delegated request by issuing an HTTP 401 -authentication error or an HTTP 403 authorization error. These responses -|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as -illustrated in :ref:`unauthHeaders`. - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -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-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-Roles - The roles associated with that user - -.. _unauthHeaders: - -Delegated WWW-Authenticate Header ---------------------------------- - -:: - - WWW-Authenticate: Delegated - -It is important to note that the actual reject message will likely be modified -by the authentication component in order to comply with the authentication -scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and -:ref:`delegateRejectOAuth` below. - -.. _delegateRejectBasic: - -Delegated Reject Basic Auth ---------------------------- - -.. image:: images/graphs_delegate_reject_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Basic Auth - -.. _delegateRejectOAuth: - -Delegated Reject OAuth ----------------------- - -.. image:: images/graphs_delegate_reject_oauth.svg - :width: 100% - :height: 180 - :alt: Delegated Reject OAuth - -The presence of the `WWW-Authenticate` header with a value of `Delegated` -distinguishes a client authentication/authorization failure from a component -failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In -:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. -In :ref:`proxyAuthDelegated`, it is the authentication component itself which is -unauthorized. - -.. _delegateForbidden: - -Delegated Reject Forbidden --------------------------- - -Figure 8. Delegated Reject Forbidden - -.. image:: images/graphs_delegate_forbiden_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Forbidden - -Authentication components |must| support both delegated and undelegated -(standard) modes. Delegated mode |should| be configured via a configuration -option. Delegated mode |should| be disabled by default. - -OpenStack services are not required to support delegated mode. If a service -does not support delegated mode, it |must| respond with a 501 not implemented -error and an `WWW-Authenticate` header with a value of `Delegated`. The -authentication component |must not| return the error to the client -application. Instead, the component |must| return a 500 internal error; this is -illustrated in :ref:`delegateUnimplemented`. The component |should| -format the error in a manner that does not break the service contract defined -by the OpenStack service. The component should also log the error such that it -that will inform operators of the misconfiguration. - -.. _delegateUnimplemented: - -Unimplemented Delegated Mode ----------------------------- - -.. image:: images/graphs_delegate_unimplemented.svg - :width: 100% - :height: 180 - :alt: Unimplemented Delegated Mode - -Handling Direct Client Connections -================================== - -Requests from the authentication component to an OpenStack service |must| -contain an ``X-Authorization`` header. If the header is missing, and reverse -proxy authentication fails or is switched off, the OpenStack service |may| -assume that the request is coming directly from a client application. In this -case, the OpenStack service |must| redirect the request to the authentication -component by issuing an HTTP 305 User Proxy redirect. This is illustrated in -:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header -specifying the authentication component's URL as shown in :ref:`redirect-response`. - -.. _redirect: - -Auth Component Redirect ------------------------ - -.. image:: images/graphs_305.svg - :width: 100% - :height: 280 - :alt: Auth Component Redirect - -.. _redirect-response: - -Auth Component Redirect Response --------------------------------- - -:: - - HTTP/1.1 305 Use Proxy - Date: Thu, 28 Oct 2011 07:41:16 GMT - Location: http://sample.auth.openstack.com/path/to/resource - -Using Multiple Authentication Components -======================================== - -There are some use cases when a service provider might want to consider using -multiple authentication components for different purposes. For instance, a -service provider may have one authentication scheme to authenticate the users -of the service and another one to authenticate the administrators or operations -personnel that maintain the service. For such scenarios, we propose using a -mapper as illustrated in :ref:`multiAuth`. - -.. _multiAuth: - -Multiple Authentication Components ----------------------------------- - -.. image:: images/graphs_mapper.svg - :width: 100% - :height: 320 - :alt: Multiple Authentication Components - -At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls -from clients and routes the request to the appropriate authentication -component. A mapper can make the routing decisions based on a number of routing -rules that map a resource to a specific authentication component. For example, -a request URI may determine whether a call should be authenticated via one -authentication component or another. - -Note that neither the authentication component nor the OpenStack service need -be aware of the mapper. Any external authentication component can be used -alongside others. Mappers may provide a means by which to offer support for -anonymous or guest access to a subset of service resources. A mapper may be -implemented via a traditional reverse proxy server such as Pound or Zeus. - -The Default Component -===================== - -Individual services |must| be distributed with a simple integrated -authentication component by default. Providing such a component lowers barriers -to the deployment of individual services. This is especially important to] -developers who may want to deploy OpenStack services on their own machines. -Also, since there is no direct dependency on an external authentication system, -OpenStack services can be deployed individually, without the need to stand up -and configure additional services. Finally, having a standard authentication -component that all services share promotes a separation of concerns. That is, -as a community we are explicitly stating that services should not develop their -own authentication mechanisms. Additional authentication components may be -developed, of course, but these components should not be intimately coupled to -any one particular service. - -As discussed in :ref:`deployStrategies`, an authentication component may be -integrated directly into the service implementation (Option (a)), or it may be -deployed separately as an HTTP reverse proxy (Option (b)). The default -component should be implemented to support Option (a) and services should -maintain support for Option (b). One way to achieve this is to provide a -method that allows the disabling of the default authentication component via -configuration. This is illustrated in :ref:`both`. Here, requests are -sent directly to the OpenStack service when the default authentication -component is disabled. - -We will discuss the design of the default component in an upcoming blueprint. - -.. _both: - -Disabled Embedded Component ---------------------------- - -.. image:: images/graphs_both.svg - :width: 100% - :height: 250 - :alt: Disabled Embedded Component - -Questions and Answers -===================== - -#. Why do authentication components send reject messages? Why not have - OpenStack services reject requests themselves? - - The content and format of an authentication failed message is determined by - the authentication scheme (or protocol). For the service to respond - appropriately, it would have to be aware of the authentication scheme in - which it participates; this defeats the purpose of pluggable authentication - components. - -#. Why require support for deploying authentication components in separate - nodes? - - The deployment strategy is very flexible. It allows for authentication - components to be horizontally scalable. It allows for components to be written - in different languages. Finally, it allows different authentication components - to be deployed simultaneously as described above. - -References -========== - -.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface - v1.0.'' http://www.python.org/dev/peps/pep-0333/. - -.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. - P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest - Access Authentication.'' http://tools.ietf.org/html/rfc2617. - -.. |must| replace:: must must -.. |should| replace:: should should -.. |may| replace:: may may -.. |must not| replace:: "must not" "must not" - diff --git a/docs/source/old/nova-api-paste.rst b/docs/source/old/nova-api-paste.rst deleted file mode 100644 index 586bac72..00000000 --- a/docs/source/old/nova-api-paste.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. - Copyright 2011 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. - -nova-api-paste example -====================== -:: - - ####### - # EC2 # - ####### - - [composite:ec2] - use = egg:Paste#urlmap - /: ec2versions - /services/Cloud: ec2cloud - /services/Admin: ec2admin - /latest: ec2metadata - /2007-01-19: ec2metadata - /2007-03-01: ec2metadata - /2007-08-29: ec2metadata - /2007-10-10: ec2metadata - /2007-12-15: ec2metadata - /2008-02-01: ec2metadata - /2008-09-01: ec2metadata - /2009-04-04: ec2metadata - /1.0: ec2metadata - - [pipeline:ec2cloud] - pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor - - [pipeline:ec2admin] - pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor - - [pipeline:ec2metadata] - pipeline = logrequest ec2md - - [pipeline:ec2versions] - pipeline = logrequest ec2ver - - [filter:logrequest] - paste.filter_factory = nova.api.ec2:RequestLogging.factory - - [filter:ec2lockout] - paste.filter_factory = nova.api.ec2:Lockout.factory - - [filter:totoken] - paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory - - [filter:ec2noauth] - paste.filter_factory = nova.api.ec2:NoAuth.factory - - [filter:authenticate] - paste.filter_factory = nova.api.ec2:Authenticate.factory - - [filter:cloudrequest] - controller = nova.api.ec2.cloud.CloudController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:adminrequest] - controller = nova.api.ec2.admin.AdminController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:authorizer] - paste.filter_factory = nova.api.ec2:Authorizer.factory - - [app:ec2executor] - paste.app_factory = nova.api.ec2:Executor.factory - - [app:ec2ver] - paste.app_factory = nova.api.ec2:Versions.factory - - [app:ec2md] - paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory - - ############# - # Openstack # - ############# - - [composite:osapi] - use = egg:Paste#urlmap - /: osversions - /v1.1: openstackapi - - [pipeline:openstackapi] - pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp - - [filter:faultwrap] - paste.filter_factory = nova.api.openstack:FaultWrapper.factory - - [filter:auth] - paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory - - [filter:noauth] - paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory - - [filter:ratelimit] - paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory - - [filter:extensions] - paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory - - [app:osapiapp] - paste.app_factory = nova.api.openstack:APIRouter.factory - - [pipeline:osversions] - pipeline = faultwrap osversionapp - - [app:osversionapp] - paste.app_factory = nova.api.openstack.versions:Versions.factory - - ########## - # Shared # - ########## - - [filter:keystonecontext] - paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory - - [filter:authtoken] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_protocol = http - service_host = 127.0.0.1 - service_port = 5000 - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://127.0.0.1:5000/ - admin_token = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/setup.rst b/docs/source/setup.rst index 25a43655..4f6b6137 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -150,7 +150,7 @@ If you want to check the version of Keystone you are running: >>> print keystone.version.version() 2012.1-dev -If you can import keystone successfully, you should be ready to move on to :doc:`testing` and :doc:`developing` +If you can import keystone successfully, you should be ready to move on to :doc:`developing` Troubleshooting =============== -- cgit From ef8b8f1d9b61ff527b223d69c52f35f25536b8dd Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 14:09:24 -0800 Subject: updating formating for configuration page --- docs/source/configuration.rst | 133 +++++++++++++++++++++++++----------------- 1 file changed, 81 insertions(+), 52 deletions(-) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index e16d1892..410e7b1b 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -101,13 +101,14 @@ from the API call. Invoking keystone-manage by itself will give you some usage information. Available keystone-manage commands: - db_sync: Sync the database. - ec2: no docs - role: Role CRUD functions. - service: Service CRUD functions. - tenant: Tenant CRUD functions. - token: Token CRUD functions. - user: User CRUD functions. + +* ``db_sync``: Sync the database. +* ``ec2``: no docs +* ``role``: Role CRUD functions. +* ``service``: Service CRUD functions. +* ``tenant``: Tenant CRUD functions. +* ``token``: Token CRUD functions. +* ``user``: User CRUD functions. Tenants ------- @@ -116,33 +117,42 @@ Tenants are the high level grouping within Keystone that represent groups of users. A tenant is the grouping that owns virtual machines within Nova, or containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. -* tenant create +``tenant create`` +^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * tenant_name - * id (optional) +* tenant_name +* id (optional) example:: + keystone-manage --id-only tenant create tenant_name=admin creates a tenant named "admin". -* tenant delete +``tenant delete`` +^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * tenant_id +* tenant_id example:: + keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 -* tenant update +``tenant update`` +^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * description - * name - * tenant_id +* description +* name +* tenant_id example:: + keystone-manage tenant update \ tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ description="those other guys" \ @@ -151,60 +161,74 @@ example:: Users ----- -* user create +``user create`` +^^^^^^^^^^^^^^^ - keyword arguments - * name - * password - * email +keyword arguments + +* name +* password +* email example:: + keystone-manage user --ks-id-only create \ name=admin \ password=secrete \ email=admin@example.com -* user delete +``user delete`` +^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user list +``user list`` +^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_email +``user update_email`` +^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_enabled +``user update_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_password +``user update_password`` +^^^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_tenant +``user update_tenant`` +^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments Roles ----- -* role create +``role create`` +^^^^^^^^^^^^^^^ - keyword arguments - * name +keyword arguments + +* name exmaple:: + keystone-manage role --ks-id-only create name=Admin -* role add_user_to_tenant +``role add_user_to_tenant`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments - * role_id - * user_id - * tenant_id +keyword arguments + +* role_id +* user_id +* tenant_id example:: @@ -213,22 +237,27 @@ example:: user_id=08741d8ed88242ca88d1f61484a0fe3b \ tenant_id=20601a7f1d94447daa4dff438cb1c209 -* role remove_user_from_tenant +``role remove_user_from_tenant`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* role get_user_role_refs +``role get_user_role_refs`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Services -------- -* service create +``service create`` +^^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * name - * service_type - * description +* name +* service_type +* description example:: - keystone-manage service create \ + + keystone-manage service create \ name=nova \ service_type=compute \ description="Nova Compute Service" -- cgit 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 From d1f4ddcb81d470401f5b6c80b66ac9649e3c224e Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 14:36:11 -0800 Subject: adding in testing details --- docs/source/developing.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/developing.rst b/docs/source/developing.rst index 48ba2873..344a6e8b 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -70,7 +70,15 @@ light integration testing to verify the keystone API against other projects. Test Structure -------------- -UPDATE THIS... +``./run_test.sh`` uses it's python cohort (``run_tests.py``) to iterate through the ``tests`` directory, using Nosetest to collect the tests and invoke them using an +OpenStack custom test running that displays the tests as well as the time taken to +run those tests. + +Within the tests directory, the general structure of the tests is a basic set of tests represented under a test class, and then subclasses of those tests under other classes with different configurations to drive different backends through the APIs. + +For example, ``test_backend.py`` has a sequence of tests under the class ``IdentityTests`` that will work with the default drivers as configured in this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests, changing the configuration by overriding with configuration files stored in the tests directory aimed at enabling the SQL backend for the Identity module. + +Likewise, ``test_cli.py`` takes advantage of the tests written aainst ``test_keystoneclient`` to verify the same tests function through different drivers. Testing Schema Migrations ------------------------- @@ -92,8 +100,9 @@ This command references to a SQLite database (test.db) to be used. Depending on Writing Tests ------------- -UPDATE THIS... +To add tests covering all drivers, update the base test class (``test_backend.py``, ``test_legacy_compat.py``, and ``test_keystoneclient.py``). +To add new drivers, subclass the ``test_backend.py`` (look towards ``test_backend_sql.py`` or ``test_backend_kvs.py`` for examples) and update the configuration of the test class in ``setUp()``. Further Testing --------------- -- cgit From 9d7d898586566cf2f7c21846961f67a773c2ee6c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 30 Jan 2012 19:53:08 +0000 Subject: shifting contents from _static to static --- docs/source/_static/basic.css | 416 ------------------------------------ docs/source/_static/default.css | 230 -------------------- docs/source/_static/jquery.tweet.js | 154 ------------- docs/source/_static/tweaks.css | 65 ------ docs/source/conf.py | 2 +- docs/source/static/basic.css | 416 ++++++++++++++++++++++++++++++++++++ docs/source/static/default.css | 230 ++++++++++++++++++++ docs/source/static/jquery.tweet.js | 154 +++++++++++++ docs/source/static/tweaks.css | 65 ++++++ 9 files changed, 866 insertions(+), 866 deletions(-) delete mode 100644 docs/source/_static/basic.css delete mode 100644 docs/source/_static/default.css delete mode 100644 docs/source/_static/jquery.tweet.js delete mode 100644 docs/source/_static/tweaks.css create mode 100644 docs/source/static/basic.css create mode 100644 docs/source/static/default.css create mode 100644 docs/source/static/jquery.tweet.js create mode 100644 docs/source/static/tweaks.css (limited to 'docs/source') diff --git a/docs/source/_static/basic.css b/docs/source/_static/basic.css deleted file mode 100644 index d909ce37..00000000 --- a/docs/source/_static/basic.css +++ /dev/null @@ -1,416 +0,0 @@ -/** - * Sphinx stylesheet -- basic theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -/* -- main layout ----------------------------------------------------------- */ - -div.clearer { - clear: both; -} - -/* -- relbar ---------------------------------------------------------------- */ - -div.related { - width: 100%; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -/* -- sidebar --------------------------------------------------------------- */ - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.sphinxsidebar ul { - list-style: none; -} - -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -img { - border: 0; -} - -/* -- search page ----------------------------------------------------------- */ - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* -- index page ------------------------------------------------------------ */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* -- general index --------------------------------------------------------- */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -/* -- general body styles --------------------------------------------------- */ - -a.headerlink { - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -.field-list ul { - padding-left: 1em; -} - -.first { -} - -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* -- sidebars -------------------------------------------------------------- */ - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; -} - -/* -- topics ---------------------------------------------------------------- */ - -div.topic { - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* -- admonitions ----------------------------------------------------------- */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -/* -- tables ---------------------------------------------------------------- */ - -table.docutils { - border: 0; - border-collapse: collapse; -} - -table.docutils td, table.docutils th { - padding: 1px 8px 1px 0; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -th { - text-align: left; - padding-right: 5px; -} - -/* -- other body styles ----------------------------------------------------- */ - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -dt:target, .highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -.refcount { - color: #060; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -.footnote:target { - background-color: #ffa -} - -.line-block { - display: block; - margin-top: 1em; - margin-bottom: 1em; -} - -.line-block .line-block { - margin-top: 0; - margin-bottom: 0; - margin-left: 1.5em; -} - -/* -- code displays --------------------------------------------------------- */ - -pre { - overflow: auto; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -/* -- math display ---------------------------------------------------------- */ - -img.math { - vertical-align: middle; -} - -div.body div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -/* -- printout stylesheet --------------------------------------------------- */ - -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0 !important; - width: 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - #top-link { - display: none; - } -} diff --git a/docs/source/_static/default.css b/docs/source/_static/default.css deleted file mode 100644 index c8091ecb..00000000 --- a/docs/source/_static/default.css +++ /dev/null @@ -1,230 +0,0 @@ -/** - * Sphinx stylesheet -- default theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - background-color: #1c4e63; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - -div.body { - background-color: #ffffff; - color: #000000; - padding: 0 20px 30px 20px; -} - -div.footer { - color: #ffffff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #ffffff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - line-height: 30px; - color: #ffffff; -} - -div.related a { - color: #ffffff; -} - -div.sphinxsidebar { -} - -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: #ffffff; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: #ffffff; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - color: #ffffff; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - -div.body p, div.body dd, div.body li { - text-align: left; - line-height: 130%; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: left; - line-height: 130%; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.admonition p { - margin-bottom: 5px; -} - -div.admonition pre { - margin-bottom: 5px; -} - -div.admonition ul, div.admonition ol { - margin-bottom: 5px; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre { - padding: 5px; - background-color: #eeffcc; - color: #333333; - line-height: 120%; - border: 1px solid #ac9; - border-left: none; - border-right: none; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - -.warning tt { - background: #efc2c2; -} - -.note tt { - background: #d6d6d6; -} diff --git a/docs/source/_static/jquery.tweet.js b/docs/source/_static/jquery.tweet.js deleted file mode 100644 index c93fea87..00000000 --- a/docs/source/_static/jquery.tweet.js +++ /dev/null @@ -1,154 +0,0 @@ -(function($) { - - $.fn.tweet = function(o){ - var s = { - username: ["seaofclouds"], // [string] required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"] - list: null, //[string] optional name of list belonging to username - avatar_size: null, // [integer] height and width of avatar if displayed (48px max) - count: 3, // [integer] how many tweets to display? - intro_text: null, // [string] do you want text BEFORE your your tweets? - outro_text: null, // [string] do you want text AFTER your tweets? - join_text: null, // [string] optional text in between date and tweet, try setting to "auto" - auto_join_text_default: "i said,", // [string] auto text for non verb: "i said" bullocks - auto_join_text_ed: "i", // [string] auto text for past tense: "i" surfed - auto_join_text_ing: "i am", // [string] auto tense for present tense: "i was" surfing - auto_join_text_reply: "i replied to", // [string] auto tense for replies: "i replied to" @someone "with" - auto_join_text_url: "i was looking at", // [string] auto tense for urls: "i was looking at" http:... - loading_text: null, // [string] optional loading text, displayed while tweets load - query: null // [string] optional search query - }; - - if(o) $.extend(s, o); - - $.fn.extend({ - linkUrl: function() { - var returning = []; - var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi; - this.each(function() { - returning.push(this.replace(regexp,"$1")); - }); - return $(returning); - }, - linkUser: function() { - var returning = []; - var regexp = /[\@]+([A-Za-z0-9-_]+)/gi; - this.each(function() { - returning.push(this.replace(regexp,"@$1")); - }); - return $(returning); - }, - linkHash: function() { - var returning = []; - var regexp = / [\#]+([A-Za-z0-9-_]+)/gi; - this.each(function() { - returning.push(this.replace(regexp, ' #$1')); - }); - return $(returning); - }, - capAwesome: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/\b(awesome)\b/gi, '$1')); - }); - return $(returning); - }, - capEpic: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/\b(epic)\b/gi, '$1')); - }); - return $(returning); - }, - makeHeart: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/(<)+[3]/gi, "♥")); - }); - return $(returning); - } - }); - - function relative_time(time_value) { - var parsed_date = Date.parse(time_value); - var relative_to = (arguments.length > 1) ? arguments[1] : new Date(); - var delta = parseInt((relative_to.getTime() - parsed_date) / 1000); - var pluralize = function (singular, n) { - return '' + n + ' ' + singular + (n == 1 ? '' : 's'); - }; - if(delta < 60) { - return 'less than a minute ago'; - } else if(delta < (45*60)) { - return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago'; - } else if(delta < (24*60*60)) { - return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago'; - } else { - return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago'; - } - } - - function build_url() { - var proto = ('https:' == document.location.protocol ? 'https:' : 'http:'); - if (s.list) { - return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?"; - } else if (s.query == null && s.username.length == 1) { - return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?'; - } else { - var query = (s.query || 'from:'+s.username.join('%20OR%20from:')); - return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?'; - } - } - - return this.each(function(){ - var list = $('
    ').appendTo(this); - var intro = '

    '+s.intro_text+'

    '; - var outro = '

    '+s.outro_text+'

    '; - var loading = $('

    '+s.loading_text+'

    '); - - if(typeof(s.username) == "string"){ - s.username = [s.username]; - } - - if (s.loading_text) $(this).append(loading); - $.getJSON(build_url(), function(data){ - if (s.loading_text) loading.remove(); - if (s.intro_text) list.before(intro); - $.each((data.results || data), function(i,item){ - // auto join text based on verb tense and content - if (s.join_text == "auto") { - if (item.text.match(/^(@([A-Za-z0-9-_]+)) .*/i)) { - var join_text = s.auto_join_text_reply; - } else if (item.text.match(/(^\w+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+) .*/i)) { - var join_text = s.auto_join_text_url; - } else if (item.text.match(/^((\w+ed)|just) .*/im)) { - var join_text = s.auto_join_text_ed; - } else if (item.text.match(/^(\w*ing) .*/i)) { - var join_text = s.auto_join_text_ing; - } else { - var join_text = s.auto_join_text_default; - } - } else { - var join_text = s.join_text; - }; - - var from_user = item.from_user || item.user.screen_name; - var profile_image_url = item.profile_image_url || item.user.profile_image_url; - var join_template = ' '+join_text+' '; - var join = ((s.join_text) ? join_template : ' '); - var avatar_template = ''+from_user+'\'s avatar'; - var avatar = (s.avatar_size ? avatar_template : ''); - var date = ''+relative_time(item.created_at)+''; - var text = '' +$([item.text]).linkUrl().linkUser().linkHash().makeHeart().capAwesome().capEpic()[0]+ ''; - - // until we create a template option, arrange the items below to alter a tweet's display. - list.append('
  • ' + avatar + date + join + text + '
    • '); - - list.children('li:first').addClass('tweet_first'); - list.children('li:odd').addClass('tweet_even'); - list.children('li:even').addClass('tweet_odd'); - }); - if (s.outro_text) list.after(outro); - }); - - }); - }; -})(jQuery); \ No newline at end of file diff --git a/docs/source/_static/tweaks.css b/docs/source/_static/tweaks.css deleted file mode 100644 index 16cd6e76..00000000 --- a/docs/source/_static/tweaks.css +++ /dev/null @@ -1,65 +0,0 @@ -ul.todo_list { - list-style-type: none; - margin: 0; - padding: 0; -} - -ul.todo_list li { - display: block; - margin: 0; - padding: 7px 0; - border-top: 1px solid #eee; -} - -ul.todo_list li p { - display: inline; -} - -ul.todo_list li p.link { - font-weight: bold; -} - -ul.todo_list li p.details { - font-style: italic; -} - -ul.todo_list li { -} - -div.admonition { - border: 1px solid #8F1000; -} - -div.admonition p.admonition-title { - background-color: #8F1000; - border-bottom: 1px solid #8E8E8E; -} - -a { - color: #CF2F19; -} - -div.related ul li a { - color: #CF2F19; -} - -div.sphinxsidebar h4 { - background-color:#8E8E8E; - border:1px solid #255E6E; - color:white; - font-size:1em; - margin:1em 0 0.5em; - padding:0.1em 0 0.1em 0.5em; -} - -em { - font-style: normal; -} - -table.docutils { - font-size: 11px; -} - -a tt { - color:#CF2F19; -} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 63515726..edae0b8a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -144,7 +144,7 @@ html_theme = '_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static', 'images'] +html_static_path = ['static', 'images'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/docs/source/static/basic.css b/docs/source/static/basic.css new file mode 100644 index 00000000..d909ce37 --- /dev/null +++ b/docs/source/static/basic.css @@ -0,0 +1,416 @@ +/** + * Sphinx stylesheet -- basic theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +img { + border: 0; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 0; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +/* -- other body styles ----------------------------------------------------- */ + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} diff --git a/docs/source/static/default.css b/docs/source/static/default.css new file mode 100644 index 00000000..c8091ecb --- /dev/null +++ b/docs/source/static/default.css @@ -0,0 +1,230 @@ +/** + * Sphinx stylesheet -- default theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: #ffffff; + color: #000000; + padding: 0 20px 30px 20px; +} + +div.footer { + color: #ffffff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ffffff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + line-height: 30px; + color: #ffffff; +} + +div.related a { + color: #ffffff; +} + +div.sphinxsidebar { +} + +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #ffffff; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: #ffffff; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: #ffffff; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +div.body p, div.body dd, div.body li { + text-align: left; + line-height: 130%; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: left; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: #eeffcc; + color: #333333; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +} diff --git a/docs/source/static/jquery.tweet.js b/docs/source/static/jquery.tweet.js new file mode 100644 index 00000000..c93fea87 --- /dev/null +++ b/docs/source/static/jquery.tweet.js @@ -0,0 +1,154 @@ +(function($) { + + $.fn.tweet = function(o){ + var s = { + username: ["seaofclouds"], // [string] required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"] + list: null, //[string] optional name of list belonging to username + avatar_size: null, // [integer] height and width of avatar if displayed (48px max) + count: 3, // [integer] how many tweets to display? + intro_text: null, // [string] do you want text BEFORE your your tweets? + outro_text: null, // [string] do you want text AFTER your tweets? + join_text: null, // [string] optional text in between date and tweet, try setting to "auto" + auto_join_text_default: "i said,", // [string] auto text for non verb: "i said" bullocks + auto_join_text_ed: "i", // [string] auto text for past tense: "i" surfed + auto_join_text_ing: "i am", // [string] auto tense for present tense: "i was" surfing + auto_join_text_reply: "i replied to", // [string] auto tense for replies: "i replied to" @someone "with" + auto_join_text_url: "i was looking at", // [string] auto tense for urls: "i was looking at" http:... + loading_text: null, // [string] optional loading text, displayed while tweets load + query: null // [string] optional search query + }; + + if(o) $.extend(s, o); + + $.fn.extend({ + linkUrl: function() { + var returning = []; + var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi; + this.each(function() { + returning.push(this.replace(regexp,"$1")); + }); + return $(returning); + }, + linkUser: function() { + var returning = []; + var regexp = /[\@]+([A-Za-z0-9-_]+)/gi; + this.each(function() { + returning.push(this.replace(regexp,"@$1")); + }); + return $(returning); + }, + linkHash: function() { + var returning = []; + var regexp = / [\#]+([A-Za-z0-9-_]+)/gi; + this.each(function() { + returning.push(this.replace(regexp, ' #$1')); + }); + return $(returning); + }, + capAwesome: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/\b(awesome)\b/gi, '$1')); + }); + return $(returning); + }, + capEpic: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/\b(epic)\b/gi, '$1')); + }); + return $(returning); + }, + makeHeart: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/(<)+[3]/gi, "♥")); + }); + return $(returning); + } + }); + + function relative_time(time_value) { + var parsed_date = Date.parse(time_value); + var relative_to = (arguments.length > 1) ? arguments[1] : new Date(); + var delta = parseInt((relative_to.getTime() - parsed_date) / 1000); + var pluralize = function (singular, n) { + return '' + n + ' ' + singular + (n == 1 ? '' : 's'); + }; + if(delta < 60) { + return 'less than a minute ago'; + } else if(delta < (45*60)) { + return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago'; + } else if(delta < (24*60*60)) { + return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago'; + } else { + return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago'; + } + } + + function build_url() { + var proto = ('https:' == document.location.protocol ? 'https:' : 'http:'); + if (s.list) { + return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?"; + } else if (s.query == null && s.username.length == 1) { + return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?'; + } else { + var query = (s.query || 'from:'+s.username.join('%20OR%20from:')); + return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?'; + } + } + + return this.each(function(){ + var list = $('
      ').appendTo(this); + var intro = '

      '+s.intro_text+'

      '; + var outro = '

      '+s.outro_text+'

      '; + var loading = $('

      '+s.loading_text+'

      '); + + if(typeof(s.username) == "string"){ + s.username = [s.username]; + } + + if (s.loading_text) $(this).append(loading); + $.getJSON(build_url(), function(data){ + if (s.loading_text) loading.remove(); + if (s.intro_text) list.before(intro); + $.each((data.results || data), function(i,item){ + // auto join text based on verb tense and content + if (s.join_text == "auto") { + if (item.text.match(/^(@([A-Za-z0-9-_]+)) .*/i)) { + var join_text = s.auto_join_text_reply; + } else if (item.text.match(/(^\w+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+) .*/i)) { + var join_text = s.auto_join_text_url; + } else if (item.text.match(/^((\w+ed)|just) .*/im)) { + var join_text = s.auto_join_text_ed; + } else if (item.text.match(/^(\w*ing) .*/i)) { + var join_text = s.auto_join_text_ing; + } else { + var join_text = s.auto_join_text_default; + } + } else { + var join_text = s.join_text; + }; + + var from_user = item.from_user || item.user.screen_name; + var profile_image_url = item.profile_image_url || item.user.profile_image_url; + var join_template = ' '+join_text+' '; + var join = ((s.join_text) ? join_template : ' '); + var avatar_template = ''+from_user+'\'s avatar'; + var avatar = (s.avatar_size ? avatar_template : ''); + var date = ''+relative_time(item.created_at)+''; + var text = '' +$([item.text]).linkUrl().linkUser().linkHash().makeHeart().capAwesome().capEpic()[0]+ ''; + + // until we create a template option, arrange the items below to alter a tweet's display. + list.append('
    • ' + avatar + date + join + text + '
      • '); + + list.children('li:first').addClass('tweet_first'); + list.children('li:odd').addClass('tweet_even'); + list.children('li:even').addClass('tweet_odd'); + }); + if (s.outro_text) list.after(outro); + }); + + }); + }; +})(jQuery); \ No newline at end of file diff --git a/docs/source/static/tweaks.css b/docs/source/static/tweaks.css new file mode 100644 index 00000000..16cd6e76 --- /dev/null +++ b/docs/source/static/tweaks.css @@ -0,0 +1,65 @@ +ul.todo_list { + list-style-type: none; + margin: 0; + padding: 0; +} + +ul.todo_list li { + display: block; + margin: 0; + padding: 7px 0; + border-top: 1px solid #eee; +} + +ul.todo_list li p { + display: inline; +} + +ul.todo_list li p.link { + font-weight: bold; +} + +ul.todo_list li p.details { + font-style: italic; +} + +ul.todo_list li { +} + +div.admonition { + border: 1px solid #8F1000; +} + +div.admonition p.admonition-title { + background-color: #8F1000; + border-bottom: 1px solid #8E8E8E; +} + +a { + color: #CF2F19; +} + +div.related ul li a { + color: #CF2F19; +} + +div.sphinxsidebar h4 { + background-color:#8E8E8E; + border:1px solid #255E6E; + color:white; + font-size:1em; + margin:1em 0 0.5em; + padding:0.1em 0 0.1em 0.5em; +} + +em { + font-style: normal; +} + +table.docutils { + font-size: 11px; +} + +a tt { + color:#CF2F19; +} \ No newline at end of file -- cgit From 8d695b83df68367be9172f0659a90a844680039b Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 30 Jan 2012 20:22:34 +0000 Subject: removing unused images, cleaning up RST in docstrings from sphinx warnings --- docs/source/configuration.rst | 36 ++-- docs/source/images/305.svg | 158 ----------------- docs/source/images/both.svg | 135 --------------- docs/source/images/graphs_delegate_accept.svg | 52 ------ docs/source/images/graphs_separate.svg | 30 ---- docs/source/images/graphs_standard_accept.svg | 51 ------ docs/source/images/graphs_standard_reject.svg | 39 ----- docs/source/images/graphs_together.svg | 24 --- docs/source/images/layouts.svg | 215 ----------------------- docs/source/images/mapper.svg | 237 ------------------------- docs/source/images/proxyAuth.svg | 238 -------------------------- 11 files changed, 21 insertions(+), 1194 deletions(-) delete mode 100644 docs/source/images/305.svg delete mode 100644 docs/source/images/both.svg delete mode 100644 docs/source/images/graphs_delegate_accept.svg delete mode 100644 docs/source/images/graphs_separate.svg delete mode 100644 docs/source/images/graphs_standard_accept.svg delete mode 100644 docs/source/images/graphs_standard_reject.svg delete mode 100644 docs/source/images/graphs_together.svg delete mode 100644 docs/source/images/layouts.svg delete mode 100644 docs/source/images/mapper.svg delete mode 100644 docs/source/images/proxyAuth.svg (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 410e7b1b..782e9fb5 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -31,7 +31,7 @@ initializing data into keystone using the command line client. Keystone Configuration File =========================== -The keystone configuration file is an 'ini' file format with sections, +The keystone configuration file is an 'ini' file format with sections, extended from Paste_, a common system used to configure python WSGI based applications. In addition to the paste config entries, general configuration values are stored under [DEFAULT] and [sql], and then drivers for the various @@ -44,7 +44,7 @@ The driver sections include: * ``[policy]`` - the python module that drives the policy system for RBAC * ``[ec2]`` - the python module providing the EC2 translations for OpenStack -The keystone configuration file is expected to be named ``keystone.conf``. +The keystone configuration file is expected to be named ``keystone.conf``. When starting up Keystone, you can specify a different configuration file to use with ``--config-file``. If you do **not** specify a configuration file, keystone will look in the following directories for a configuration file, in @@ -57,7 +57,7 @@ order: Logging is configured externally to the rest of keystone, the file specifying the logging configuration is in the [DEFAULT] section of the keystone conf -file under ``log_config``. If you wish to route all your logging through +file under ``log_config``. If you wish to route all your logging through syslog, there is a ``use_syslog`` option also in the [DEFAULT] section that easy. @@ -81,20 +81,26 @@ Sample Configuration Files Initializing Keystone ===================== -Keystone must be running in order to initialize data within it. This is because -the keystone-manage commands are all used the same REST API that other +Keystone must be running in order to initialize data within it. This is +because the keystone-manage commands are all used the same REST API that other OpenStack systems utilize. General keystone-manage options: -------------------------------- * ``--id-only`` : causes ``keystone-manage`` to return only the UUID result -from the API call. -* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' + from the API call. + +* ``--endpoint`` : allows you to specify the keystone endpoint to communicate + with. The default endpoint is http://localhost:35357/v2.0' + * ``--auth-token`` : provides the authorization token -``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command -``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: +``keystone-manage`` is set up to expect commands in the general form of +``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to +provide additional information to the command. For example, the command +``tenant`` has the subcommand ``create``, which takes the required keyword +``tenant_name``:: keystone-manage tenant create tenant_name=example_tenant @@ -137,7 +143,7 @@ creates a tenant named "admin". keyword arguments * tenant_id - + example:: keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 @@ -169,14 +175,14 @@ keyword arguments * name * password * email - + example:: keystone-manage user --ks-id-only create \ name=admin \ password=secrete \ email=admin@example.com - + ``user delete`` ^^^^^^^^^^^^^^^ @@ -199,7 +205,7 @@ keyword arguments ``user update_password`` ^^^^^^^^^^^^^^^^^^^^^^^^ - + keyword arguments ``user update_tenant`` @@ -220,7 +226,7 @@ keyword arguments exmaple:: keystone-manage role --ks-id-only create name=Admin - + ``role add_user_to_tenant`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -236,7 +242,7 @@ example:: role_id=19d1d3344873464d819c45f521ff9890 \ user_id=08741d8ed88242ca88d1f61484a0fe3b \ tenant_id=20601a7f1d94447daa4dff438cb1c209 - + ``role remove_user_from_tenant`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/images/305.svg b/docs/source/images/305.svg deleted file mode 100644 index 7d79464e..00000000 --- a/docs/source/images/305.svg +++ /dev/null @@ -1,158 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - Request - service directly - - - Auth - Component - 305 - Use proxy to - redirect to Auth - - - - - - - OpenStack - Service - - - diff --git a/docs/source/images/both.svg b/docs/source/images/both.svg deleted file mode 100644 index d29872a4..00000000 --- a/docs/source/images/both.svg +++ /dev/null @@ -1,135 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - Auth - Component - - Auth - Component - - - OpenStack - Service - - - - - diff --git a/docs/source/images/graphs_delegate_accept.svg b/docs/source/images/graphs_delegate_accept.svg deleted file mode 100644 index 1d86cadf..00000000 --- a/docs/source/images/graphs_delegate_accept.svg +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - -DelegateAcceptAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp->Start - - -200 Okay - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U -X-Identity-Status: Confirmed - - -Service->AuthComp - - -200 Okay - - - diff --git a/docs/source/images/graphs_separate.svg b/docs/source/images/graphs_separate.svg deleted file mode 100644 index 376e5988..00000000 --- a/docs/source/images/graphs_separate.svg +++ /dev/null @@ -1,30 +0,0 @@ - - - - - - -Seperate - - -AuthComp - -Auth -Component - - -Service - -OpenStack -Service - - -AuthComp->Service - - - - - diff --git a/docs/source/images/graphs_standard_accept.svg b/docs/source/images/graphs_standard_accept.svg deleted file mode 100644 index bddf4b5f..00000000 --- a/docs/source/images/graphs_standard_accept.svg +++ /dev/null @@ -1,51 +0,0 @@ - - - - - - -StandardAcceptAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp->Start - - -200 Okay - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U - - -Service->AuthComp - - -200 Okay - - - diff --git a/docs/source/images/graphs_standard_reject.svg b/docs/source/images/graphs_standard_reject.svg deleted file mode 100644 index 6020ad67..00000000 --- a/docs/source/images/graphs_standard_reject.svg +++ /dev/null @@ -1,39 +0,0 @@ - - - - - - -StandardRejectAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic Yjpw - - -AuthComp->Start - - -401 Unauthorized -WWW-Authenticate: Basic Realm="API Realm" - - -Service - -OpenStack -Service - - - diff --git a/docs/source/images/graphs_together.svg b/docs/source/images/graphs_together.svg deleted file mode 100644 index 1425a28b..00000000 --- a/docs/source/images/graphs_together.svg +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -Together - - -Together - - -Auth -Component - - -OpenStack -Service - - - diff --git a/docs/source/images/layouts.svg b/docs/source/images/layouts.svg deleted file mode 100644 index fdf61b7d..00000000 --- a/docs/source/images/layouts.svg +++ /dev/null @@ -1,215 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - Auth - Component - - - OpenStack - Service - - - Option - ( - b - ) - - - Auth - Component - - - OpenStack - Service - Option - ( - a - ) - - - - diff --git a/docs/source/images/mapper.svg b/docs/source/images/mapper.svg deleted file mode 100644 index b5a2b7b1..00000000 --- a/docs/source/images/mapper.svg +++ /dev/null @@ -1,237 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - OpenStack - Service - - - - - - - - - - - - - - - Mapper - - - Auth - 1 - - - Auth - 2 - - - Auth - 3 - - - - - diff --git a/docs/source/images/proxyAuth.svg b/docs/source/images/proxyAuth.svg deleted file mode 100644 index f60b40d8..00000000 --- a/docs/source/images/proxyAuth.svg +++ /dev/null @@ -1,238 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - Authorization - : - Basic dTpw - X - - - Authorization - : - Proxy U - Authorization - : - Basic VTpQ - 500 - Internal Error - 403 - Proxy Unauthorized - - - - - Auth - Component - - - - - OpenStack - Service - - - - - - - -- cgit