Vehicle-cpp/hkpc/software/lazr/restfulclient/docs/authorizer.standalone.rst

Authorizers
===========

Authorizers are objects that encapsulate knowledge about a particular
web service's authentication scheme. lazr.restfulclient includes
authorizers for common HTTP authentication schemes.

The BasicHttpAuthorizer
-----------------------

This authorizer handles HTTP Basic Auth. To test it, we'll create a
fake web service that serves some sample WADL.

    >>> import pkg_resources
    >>> wadl_string = pkg_resources.resource_string(
    ...     'wadllib.tests.data', 'launchpad-wadl.xml')

    >>> responses = { 'application/vnd.sun.wadl+xml' : wadl_string,
    ...               'application/json' : '{}' }

    >>> def sample_application(environ, start_response):
    ...     media_type = environ['HTTP_ACCEPT']
    ...     content = responses[media_type]
    ...     start_response(
    ...         '200', [('Content-type', media_type)])
    ...     return [content]


The WADL file will be protected with HTTP Basic Auth. To access it,
you'll need to provide a username of "user" and a password of
"password".

    >>> def authenticate(username, password):
    ...     """Accepts "user/password", rejects everything else.
    ...
    ...     :return: The username, if the credentials are valid.
    ...              None, otherwise.
    ...     """
    ...     if username == "user" and password == "password":
    ...         return username
    ...     return None

    >>> from lazr.authentication.wsgi import BasicAuthMiddleware
    >>> def protected_application():
    ...     return BasicAuthMiddleware(
    ...         sample_application, authenticate_with=authenticate)

Finally, we'll set up a WSGI intercept so that we can test the web
service by making HTTP requests to http://api.launchpad.dev/. (This is
the hostname mentioned in the WADL file.)

    >>> import wsgi_intercept
    >>> from wsgi_intercept.httplib2_intercept import install
    >>> install()
    >>> wsgi_intercept.add_wsgi_intercept(
    ...     'api.launchpad.dev', 80, protected_application)

With no HttpAuthorizer, a ServiceRoot can't get access to the web service.

    >>> from lazr.restfulclient.resource import ServiceRoot
    >>> client = ServiceRoot(None, "http://api.launchpad.dev/")
    Traceback (most recent call last):
    ...
    Unauthorized: HTTP Error 401: Unauthorized
    ...

We can't get access if the authorizer doesn't have the right
credentials.

    >>> from lazr.restfulclient.authorize import BasicHttpAuthorizer

    >>> bad_authorizer = BasicHttpAuthorizer("baduser", "badpassword")
    >>> client = ServiceRoot(bad_authorizer, "http://api.launchpad.dev/")
    Traceback (most recent call last):
    ...
    Unauthorized: HTTP Error 401: Unauthorized
    ...

If we provide the right credentials, we can retrieve the WADL. We'll
still get an exception, because our fake web service is too fake for
ServiceRoot--its 'service root' resource doesn't match the WADL--but
we're able to make HTTP requests without getting 401 errors.

Note that the HTTP request includes the User-Agent header, but that
that header contains no special information about the authorization
method. This will change when the authorization method is OAuth.

    >>> import httplib2
    >>> httplib2.debuglevel = 1

    >>> authorizer = BasicHttpAuthorizer("user", "password")
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
    send: 'GET / ...user-agent: lazr.restfulclient ...'
    ...


The BasicHttpAuthorizer allows you to adds proper basic auth headers to the
request, when asked to, using the username and password information it already
knows about.

    >>> headers = {}
    >>> authorizer.authorizeRequest('/', 'GET', '', headers)
    >>> headers.get('authorization')
    'Basic dXNlcjpwYXNzd29yZA=='

Teardown.

    >>> httplib2.debuglevel = 0
    >>> _ = wsgi_intercept.remove_wsgi_intercept("api.launchpad.dev", 80)


The OAuthAuthorizer
-------------------

This authorizer handles OAuth authorization. To test it, we'll protect
the sample application with a piece of OAuth middleware. The middleware
will accept only one consumer/token combination, though it will also
allow anonymous access: if you pass in an empty token and secret,
you'll get a lower level of access.

    >>> from oauth.oauth import OAuthConsumer, OAuthToken
    >>> valid_consumer = OAuthConsumer("consumer", '')
    >>> valid_token = OAuthToken("token", "secret")
    >>> empty_token = OAuthToken("", "")

Our authenticate() implementation checks against the one valid
consumer and token.

    >>> def authenticate(consumer, token, parameters):
    ...     """Accepts the valid consumer and token, rejects everything else.
    ...
    ...     :return: The consumer, if the credentials are valid.
    ...              None, otherwise.
    ...     """
    ...     if token.key == '' and token.secret == '':
    ...         # Anonymous access.
    ...         return consumer
    ...     if consumer == valid_consumer and token == valid_token:
    ...         return consumer
    ...     return None

