django-oauthost documentation¶
Reusable application for Django to protect your apps with OAuth 2.0.
It allows to guard your applications views with OAuth 2.0 in quite a trivial way.
Requirements¶
- Python 3.6+
- Django 1.8+
- Django Auth contrib enabled
- Django Admin site contrib enabled (for simple oauthost data manipulation).
Table of Contents¶
Quick start¶
Warning
OAuth 2 requires secure connections, so oauthost will check for https if your project is not in debug mode, and will refuse to function if check fails.
Do not use Django’s cookie-based session engine with
oauthost
, it may cause security issues.Do not use OAuth1 clients.
Verify
MIDDLEWARE_CLASSES
setting hasdjango.contrib.sessions.middleware.SessionMiddleware and django.middleware.csrf.CsrfViewMiddleware
Verify
TEMPLATE_CONTEXT_PROCESSORS
has django.core.context_processors.requestNote
For Django 1.8+: django.template.context_processors.request should be defined in
TEMPLATES/OPTIONS/context_processors
.Add
oauthost
intoINSTALLED_APPS
Step by step¶
Initialize DB tables for
oauthost
. Run from command line:python manage.py migrate
Attach oauthost.urls to project URLs file (e.g. urls.py)
from oauthost.urls import urlpatterns as oauthost_urlpatterns urlpatterns = ... # Your actual urlpatterns are ommited. urlpatterns += oauthost_urlpatterns
Now authorization endpoint is available at { BASE_URL }auth/.
And token endpoint is available at { BASE_URL }token/.
Decorate application views which require OAuth 2 authorization with @oauth_required (let’s suppose those are views from polls application):
from oauthost.decorators import oauth_required @oauth_required(scope='my_polls:my_stats') def stats(request, poll_id): """Scope associated with this view is `my_polls:my_stats`.""" @oauth_required(scope_auto=True) def results(request, poll_id): """Scope for this view would be evaluated to `polls:results`."""
Use Django Admin site contrib package to manipulate
oauthost
data (e.g. register clients).3.1. Register scopes for your Django application.
Scope identifiers examples: polls:index, polls:detail, polls:results.
Note
You can use
syncscopes
management command which automatically creates scopes for oauth_required decorated views available in application(s), which names are passed to the command:python manage.py syncscopes polls
3.2. Register a client which could be granted with access to your resources.
Note
Just right there on client registration page you can set up redirection endpoints, register authorization codes and issue tokens. Latter two should normally be issued to a client itself as described in paragraph no 4.
Or use API:
from oauthost.toolbox import register_client # Define some scopes to restrict our client to. my_scopes = ['polls:vote', 'polls:stats'] # `user` might be `request.user` if in a view. register_client('My OAuth Client', '1234', 'http://myapp.com/', user, scopes_list=my_scopes)
Tokens and protected resources¶
4. Access authorization and/or token endpoints (see no 1 above) from within the client (registered in no 3.2) to gain credentials (namely an access token) to access protected views.
4.1. First your client needs to get an access token and there are several ways to get it.
Note
In the examples below we use client with ID 1234, which has one redirection endpoint (e.g. http://myapp.com/).
4.1.1. Grant token through authorization code.
Request for authorization code with GET HTTP method:
{BASE_URL}auth/?client_id=1234&response_type=codeGrab code param value from URL your client is redirected to (e.g. http://myapp.com/).
Exchange authorization code for access token using POST HTTP method:
{BASE_URL}token/ grant_type=authorization_code&code={code_from_no_2}&redirect_uri=http://myapp.com/&client_id=1234Get access_token param value from JSON document returned by server.
4.1.2. Grant token implicitly.
Request for authorization code with GET HTTP method:
{BASE_URL}auth/?client_id=1234&response_type=tokenGet access_token param value from JSON document returned by server.
4.2. Second your client should supply token from no 4.1 (or no 3.2) to server when accessing any protected views of your application. Currently there are three ways to do it. Let’s suppose our access token is 987654.
4.2.1. Recommended way is to pass token in HTTP Authorization Bearer header:
GET /polls HTTP/1.1 Host: myapp.com Authorization: Bearer 9876544.2.2. You can also use POST HTTP method (access_token param is checked):
POST /polls HTTP/1.1 Host: myapp.com Content-Type: application/x-www-form-urlencoded access_token=9876544.2.3. Finally you can use GET HTTP method (access_token param is checked):
GET /polls?access_token=987654 HTTP/1.1 Host: myapp.com
Helpers¶
Piston Authentication class¶
Piston is a mini-framework for Django for creating RESTful APIs - http://bitbucket.org/jespern/django-piston/wiki/Home
Oauthost comes with an authentication class for Piston resources.
Piston resource view creation example:
from piston.resource import Resource
from oauthost.toolbox import PistonAuthHelper
my_resource_view = Resource(MyResourceHandler, authentication=PistonAuthHelper('my_resource:my_scope'))
See Piston documentation for more information on authentication customizations.
Things to read¶
OAuth 2.0 Authorization Protocol - http://tools.ietf.org/html/rfc6749
OAuth 2.0 Bearer Tokens - http://tools.ietf.org/html/rfc6750
All different flavors:
Get involved into django-oauthost¶
Submit issues. If you spotted something weird in application behavior or want to propose a feature you can do that at https://github.com/idlesign/django-oauthost/issues
Write code. If you are eager to participate in application development, fork it at https://github.com/idlesign/django-oauthost, write your code, whether it should be a bugfix or a feature implementation, and make a pull request right from the forked project page.
Translate. If want to translate the application into your native language use Transifex: https://www.transifex.net/projects/p/django-oauthost/.
Spread the word. If you have some tips and tricks or any other words in mind that you think might be of interest for the others — publish it.
Also¶
If the application is not what you want for OAuth 2.0, you might be interested in considering other choices at http://djangopackages.com/grids/g/oauth-servers/