OAuth2 with Django REST Framework

Here at Yeti we build our APIs with Django REST Framework and use the OAuth2 scheme using Django OAuth Toolkit. I'm no OAuth expert and it took me awhile to figure it all out — in fact, this is the second version of this post! Hopefully this blog post will save others some trouble; it will show you everything you need to set up OAuth2 for your own application using DRF.

This post is NOT about setting up authentication with third-party services like Facebook (see Part 3 instead). It is also not about creating an authentication service for apps other than your own to use.

Setup

I'm assuming you already have a User model and have DRF setup.

pip install django-oauth-toolkit
Add 'oauth2_provider' to installed apps
Add DOT to your authentication classes for DRF in settings.py
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'oauth2_provider.ext.rest_framework.OAuth2Authentication',
),
}
Add DOT to your urls.py
urlpatterns = patterns('',
url(r'^', include(router.urls)),
url(r'^o/', include('oauth2_provider.urls', namespace='oauth2_provider')),
url(r'^admin/', include(admin.site.urls)),
)
python manage.py migrate

How all this application and client stuff is working

Setting up OAuth for your own application can be confusing. For me, I was used to oauth flows with third-party services like Facebook and Twitter, but it took me a bit to wrap my head around how that would work for my app and our users. It doesn't help that oauth can be implemented in different ways (1.0 vs 2.0, different grant types, etc.).

When you use a third-party service

When you do your own OAuth

Essentially, the way OAuth works, there needs to be an application that a user is authenticating with. But now our app is the service providing authentication, so what is the appilcation supposed to be? Nothing really. It's just a dummy application that we set up. You can think of it as representing your front-end application if that helps.

Creating an application

In your Django admin or shell, you can create a new oauth2_provider.models.Application. Set client type to "public" and grant type to "resource owner password based". The name can just be whatever makes sense to you (e.g., "iOS App", "JS Frontend"), and the application should be owned by your admin user.

Note: The Django OAuth Toolkit tutorial says to make the client type "confidential". You can if you want, but since this app is actually going to be living on a public, insecure client (browser, mobile device), it makes more sense for the client type to be "public".

Example Sign Up

You don't have to use this, you're welcome to just make a user in the admin, but here's a full example:

serializers.py

from rest_framework import serializers

class SignUpSerializer(serializers.ModelSerializer):
class Meta:
model = User
fields = ('username', 'password')
write_only_fields = ('password',)

views.py

from rest_framework import generics
from permissions import IsAuthenticatedOrCreate

class SignUp(generics.CreateAPIView):
queryset = User.objects.all()
serializer_class = SignUpSerializer
permission_classes = (IsAuthenticatedOrCreate,)

permissions.py

from rest_framework import permissions

class IsAuthenticatedOrCreate(permissions.IsAuthenticated):
def has_permission(self, request, view):
if request.method == 'POST':
return True
return super(IsAuthenticatedOrCreate, self).has_permission(request, view)

urls.py

urlpatterns = patterns('',
url(r'^sign_up/$', views.SignUp.as_view(), name="sign_up"),
)

Request / Response (in JSON)

request:

{
"username": "django.pony",
"password": "djangsta"
}

response:

{
"username": "django.pony"
}

Get your token

The DOT docs say that you can get your token with the following request:

curl -X POST -d "grant_type=password&username=<user_name>&password=<password>" http://<client_id>:<client_secret>@localhost:8000/o/token/

Let's translate that.

Your request must be x-www-form-urlencoded. Having a different Content-Type header is not going to make DOT happy.
You can pass all the arguments (client_id, client_secret, grant_type, username, password) in that encoded form. E.g., though the curl request shows client_id and client_secret being passed in the url itself ahead of localhost, this is not a thing you need to try to figure out.
We are NOT actually using the client secret. If you are following along with this tutorial, and you made your Application public, you do not need to pass this value. If you were following the DOT tutorial instead and made your Application private, you will need to pass the client secret.

The mechanics of making this request with your Angular / iOS / whatever client are beyond the scope of this blog post, but I use a tool called Postman when playing around with APIs and the request looks like this:

You should get a response that looks like this:

{
"access_token": "THIS IS THE IMPORTANT PART",
"token_type": "Bearer",
"expires_in": 36000,
"refresh_token": "xyz456",
"scope": "read write groups"
}

Using your token

From here out, using your token is straightforward. To make an authenticated request, just pass the Authorization header in your requests. It's value will be "Bearer YOUR_ACCESS_TOKEN".

Logging in

The last missing piece of this is handling login. If your token expires or a user logs out of your application, you'll need to get a new token. Logging in works the exact same as the last request to /o/token/: you pass client id, grant type, username, and password, and you'll get a fresh access token back.

Logging out

Remember, the only thing that lets the server know that your subsequent requests are authorized is that token you are passing along. To log out (or make an unauthorized request), just delete the access token on your front end.

In summary

These are the endpoints we just set up:

EndpointAuthRequestResponsesign_up/username, passwordusernameo/token/username, password, client_idtoken (and some other stuff)everything elseOAuth2 (formatted as: Bearer YOUR_TOKEN)

You should now be able to sign up, then hit the o/token/ endpoint, and then be on your merry way.

Setup