Our data store helps the middleware look up consumer and token objects
from the information provided in a signed OAuth request.

    >>> from lazr.authentication.testing.oauth import SimpleOAuthDataStore

    >>> class AnonymousAccessDataStore(SimpleOAuthDataStore):
    ...     """A data store that will accept any consumer."""
    ...     def lookup_consumer(self, consumer):
    ...         """If there's no matching consumer, just create one.
    ...
    ...         This will let anonymous requests succeed with any
    ...         consumer key."""
    ...         consumer = super(
    ...             AnonymousAccessDataStore, self).lookup_consumer(
    ...             consumer)
    ...         if consumer is None:
    ...             consumer = OAuthConsumer(consumer, '')
    ...         return consumer

    >>> data_store = AnonymousAccessDataStore(
    ...     {valid_consumer.key : valid_consumer},
    ...     {valid_token.key : valid_token,
    ...      empty_token.key : empty_token})

Now we're ready to protect the sample_application with OAuthMiddleware,
using our authenticate() implementation and our data store.

    >>> from lazr.authentication.wsgi import OAuthMiddleware
    >>> def protected_application():
    ...     return OAuthMiddleware(
    ...         sample_application, realm="OAuth test",
    ...         authenticate_with=authenticate, data_store=data_store)
    >>> wsgi_intercept.add_wsgi_intercept(
    ...     'api.launchpad.dev', 80, protected_application)

Let's try out some clients. As you'd expect, you can't get through the
middleware with no HTTPAuthorizer at all.

    >>> from lazr.restfulclient.authorize.oauth import OAuthAuthorizer
    >>> client = ServiceRoot(None, "http://api.launchpad.dev/")
    Traceback (most recent call last):
    ...
    Unauthorized: HTTP Error 401: Unauthorized
    ...

Invalid credentials are also no help.

    >>> authorizer = OAuthAuthorizer(
    ...     valid_consumer.key, access_token=OAuthToken("invalid", "token"))
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
    Traceback (most recent call last):
    ...
    Unauthorized: HTTP Error 401: Unauthorized
    ...

But valid credentials work fine (again, up to the point at which
lazr.restfulclient runs against the limits of this simple web
service). Note that the User-Agent header mentions the consumer key.

    >>> httplib2.debuglevel = 1
    >>> authorizer = OAuthAuthorizer(
    ...     valid_consumer.key, access_token=valid_token)
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
    send: 'GET /...user-agent: lazr.restfulclient...; oauth_consumer="consumer"...'
    ...

If the OAuthAuthorizer is created with an application name as well as
a consumer key, the application name is mentioned in the User-Agent
header as well.

    >>> authorizer = OAuthAuthorizer(
    ...     valid_consumer.key, access_token=valid_token,
    ...     application_name="the app")
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
    send: 'GET /...user-agent: lazr.restfulclient...; application="the app"; oauth_consumer="consumer"...'
    ...

    >>> httplib2.debuglevel = 0

It's even possible to get anonymous access by providing an empty
access token.

    >>> authorizer = OAuthAuthorizer(
    ...     valid_consumer.key, access_token=empty_token)
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")

Because of the way the AnonymousAccessDataStore (defined
earlier in the test) works, you can even get anonymous access by
specifying an OAuth consumer that's not in the server-side list of
valid consumers.

    >>> authorizer = OAuthAuthorizer(
    ...     "random consumer", access_token=empty_token)
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")

A ServiceRoot object has a 'credentials' attribute which contains the
Authorizer used to authorize outgoing requests.

    >>> from lazr.restfulclient.resource import ServiceRoot
    >>> root = ServiceRoot(authorizer, "http://api.launchpad.dev/")
    >>> root.credentials
    <lazr.restfulclient.authorize.oauth.OAuthAuthorizer object...>

If you try to provide credentials with an unrecognized OAuth consumer,
you'll get an error--even if the credentials are valid. The data store
used in this test only lets unrecognized OAuth consumers through when
they request anonymous access.

    >>> authorizer = OAuthAuthorizer(
    ...     'random consumer', access_token=valid_token)
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
    Traceback (most recent call last):
    ...
    Unauthorized: HTTP Error 401: Unauthorized
    ...

    >>> authorizer = OAuthAuthorizer(
    ...     'random consumer', access_token=OAuthToken("invalid", "token"))
    >>> client = ServiceRoot(authorizer, "http://api.launchpad.dev/")
    Traceback (most recent call last):
    ...
    Unauthorized: HTTP Error 401: Unauthorized
    ...

Teardown.

    >>> _ = wsgi_intercept.remove_wsgi_intercept("api.launchpad.dev", 80)