Debian Codegraph @

src/lazr/restfulclient/docs/authorizer.standalone.rst

raw
1 Authorizers
2 ===========
3
4 Authorizers are objects that encapsulate knowledge about a particular
5 web service's authentication scheme. lazr.restfulclient includes
6 authorizers for common HTTP authentication schemes.
7
8 The BasicHttpAuthorizer
9 -----------------------
10
11 This authorizer handles HTTP Basic Auth. To test it, we'll create a
12 fake web service that serves some sample WADL.
13
14 >>> import pkg_resources
15 >>> wadl_string = pkg_resources.resource_string(
16 ... 'wadllib.tests.data', 'launchpad-wadl.xml')
17
18 >>> responses = { 'application/vnd.sun.wadl+xml' : wadl_string,
19 ... 'application/json' : '{}' }
20
21 >>> def sample_application(environ, start_response):
22 ... media_type = environ['HTTP_ACCEPT']
23 ... content = responses[media_type]
24 ... start_response(
25 ... '200', [('Content-type', media_type)])
26 ... return [content]
27
28
29 The WADL file will be protected with HTTP Basic Auth. To access it,
30 you'll need to provide a username of "user" and a password of
31 "password".
32
33 >>> def authenticate(username, password):
34 ... """Accepts "user/password", rejects everything else.
35 ...
36 ... :return: The username, if the credentials are valid.
37 ... None, otherwise.
38 ... """
39 ... if username == "user" and password == "password":
40 ... return username
41 ... return None
42
43 >>> from lazr.authentication.wsgi import BasicAuthMiddleware
44 >>> def protected_application():
45 ... return BasicAuthMiddleware(
46 ... sample_application, authenticate_with=authenticate)
47
48 Finally, we'll set up a WSGI intercept so that we can test the web
49 service by making HTTP requests to http://api.launchpad.dev/. (This is
50 the hostname mentioned in the WADL file.)
51
52 >>> import wsgi_intercept
53 >>> from wsgi_intercept.httplib2_intercept import install
54 >>> install()
55 >>> wsgi_intercept.add_wsgi_intercept(
56 ... 'api.launchpad.dev', 80, protected_application)
57
58 With no HttpAuthorizer, a ServiceRoot can't get access to the web service.
59
60 >>> from lazr.restfulclient.resource import ServiceRoot
61 >>> client = ServiceRoot(None, "http://api.launchpad.dev/")
62 Traceback (most recent call last):
63 ...
64 Unauthorized: HTTP Error 401: Unauthorized
65 ...
66
67 We can't get access if the authorizer doesn't have the right
68 credentials.
69
70 >>> from lazr.restfulclient.authorize import BasicHttpAuthorizer
71
72 >>> bad_authorizer = BasicHttpAuthorizer("baduser", "badpassword")
73 >>> client = ServiceRoot(bad_authorizer, "http://api.launchpad.dev/")
74 Traceback (most recent call last):
75 ...
76 Unauthorized: HTTP Error 401: Unauthorized
77 ...
78
79 If we provide the right credentials, we can retrieve the WADL. We'll
80 still get an exception, because our fake web service is too fake for
81 ServiceRoot--its 'service root' resource doesn't match the WADL--but
82 we're able to make HTTP requests without getting 401 errors.
83
84 Note that the HTTP request includes the User-Agent header, but that
85 that header contains no special information about the authorization
86 method. This will change when the authorization method is OAuth.
87
88 >>> import httplib2
89 >>> httplib2.debuglevel = 1
90
91 >>> authorizer = BasicHttpAuthorizer("user", "password")
92 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
93 send: 'GET / ...user-agent: lazr.restfulclient ...'
94 ...
95
96
97 The BasicHttpAuthorizer allows you to adds proper basic auth headers to the
98 request, when asked to, using the username and password information it already
99 knows about.
100
101 >>> headers = {}
102 >>> authorizer.authorizeRequest('/', 'GET', '', headers)
103 >>> headers.get('authorization')
104 'Basic dXNlcjpwYXNzd29yZA=='
105
106 Teardown.
107
108 >>> httplib2.debuglevel = 0
109 >>> _ = wsgi_intercept.remove_wsgi_intercept("api.launchpad.dev", 80)
110
111
112 The OAuthAuthorizer
113 -------------------
114
115 This authorizer handles OAuth authorization. To test it, we'll protect
116 the sample application with a piece of OAuth middleware. The middleware
117 will accept only one consumer/token combination, though it will also
118 allow anonymous access: if you pass in an empty token and secret,
119 you'll get a lower level of access.
120
121 >>> from oauth.oauth import OAuthConsumer, OAuthToken
122 >>> valid_consumer = OAuthConsumer("consumer", '')
123 >>> valid_token = OAuthToken("token", "secret")
124 >>> empty_token = OAuthToken("", "")
125
126 Our authenticate() implementation checks against the one valid
127 consumer and token.
128
129 >>> def authenticate(consumer, token, parameters):
130 ... """Accepts the valid consumer and token, rejects everything else.
131 ...
132 ... :return: The consumer, if the credentials are valid.
133 ... None, otherwise.
134 ... """
135 ... if token.key == '' and token.secret == '':
136 ... # Anonymous access.
137 ... return consumer
138 ... if consumer == valid_consumer and token == valid_token:
139 ... return consumer
140 ... return None
141
142 Our data store helps the middleware look up consumer and token objects
143 from the information provided in a signed OAuth request.
144
145 >>> from lazr.authentication.testing.oauth import SimpleOAuthDataStore
146
147 >>> class AnonymousAccessDataStore(SimpleOAuthDataStore):
148 ... """A data store that will accept any consumer."""
149 ... def lookup_consumer(self, consumer):
150 ... """If there's no matching consumer, just create one.
151 ...
152 ... This will let anonymous requests succeed with any
153 ... consumer key."""
154 ... consumer = super(
155 ... AnonymousAccessDataStore, self).lookup_consumer(
156 ... consumer)
157 ... if consumer is None:
158 ... consumer = OAuthConsumer(consumer, '')
159 ... return consumer
160
161 >>> data_store = AnonymousAccessDataStore(
162 ... {valid_consumer.key : valid_consumer},
163 ... {valid_token.key : valid_token,
164 ... empty_token.key : empty_token})
165
166 Now we're ready to protect the sample_application with OAuthMiddleware,
167 using our authenticate() implementation and our data store.
168
169 >>> from lazr.authentication.wsgi import OAuthMiddleware
170 >>> def protected_application():
171 ... return OAuthMiddleware(
172 ... sample_application, realm="OAuth test",
173 ... authenticate_with=authenticate, data_store=data_store)
174 >>> wsgi_intercept.add_wsgi_intercept(
175 ... 'api.launchpad.dev', 80, protected_application)
176
177 Let's try out some clients. As you'd expect, you can't get through the
178 middleware with no HTTPAuthorizer at all.
179
180 >>> from lazr.restfulclient.authorize.oauth import OAuthAuthorizer
181 >>> client = ServiceRoot(None, "http://api.launchpad.dev/")
182 Traceback (most recent call last):
183 ...
184 Unauthorized: HTTP Error 401: Unauthorized
185 ...
186
187 Invalid credentials are also no help.
188
189 >>> authorizer = OAuthAuthorizer(
190 ... valid_consumer.key, access_token=OAuthToken("invalid", "token"))
191 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
192 Traceback (most recent call last):
193 ...
194 Unauthorized: HTTP Error 401: Unauthorized
195 ...
196
197 But valid credentials work fine (again, up to the point at which
198 lazr.restfulclient runs against the limits of this simple web
199 service). Note that the User-Agent header mentions the consumer key.
200
201 >>> httplib2.debuglevel = 1
202 >>> authorizer = OAuthAuthorizer(
203 ... valid_consumer.key, access_token=valid_token)
204 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
205 send: 'GET /...user-agent: lazr.restfulclient...; oauth_consumer="consumer"...'
206 ...
207
208 If the OAuthAuthorizer is created with an application name as well as
209 a consumer key, the application name is mentioned in the User-Agent
210 header as well.
211
212 >>> authorizer = OAuthAuthorizer(
213 ... valid_consumer.key, access_token=valid_token,
214 ... application_name="the app")
215 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
216 send: 'GET /...user-agent: lazr.restfulclient...; application="the app"; oauth_consumer="consumer"...'
217 ...
218
219 >>> httplib2.debuglevel = 0
220
221 It's even possible to get anonymous access by providing an empty
222 access token.
223
224 >>> authorizer = OAuthAuthorizer(
225 ... valid_consumer.key, access_token=empty_token)
226 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
227
228 Because of the way the AnonymousAccessDataStore (defined
229 earlier in the test) works, you can even get anonymous access by
230 specifying an OAuth consumer that's not in the server-side list of
231 valid consumers.
232
233 >>> authorizer = OAuthAuthorizer(
234 ... "random consumer", access_token=empty_token)
235 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
236
237 A ServiceRoot object has a 'credentials' attribute which contains the
238 Authorizer used to authorize outgoing requests.
239
240 >>> from lazr.restfulclient.resource import ServiceRoot
241 >>> root = ServiceRoot(authorizer, "http://api.launchpad.dev/")
242 >>> root.credentials
243 <lazr.restfulclient.authorize.oauth.OAuthAuthorizer object...>
244
245 If you try to provide credentials with an unrecognized OAuth consumer,
246 you'll get an error--even if the credentials are valid. The data store
247 used in this test only lets unrecognized OAuth consumers through when
248 they request anonymous access.
249
250 >>> authorizer = OAuthAuthorizer(
251 ... 'random consumer', access_token=valid_token)
252 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
253 Traceback (most recent call last):
254 ...
255 Unauthorized: HTTP Error 401: Unauthorized
256 ...
257
258 >>> authorizer = OAuthAuthorizer(
259 ... 'random consumer', access_token=OAuthToken("invalid", "token"))
260 >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
261 Traceback (most recent call last):
262 ...
263 Unauthorized: HTTP Error 401: Unauthorized
264 ...
265
266 Teardown.
267
268 >>> _ = wsgi_intercept.remove_wsgi_intercept("api.launchpad.dev", 80)