Piston comes with 4 built-in authentication mechanisms:
- piston.authentication.NoAuthentication
- piston.authentication.HttpBasicAuthentication
- piston.authentication.OAuthAuthentication
- piston.authentication.DjangoAuthentication
plus a bonus piston.authentication.MultiAuthentication class to allow you to register multiple Auth mechanisms with a single instance of a handler.
The default Authentication mechanism for a handler is NoAuthentication which simply returns true on is_authenticated.
The piston.authentication.HttpBasicAuthentication Authentication handler allows you to use simple HTTP Authentication with your API.
Note
Using piston.authentication.HttpBasicAuthentication with apache and mod_wsgi requires you to add the WSGIPassAuthorization On directive to the server or vhost config, otherwise django-piston cannot read the authentication data from HTTP_AUTHORIZATION in request.META. See: Configuration Directives.
Example
Adding to the Blogpost example, you could require Basic Authentication as follows:
from django.conf.urls.defaults import *
from piston.resource import Resource
from piston.authentication import HttpBasicAuthentication
from mysite.myapp.api.handlers import BlogpostHandler
auth = HttpBasicAuthentication(realm="Django Piston Example")
blogpost_handler = Resource(BlogpostHandler, authentication=auth)
urlpatterns = patterns('',
url(r'^blogpost/(?P<post_slug>[^/]+)/', blogpost_handler),
url(r'^blogposts/', blogpost_handler),
)
A very handy class to use your API from pages that Django rendered, DjangoAuthentication allows you to use a user’s session cookie to Authenticate to the API.
OAuth is the preferred means of authorization, because it distinguishes between “consumers”, i.e. the approved application on your end which is using the API. Piston knows and respects this, and makes good use of it, for example when you use the @throttle decorator, it will limit on a per-consumer basis, keeping services operational even if one service has been throttled.
MultiAuthentication allows you to register multiple authentication classes for the same handler.
On each call, it will try each auth method in order, and try to authenticate in before failing.
Example
This example shows registering all 3 Auth methods to a single handler inside the url configuration in urls.py.
dj_auth = DjangoAuthentication()
basic_auth = HttpBasicAuthentication(realm="BasicAuth")
o_auth = OAuthAuthentication(realm="OAuth")
# Register all 3 Auth methods for the API.
auth = MultiAuthentication([dj_auth, basic_auth, o_auth])
ad = { 'authentication': auth }
# User Handler
user_handler = APIResource(UserHandler, \*\*ad)
Piston supports pluggable authentication through a simple interface. Resources can be initialized to use any authentication handler that implements the interface.
The Basic auth handler is very simple, and you should use this for reference if you want to roll your own.
An authentication handler is a class, which must have 2 methods: is_authenticated and challenge.
is_authenticated will receive exactly 1 argument, a copy of the request object Django receives. This object will hold all the information you will need to authenticate a user, e.g. request.META.get('HTTP_AUTHENTICATION').
Upon successful authentication, this function must set request.user to the correct django.contrib.auth.models.User object. This allows for subsequent handlers to identify who is logged in.
It must return either True or False, indicating whether the user was logged in.
For cases where authentication fails, is where challenge comes in.
challenge will receive no arguments, and must return a HttpResponse containing the proper challenge instructions. For Basic auth, it will return an empty response, with the header WWW-Authenticate set, and status code 401. This will tell the receiving end that they need to supply us with authentication.
For anonymous handlers, there is a special class, NoAuthentication in piston.authentication that always returns True for is_authenticated.