Django API

Sample Project

Download a sample project specific to this tutorial configured with your Auth0 API Keys.

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
Show requirements

This tutorial shows you how to use the authorization features in the OAuth 2.0 framework to limit access to your or third-party applications. For more information, read the API authorization documentation.

This guide demonstrates how to add authorization to your Python API using Django REST Framework.

Create a Resource Server (API)

In the APIs section of the Auth0 dashboard, click Create API. Provide a name and an identifier for your 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

Add API Authorization

To restrict access to the resources served by your API, check the incoming requests for valid authorization information. The authorization information is stored in the access token created for the user and needs to be sent in the Authorization header. To see if the token is valid, check it against the JSON Web Key Set (JWKS) for your Auth0 account. To learn more about validating access tokens, read the Verify Access Tokens tutorial.

Install the Dependencies

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

django
djangorestframework
djangorestframework-jwt
cryptography
python-jose

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:

$ django-admin startproject apiexample
$ cd apiexample
$ python manage.py startapp auth0authorization

Django Settings

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

Add the following imports in settings.py file.

# apiexample/settings.py

import json
from six.moves.urllib import request

from cryptography.x509 import load_pem_x509_certificate
from cryptography.hazmat.backends import default_backend

Add rest_framework app to the INSTALLED_APPS entry.

# apiexample/settings.py

INSTALLED_APPS = [
    # ...
    'rest_framework'
]

Add JSONWebTokenAuthentication to Django REST framework's DEFAULT_AUTHENTICATION_CLASSES.

# apiexample/settings.py

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    ),
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_jwt.authentication.JSONWebTokenAuthentication',
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.BasicAuthentication',
    ),
}

By default, your API will be set up to use RS256 as the algorithm for signing tokens. Since RS256 works by using a private/public keypair, tokens can be verified against the public key for your Auth0 account. This public key is accessible at https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json.

Obtain the public key from your JWKS. Then set the settings for REST Framework JWK.

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.

# apiexample/settings.py

jsonurl = request.urlopen("https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json")
jwks = json.loads(jsonurl.read())
cert = '-----BEGIN CERTIFICATE-----\n' + jwks['keys'][0]['x5c'][0] + '\n-----END CERTIFICATE-----'

certificate = load_pem_x509_certificate(str.encode(cert), default_backend())
publickey = certificate.public_key()

JWT_AUTH = {
    'JWT_PAYLOAD_GET_USERNAME_HANDLER':
        'authorization.user.jwt_get_username_from_payload_handler',
    'JWT_PUBLIC_KEY': publickey,
    'JWT_ALGORITHM': 'RS256',
    'JWT_AUDIENCE': '{YOUR_API_IDENTIFIER}',
    'JWT_ISSUER': 'YOUR_AUTH0_DOMAIN',
    'JWT_AUTH_HEADER_PREFIX': 'Bearer',
}

Add a Django User

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

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.

# auth0authorization/user.py

def jwt_get_username_from_payload_handler(payload):
    return payload.get('sub')

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

Protect Individual Endpoints

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.

# auth0authorization/views.py

from functools import wraps

from rest_framework.decorators import api_view
from django.http import HttpResponse
from jose import jwt

def public(request):
    return HttpResponse("All good. You don't need to be authenticated to call this")


@api_view(['GET'])
def private(request):
    return HttpResponse("All good. You only get this message if you're authenticated")

Configure the Scopes

To configure scopes, click the Scopes section of the Dashboard's APIs section and configure the scopes you need.

This example uses the read:messages scopes.

API endpoints can be configured to look for a particular scope in the access_token.

Add the following methods to the views.py file to extract the granted scopes from the access_token.

# auth0authorization/views.py

def get_token_auth_header(request):
    """Obtains the access token from the Authorization Header
    """
    auth = request.META.get("HTTP_AUTHORIZATION", None)
    parts = auth.split()
    token = parts[1]

    return token

def requires_scope(required_scope):
    """Determines if the required scope is present in the access token
    Args:
        required_scope (str): The scope required to access the resource
    """
    def require_scope(f):
        @wraps(f)
        def decorated(*args, **kwargs):
            token = get_token_auth_header(args[0])
            unverified_claims = jwt.get_unverified_claims(token)
            token_scopes = unverified_claims["scope"].split()
            for token_scope in token_scopes:
                if token_scope == required_scope:
                    return f(*args, **kwargs)
            return HttpResponse("You don't have access to this resource")
        return decorated
    return require_scope

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

# auth0authorization/views.py

@api_view(['GET'])
@requires_scope('read:messages')
def private_scoped(request):
    return HttpResponse("All good. You're authenticated and the access token has the appropriate scope")

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.

# auth0authorization/views.py

from django.conf.urls import url

from . import views

urlpatterns = [
    url(r'^api/public/', views.public),
    url(r'^api/private/', views.private),
    url(r'^api/private-scoped/', views.private_scoped),
]

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

# apiexample/urls.py

from django.conf.urls import url, include
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^', include('auth0authorization.urls'))
]

Make a Call to Your API

To make calls to your API, you need an access token. You can get an access token for testing purposes from the test lab in your API settings.

Obtain a JWT

Provide the access token as an Authorization header in your requests.


curl --request GET \
  --url http://your-domain.com/api_path \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
var client = new RestClient("http://your-domain.com/api_path");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
IRestResponse response = client.Execute(request);
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "http://your-domain.com/api_path"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("http://your-domain.com/api_path")
  .header("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .asString();
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://your-domain.com/api_path",
  "method": "GET",
  "headers": {
    "authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require("request");

var options = { method: 'GET',
  url: 'http://your-domain.com/api_path',
  headers: { authorization: 'Bearer YOUR_ACCESS_TOKEN_HERE' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http://your-domain.com/api_path"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://your-domain.com/api_path",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer YOUR_ACCESS_TOKEN_HERE"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import http.client

conn = http.client.HTTPConnection("your-domain.com")

headers = { 'authorization': "Bearer YOUR_ACCESS_TOKEN_HERE" }

conn.request("GET", "/api_path", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("http://your-domain.com/api_path")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Bearer YOUR_ACCESS_TOKEN_HERE'

response = http.request(request)
puts response.read_body
import Foundation

let headers = ["authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"]

var request = NSMutableURLRequest(URL: NSURL(string: "http://your-domain.com/api_path")!,
                                        cachePolicy: .UseProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.HTTPMethod = "GET"
request.allHTTPHeaderFields = headers

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    println(error)
  } else {
    let httpResponse = response as? NSHTTPURLResponse
    println(httpResponse)
  }
})

dataTask.resume()

Use Auth0 for FREECreate free Account