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') 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