Docs

Django API: Authorization

View on Github

Django API: Authorization

Gravatar for andres.aguiar@auth0.com
By Andres Aguiar

This tutorial demonstrates how to add authorization to a Django REST Framework API. We recommend you to Log in to follow this quickstart with examples configured for your account.

I want to explore a sample app

2 minutes

Get a sample configured with your account settings or check it out on Github.

View on Github
System requirements: Python 2.7, 3.3 and up | Django 1.8 and up | djangorestframework 3.0 and up | djangorestframework-jwt 1.11.0 | python-jose 1.3.2 | cryptography 2.0.3

New to Auth0? Learn how Auth0 works and read about implementing API authentication and authorization using the OAuth 2.0 framework.

Configure Auth0 APIs

Create an API

In the APIs section of the Auth0 dashboard, click Create API. Provide a name and an identifier for your API, for example https://quickstarts/api. You will use the identifier as an audience later, when you are configuring the Access Token verification. For Signing Algorithm, select RS256.

Create API

By default, your API uses RS256 as the algorithm for signing tokens. Since RS256 uses a private/public keypair, it verifies the tokens against the public key for your Auth0 account. The public key is in the JSON Web Key Set (JWKS) format, and can be accessed here.

Define scopes

Scopes let you define which resources can be accessed by the user with a given Access Token. For example, you might choose to grant read access to the messages resource if users have the manager access level, and a write access to that resource if they have the administrator access level.

You can add the required scopes in the Scopes tab of the Auth0 Dashboard's APIs section.

Configure Scopes

This example uses the read:messages scope.

This example demonstrates:

  • How to check for a JSON Web Token (JWT) in the Authorization header of an incoming HTTP request.

  • How to check if the token is valid, using the JSON Web Key Set (JWKS) for your Auth0 account. To learn more about validating Access Tokens, read the Verify Access Tokens tutorial.

Setup the Django Application

Install dependencies

Add the following dependencies to your requirements.txt and run pip install -r requirements.txt.

Create a Django project

This guide assumes you already have a Django application set up. If that is not the case, follow the steps in the Django Tutorial.

The sample project was created with the following commands:

Add a Django remote user

You need to define a way to map the username from the Access Token payload to the Django authentication system user.

Add RemoteUserMiddleware middleware component after AuthenticationMiddleware to middleware list.

Add ModelBackend and RemoteUserBackend to the Authentication Backends.

Create user.py file in your application's folder and define a function that maps the sub field from the access_token to the username.

Then create a remote user in Django authentication system. Please check the Django documentation for more information.

Validate Access Tokens

The settings.py file contains the configuration of the Django project.

Add the following imports in settings.py file.

Add rest_framework app to the INSTALLED_APPS entry.

Add JSONWebTokenAuthentication to Django REST framework's DEFAULT_AUTHENTICATION_CLASSES.

Add code to download the JWKS for your Auth0 domain and create a public key variable with it:

Configure the Django REST Framework JWK by setting the JWT_AUTH variable.

Set the JWT_AUDIENCE to your API identifier and the JWT_ISSUER to your Auth0 domain. By default those values will be retrieved from the .env file.

Validate scopes

Add the following methods to the views.py file to create a decorator that will check the granted scopes from the access_token.

Protect API Endpoints

The routes shown below are available for the following requests:

  • GET /api/public: available for non-authenticated requests
  • GET /api/private: available for authenticated requests containing an Access Token with no additional scopes
  • GET /api/private-scoped: available for authenticated requests containing an Access Token with the read:messages scope granted

In the file views.py add public and private endpoints. Add the @api_view decorator to the private endpoint to indicate that the method requires authentication.

Use the requires_scope decorator in the methods that require specific scopes granted. The method below requires the read:messages scope granted.

Add URL mappings

In previous steps we added methods to the views.py file. We need to map those methods to URLs.

Django has a URL dispatcher that lets you map URL patterns to views.

Create the file urls.py in your application folder. Add the URL patterns.

The Django project also has a urls.py file. Add a reference to your application's urls.py file.

Use Auth0 for FREE