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
The Keystone middleware sits in front of an OpenStack service and handles authenticating
22
incoming requests. The middleware was designed according to `this spec`.
24
The middleware is found in source under Keystone/middleware.
26
The middleware supports two interfaces; WSGI and REST/HTTP.
28
.. _`this spec`: http://wiki.openstack.org/openstack-authn
33
If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per
34
HTTP standards, it will also return a WWW-Authenticate header informing the caller
35
of what protocols are supported. For Keystone authentication, the response syntax will be::
37
WWW-Authenticate: Keystone uri="url to Keystone server"
39
The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token.
41
The token is passed in using ther X-Auth-Token header.
46
Upon successful authentication the middleware sends the following
47
headers to the downstream WSGI app:
50
Provides information on whether the request was authenticated or not.
53
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.
56
The unique, immutable tenant Id
59
The unique, but mutable (it can change) tenant name.
62
The user id of the user used to log in
65
The username used to log in
68
The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants.
71
The roles associated with that user
77
The middleware is configured within the config file of the main application as
78
a WSGI component. Example for the auth_token middleware::
81
paste.app_factory = myService:app_factory
89
paste.filter_factory = keystone.middleware.auth_token:filter_factory
93
auth_uri = http://127.0.0.1:5000/
94
admin_token = 999888777666
95
;Uncomment next line and check ip:port to use memcached to cache token requests
96
;memcache_hosts = 127.0.0.1:11211
98
*The required configuration entries are:*
101
The IP address or DNS name of the Keystone server
104
The TCP/IP port of the Keystone server
107
The protocol of the Keystone server ('http' or 'https')
110
The externally accessible URL of the Keystone server. This will be where unauthenticated
111
clients are redirected to. This is in the form of a URL. For example, if they make an
112
unauthenticated call, they get this response::
114
HTTP/1.1 401 Unauthorized
115
Www-Authenticate: Keystone uri='https://auth.example.com/'
118
In this case, the auth_uri setting is set to https://auth.example.com/
121
This is the long-lived token issued to the service to authenticate itself when calling
122
Keystone. See :doc:`configuration` for more information on setting this up.
125
*Optional parameters are:*
128
Whether the middleware should reject invalid or unauthenticated calls directly or not. If not,
129
it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS
130
header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the
131
service can then decide if it wants to honor the call or not. This is useful if the service offers
132
some resources publicly, for example.
135
The amount of time to wait before timing out a call to Keystone (in seconds)
138
This is used to point to a memcached server (in ip:port format). If supplied,
139
the middleware will cache tokens and data retrieved from Keystone in memcached
140
to minimize calls made to Keystone and optimize performance.
143
Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone,
144
the service will not know and will continue to honor the token as it has them stored in memcached.
145
Also note that tokens and data stored in memcached are not encrypted. The memcached server must
146
be trusted and on a secure network.
149
*Parameters needed in a distributed topology.* In this configuration, the middleware is running
150
on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture`
151
for details on different deployment topologies):
154
The IP address or DNS name of the location of the service (since it is remote
155
and not automatically down the WSGI chain)
158
The TCP/IP port of the remote service.
161
The protocol of the service ('http' or 'https')
164
The basic auth password used to authenticate to the service (so the service
165
knows the call is coming from a server that has validated the token and not from
166
an untrusted source or spoofer)
169
The amount of time to wait for the service to respond before timing out.
added
removed
doc/source/old/middleware.rst
