2
Copyright 2011-2012 OpenStack, LLC
5
Licensed under the Apache License, Version 2.0 (the "License"); you may
6
not use this file except in compliance with the License. You may obtain
7
a copy of the License at
9
http://www.apache.org/licenses/LICENSE-2.0
11
Unless required by applicable law or agreed to in writing, software
12
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
License for the specific language governing permissions and limitations
21
Extensions support adding features and functions to OpenStack APIs at any time, without prior
22
approval or waiting for a new API and release cycles.
24
The extension framework is in development and documented in extensions_ and extensionspresentation_.
26
This document describes the extensions included with Keystone, how to enable and disable them,
27
and briefly touches on how to write your own extensions.
29
.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html
30
.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions
35
Keystone ships with a number of extensions found under the
36
``keystone/contib/extensions`` folder.
38
The following built-in extensions are included:
42
This is an extensions that supports managing users, tenants, and roles
43
through the API. Without this extensions, the ony way to manage those
44
objects is through keystone-manage or directly in the underlying database.
46
This is an Admin API extension only.
50
This extensions supports managing Endpoints and prrovides the Endpoint
51
Template mechanism for managing bulk endpoints.
53
This is an Admin API extension only.
57
This extension adds support for EC2 credentials.
59
This is an Admin and Service API extension.
63
This extension adds functionality the enables groups.
65
This is an Admin and Service API extension.
69
This extensions adds support for authentication with an API Key (the core
70
Keystone API only supports username/password credentials)
72
This is an Admin and Service API extension.
76
This extension adds capability to filter roles with optional service IDs
77
for token validation to mitigate security risks with role name conflicts.
78
See https://bugs.launchpad.net/keystone/+bug/890411 for more details.
80
This is an Admin API extension. Applicable to validate token (GET)
81
and check token (HEAD) APIs only.
85
This extensions supports admin calls to /tokens without having to specify
86
the token ID in the URL. Instead, the ID is supplied in a header called
87
X-Subject-Token. This is provided as an alternative to address any security
88
concerns that arise when token IDs are passed as part of the URL which is
89
often (and by default) logged to insecure media.
91
This is an Admin API extension only.
95
The included extensions are in the process of being rewritten. Currently
96
osksadm, oskscatalog, hpidm, and osksvalidate work with this new
100
Enabling & Disabling Extensions
101
-------------------------------
103
The Keystone conf file has a property called extensions. This property holds
104
the list of supported extensions that you want enabled. If you want to
105
add/remove an extension from being supported, add/remove the extension key
106
from this property. The key is the name of the folder of the extension
107
under the keystone/contrib/extensions folder.
111
If you want to load different extensions in the service API than the Admin API
112
you need to use different config files.
114
Creating New Extensions
115
-----------------------
117
#. **Adopt a unique organization abbreviation.**
119
This prefix should uniquely identify your organization within the community.
120
The goal is to avoid schema and resource collisions with similiar extensions.
121
(e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard)
123
#. **Adopt a unique extension abbreviation.**
125
Select an abbreviation to identify your extension, and append to
126
your organization prefix using a hyphen (``-``), by convention
127
(e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension).
129
This combination is referred to as your extension's prefix.
131
#. **Determine the scope of your extension.**
133
Extensions can enhance the Admin API, Service API or both.
135
#. **Create a new module.**
137
Create a module to isolate your namespace based on the extension prefix
140
keystone/contrib/extensions/admin
144
keystone/contrib/extensions/service/
146
... based on which API you are enhancing.
150
In the future, we will support loading external extensions.
152
#. Add static extension files for JSON (``*.json``) and XML
153
(``*.xml``) to the new extension module.
155
Refer to `Service Guide <https://github.com/openstack/keystone/blob/master/keystone/content/admin/identityadminguide.pdf?raw=true>`_
156
`Sample extension XML <https://github.com/openstack/keystone/blob/master/keystone/content/common/samples/extension.json>`_
157
`Sample extension JSON <https://github.com/openstack/keystone/blob/master/keystone/content/common/samples/extension.xml>`_ for the the content and structure.
159
#. If your extension is adding additional methods override the base class
160
``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods.
162
#. **Document your work.**
164
Provide documentation to support your extension.
166
Extensions documentation, WADL, and XSD files can be stored in the
167
``keystone/content`` folder.
169
#. Add your extension name to the list of supported extensions in The
170
``keystone.conf`` file.
172
Which extensions are enabled?
173
-----------------------------
175
Discover which extensions are available (service API)::
177
curl http://localhost:5000/v2.0/extensions
181
curl http://localhost:35357/v2.0/extensions
183
The response will list the extensions available.
added
removed
doc/source/old/extensions.rst
