Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
;
};
export const sections = [{
id: "define-permissions",
title: "Define permissions"
}, {
id: "configure-django-to-use-auth0",
title: "Configure Django to use Auth0"
}, {
id: "create-the-jwt-validator",
title: "Create the JWT validator"
}, {
id: "create-the-api-views",
title: "Create the API views"
}, {
id: "add-url-mappings",
title: "Add URL mappings"
}];
This guide demonstrates how to integrate Auth0 with any new or existing Python API built with [Django](https://www.djangoproject.com/).
If you haven't created an API in your Auth0 Dashboard yet, you can use the interactive selector to create a new
Auth0 API or select an existing API that represents the project you want to integrate with.
Alternatively, you can read our getting started guide,
which will help you set up your first API through the Auth0 Dashboard.
Every API in Auth0 is configured using an API Identifier that your application code will use as the Audience to
validate the Access Token.
**New to Auth0?** Learn how Auth0 works and
read about implementing API authentication and
authorization using the OAuth 2.0 framework.
Permissions let you define how resources can be accessed on behalf of 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 grant write access to that resource if they have the administrator access level.
You can define allowed permissions in the **Permissions** view of the Auth0 Dashboard's [APIs](https://manage.auth0.com/#/apis) section. The following
example uses the `read:messages` scope.
### Install dependencies
1. Add the following dependencies to your `requirements.txt`:
2. Run `pip install -r requirements.txt`
### Create a Django application
You will use a library called [Authlib](https://github.com/lepture/authlib) to create a [ResourceProtector](https://docs.authlib.org/en/latest/flask/1/resource-server.html), which is a type of [Django view decorator](https://docs.djangoproject.com/en/4.0/topics/http/decorators/) that protects your resources (API views) with a given
validator.
The validator will verify the Access Token that you pass to the resource by checking that it has a valid
signature and claims.
You can use AuthLib's `JWTBearerTokenValidator` validator with a few tweaks to make sure it conforms
to our requirements for [validating Access Tokens](https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens).
To create your `Auth0JWTBearerTokenValidator`, you need to pass it to your `domain` and
`audience` (API Identifier). It will then get the public key required to verify the token's signature
and pass it to the `JWTBearerTokenValidator` class.
You'll then override the class's `claims_options` to make sure the token's `expiry`,
`audience`, and `issue` claims are validated according to our requirements.
Create the file `apiexample/validator.py` using the code from the interactive panel.
Next, you'll create three API views in `apiexample/views.py`:
* `/api/public`: A public endpoint that requires no authentication.
* `/api/private`: A private endpoint that requires a valid Access Token JWT.
* `/api/private-scoped`: A private endpoint that requires a valid Access Token JWT containing the
given `scope`.
The protected routes will have a `require_auth` decorator, which is a `ResourceProtector`
that uses the `Auth0JWTBearerTokenValidator` you created earlier.
To create the `Auth0JWTBearerTokenValidator`, you'll pass it to your tenant's domain and the API
Identifier of the API you created earlier.
The `require_auth` decorator on the `private_scoped` route accepts an additional argument
`"read:messages"`, which checks the Access Token for the Permission (Scope) you created earlier.
In previous steps, you added methods to the `views.py` file. Next, map those methods to URLs using
Django's [URL dispatcher](https://docs.djangoproject.com/en/4.0/topics/http/urls/), which lets you map URL patterns to views.
Add the URL patterns to your `apiexample/urls.py` file.
### Make a Call to Your API
To make calls to your API, you will need an access token. You can retrieve an access token for testing purposes
from the **Test** view in your [API settings](https://manage.auth0.com/#/apis).
Provide the access token as an `Authorization` header in your requests.
```bash cURL lines theme={null}
curl --request get \
--url 'http:///%7ByourDomain%7D.com/api_path' \
--header 'authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
```
```csharp C# lines theme={null}
var client = new RestClient("http:///%7ByourDomain%7D.com/api_path");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
IRestResponse response = client.Execute(request);
```
```go Go lines theme={null}
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "http:///%7ByourDomain%7D.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))
}
```
```java Java lines theme={null}
HttpResponse response = Unirest.get("http:///%7ByourDomain%7D.com/api_path")
.header("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
.asString();
```
```javascript Node.JS lines theme={null}
var axios = require("axios").default;
var options = {
method: 'get',
url: 'http:///%7ByourDomain%7D.com/api_path',
headers: {authorization: 'Bearer YOUR_ACCESS_TOKEN_HERE'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
```
```objc Obj-C lines theme={null}
#import
NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http:///%7ByourDomain%7D.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];
```
```php PHP lines theme={null}
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http:///%7ByourDomain%7D.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 => [
"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;
}
```
```python Python lines theme={null}
import http.client
conn = http.client.HTTPConnection("")
headers = { 'authorization': "Bearer YOUR_ACCESS_TOKEN_HERE" }
conn.request("get", "/{yourDomain}.com/api_path", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```
```ruby Ruby lines theme={null}
require 'uri'
require 'net/http'
url = URI("http:///%7ByourDomain%7D.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
```
```swift Swift lines theme={null}
import Foundation
let headers = ["authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"]
let request = NSMutableURLRequest(url: NSURL(string: "http:///%7ByourDomain%7D.com/api_path")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "get"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
## Next Steps
Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.
This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:
* [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
* [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
```py apiexample/views.py lines highlight={} theme={null}
from authlib.integrations.django_oauth2 import ResourceProtector
from django.http import JsonResponse
from . import validator
require_auth = ResourceProtector()
validator = validator.Auth0JWTBearerTokenValidator(
"{yourDomain}",
"{yourApiIdentifier}"
)
require_auth.register_token_validator(validator)
def public(request):
"""No access token required to access this route
"""
response = "Hello from a public endpoint! You don't need to be authenticated to see this."
return JsonResponse(dict(message=response))
@require_auth(None)
def private(request):
"""A valid access token is required to access this route
"""
response = "Hello from a private endpoint! You need to be authenticated to see this."
return JsonResponse(dict(message=response))
@require_auth("read:messages")
def private_scoped(request):
"""A valid access token and an appropriate scope are required to access this route
"""
response = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
return JsonResponse(dict(message=response))
```
```py apiexample/validator.py lines highlight={} theme={null}
import json
from urllib.request import urlopen
from authlib.oauth2.rfc7523 import JWTBearerTokenValidator
from authlib.jose.rfc7517.jwk import JsonWebKey
class Auth0JWTBearerTokenValidator(JWTBearerTokenValidator):
def __init__(self, domain, audience):
issuer = f"https://{domain}/"
jsonurl = urlopen(f"{issuer}.well-known/jwks.json")
public_key = JsonWebKey.import_key_set(
json.loads(jsonurl.read())
)
super(Auth0JWTBearerTokenValidator, self).__init__(
public_key
)
self.claims_options = {
"exp": {"essential": True},
"aud": {"essential": True, "value": audience},
"iss": {"essential": True, "value": issuer},
}
```
```py apiexample/urls.py lines highlight={8-10} theme={null}
from django.contrib import admin
from django.urls import path
from . import views
urlpatterns = [
path('admin/', admin.site.urls),
path('api/public', views.public),
path('api/private', views.private),
path('api/private-scoped', views.private_scoped)
]
```
```py apiexample/validator.py lines highlight={} theme={null}
import json
from urllib.request import urlopen
from authlib.oauth2.rfc7523 import JWTBearerTokenValidator
from authlib.jose.rfc7517.jwk import JsonWebKey
class Auth0JWTBearerTokenValidator(JWTBearerTokenValidator):
def __init__(self, domain, audience):
issuer = f"https://{domain}/"
jsonurl = urlopen(f"{issuer}.well-known/jwks.json")
public_key = JsonWebKey.import_key_set(
json.loads(jsonurl.read())
)
super(Auth0JWTBearerTokenValidator, self).__init__(
public_key
)
self.claims_options = {
"exp": {"essential": True},
"aud": {"essential": True, "value": audience},
"iss": {"essential": True, "value": issuer},
}
```
```py apiexample/views.py lines highlight={} theme={null}
from authlib.integrations.django_oauth2 import ResourceProtector
from django.http import JsonResponse
from . import validator
require_auth = ResourceProtector()
validator = validator.Auth0JWTBearerTokenValidator(
"{yourDomain}",
"{yourApiIdentifier}"
)
require_auth.register_token_validator(validator)
def public(request):
"""No access token required to access this route
"""
response = "Hello from a public endpoint! You don't need to be authenticated to see this."
return JsonResponse(dict(message=response))
@require_auth(None)
def private(request):
"""A valid access token is required to access this route
"""
response = "Hello from a private endpoint! You need to be authenticated to see this."
return JsonResponse(dict(message=response))
@require_auth("read:messages")
def private_scoped(request):
"""A valid access token and an appropriate scope are required to access this route
"""
response = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
return JsonResponse(dict(message=response))
```
```py apiexample/urls.py lines highlight={8-10} theme={null}
from django.contrib import admin
from django.urls import path
from . import views
urlpatterns = [
path('admin/', admin.site.urls),
path('api/public', views.public),
path('api/private', views.private),
path('api/private-scoped', views.private_scoped)
]
```
```py apiexample/urls.py lines highlight={8-10} theme={null}
from django.contrib import admin
from django.urls import path
from . import views
urlpatterns = [
path('admin/', admin.site.urls),
path('api/public', views.public),
path('api/private', views.private),
path('api/private-scoped', views.private_scoped)
]
```
```py apiexample/validator.py lines highlight={} theme={null}
import json
from urllib.request import urlopen
from authlib.oauth2.rfc7523 import JWTBearerTokenValidator
from authlib.jose.rfc7517.jwk import JsonWebKey
class Auth0JWTBearerTokenValidator(JWTBearerTokenValidator):
def __init__(self, domain, audience):
issuer = f"https://{domain}/"
jsonurl = urlopen(f"{issuer}.well-known/jwks.json")
public_key = JsonWebKey.import_key_set(
json.loads(jsonurl.read())
)
super(Auth0JWTBearerTokenValidator, self).__init__(
public_key
)
self.claims_options = {
"exp": {"essential": True},
"aud": {"essential": True, "value": audience},
"iss": {"essential": True, "value": issuer},
}
```
```py apiexample/views.py lines highlight={} theme={null}
from authlib.integrations.django_oauth2 import ResourceProtector
from django.http import JsonResponse
from . import validator
require_auth = ResourceProtector()
validator = validator.Auth0JWTBearerTokenValidator(
"{yourDomain}",
"{yourApiIdentifier}"
)
require_auth.register_token_validator(validator)
def public(request):
"""No access token required to access this route
"""
response = "Hello from a public endpoint! You don't need to be authenticated to see this."
return JsonResponse(dict(message=response))
@require_auth(None)
def private(request):
"""A valid access token is required to access this route
"""
response = "Hello from a private endpoint! You need to be authenticated to see this."
return JsonResponse(dict(message=response))
@require_auth("read:messages")
def private_scoped(request):
"""A valid access token and an appropriate scope are required to access this route
"""
response = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
return JsonResponse(dict(message=response))
```
Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
Provide the access token as an `Authorization` header in your requests.