1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
..
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.
========
HTTP API
========
Specifications
==============
Keystone implements two major HTTP API versions, along with several API
extensions that build on top of each core API. The two APIs are specified as
`Identity API v2.0`_ and `Identity API v3`_. Each API is specified by a single
source of truth to avoid conflicts between documentation and implementation.
The original source of truth for the v2.0 API is defined by a set of WADL and
XSD files. The original source of truth for the v3 API is defined by
documentation.
.. _`Identity API v2.0`: https://github.com/openstack/identity-api/tree/master/v2.0/src
.. _`Identity API v3`: https://github.com/openstack/identity-api/tree/master/v3/src/markdown
History
=======
You're probably wondering why Keystone does not implement a "v1" API. As a
matter of fact, one exists, but it actually predates OpenStack. The v1.x API
was an extremely small API documented and implemented by Rackspace for their
early public cloud products.
With the advent of OpenStack, Keystone served to provide a superset of the
authentication and multi-tenant authorization models already implemented by
Rackspace's public cloud, Nova, and Swift. Thus, Identity API v2.0 was
introduced.
Identity API v3 was established to introduce namespacing for users and projects
by using "domains" as a higher-level container for more flexible identity
management and fixed a security issue in the v2.0 API (bearer tokens appearing
in URLs).
Should I use v2.0 or v3?
========================
Identity API v3.
Identity API v3 is a superset of all the functionality available in v2.0 and
several of its extensions, and provides a much more consistent developer
experience to boot. We're also on the road to deprecating, and ultimately
reducing (or dropping) support for, Identity API v2.0.
How do I migrate from v2.0 to v3?
=================================
I am a deployer
---------------
You'll need to ensure the v3 API is included in your Paste pipeline, usually
``etc/keystone-paste.ini``. Our `latest sample configuration`_ includes the v3
application pipeline.
First define a v3 application, which refers to the v3 application factory
method:
.. code-block:: ini
[app:service_v3]
paste.app_factory = keystone.service:v3_app_factory
Then define a v3 pipeline, which terminates with the v3 application you defined
above:
.. code-block:: ini
[app:app_v3]
pipeline = ... service_v3
Replace "..." with whatever middleware you'd like to run in front of the API
service. Our `latest sample configuration`_ documents our tested
recommendations, but your requirements may vary.
Finally, include the v3 pipeline in at least one ``composite`` application (but
usually both ``[composite:main]`` and ``[composite:admin]``), for example:
.. code-block:: ini
[composite:main]
use = egg:Paste#urlmap
/v3 = api_v3
...
Once your pipeline is configured to expose both v2.0 and v3, you need to ensure
that you've configured your service catalog in Keystone correctly. The
simplest, and most ideal, configuration would expose one identity with
unversioned endpoints (note the lack of ``/v2.0/`` or ``/v3/`` in these URLs):
- Service (type: ``identity``)
- Endpoint (interface: ``public``, URL: ``http://identity:5000/``)
- Endpoint (interface: ``admin``, URL: ``http://identity:35357/``)
If you were to perform a ``GET`` against either of these endpoints, you would
be greeted by an ``HTTP/1.1 300 Multiple Choices`` response, which newer
Keystone clients can use to automatically detect available API versions.
.. code-block:: bash
$ curl -i http://identity:35357/
HTTP/1.1 300 Multiple Choices
Vary: X-Auth-Token
Content-Type: application/json
Content-Length: 755
Date: Tue, 10 Jun 2014 14:22:26 GMT
{"versions": {"values": [ ... ]}}
With unversioned ``identity`` endpoints in the service catalog, you should be
able to `authenticate with keystoneclient`_ successfully.
.. _`latest sample configuration`: https://github.com/openstack/keystone/blob/master/etc/keystone-paste.ini
.. _`authenticate with keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/using-api-v3.html#authenticating
I have a Python client
----------------------
The Keystone community provides first-class support for Python API consumers
via our client library, `python-keystoneclient`_. If you're not currently using
this library, you should, as it is intended to expose all of our HTTP API
functionality. If we're missing something you're looking for, please
contribute!
Adopting `python-keystoneclient`_ should be the easiest way to migrate to
Identity API v3.
.. _`python-keystoneclient`: https://pypi.python.org/pypi/python-keystoneclient/
I have a non-Python client
--------------------------
You'll likely need to heavily reference our `API documentation`_ to port your
application to Identity API v3.
.. _`API documentation`: https://github.com/openstack/identity-api/blob/master/v3/src/markdown/identity-api-v3.md
The most common operation would be password-based authentication including a
tenant name (i.e. project name) to specify an authorization scope. In Identity
API v2.0, this would be a request to ``POST /v2.0/tokens``:
.. code-block:: javascript
{
"auth": {
"passwordCredentials": {
"password": "my-password",
"username": "my-username"
},
"tenantName": "project-x"
}
}
And you would get back a JSON blob with an ``access`` -> ``token`` -> ``id``
that you could pass to another web service as your ``X-Auth-Token`` header
value.
In Identity API v3, an equivalent request would be to ``POST /v3/auth/tokens``:
.. code-block:: javascript
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"domain": {
"id": "default"
},
"name": "my-username",
"password": "my-password"
}
}
},
"scope": {
"project": {
"domain": {
"id": "default"
},
"name": "project-x"
}
}
}
}
Note a few key differences when compared to the v2.0 API:
- A "tenant" in v2.0 became a "project" in v3.
- The authentication method (``password``) is explicitly identified.
- Both the user name (``my-username``) and project name (``project-x``) are
namespaced by an owning domain (where ``id`` = ``default``). The "default"
domain exists by default in Keystone, and automatically owns the namespace
exposed by Identity API v2.0. Alternatively, you may reference users and
projects that exist outside the namespace of the default domain, which are
thus inaccessible to the v2.0 API.
- In v3, your token is returned to you in an ``X-Subject-Token`` header,
instead of as part of the request body. You should still authenticate
yourself to other services using the ``X-Auth-Token`` header.
HTTP/1.1 Chunked Encoding
=========================
.. WARNING::
Running Keystone under HTTPD in the recommended (and tested) configuration does not support
the use of ``Transfer-Encoding: chunked``. This is due to a limitation with the WSGI spec
and the implementation used by ``mod_wsgi``. Support for chunked encoding under ``eventlet``
may or may not continue. It is recommended that all clients assume Keystone will not support
``Transfer-Encoding: chunked``.
|
