Secure Django (Python) API Application with ZITADEL - Zitadel

import AppJWT from '../imports/_app_jwt.mdx'; import ServiceAccountJWT from '../imports/_serviceaccount_jwt.mdx'; import ServiceAccountRole from '../imports/_serviceaccount_role.mdx'; import SetupPython from '../imports/_setup_python.mdx'; import { GithubCodeBlock } from '@/components/github-code-block';

This integration guide demonstrates the recommended way to incorporate ZITADEL into your Django Python application. It explains how to check the token validity in the API and how to check for permissions.

By the end of this guide, your application will have three different endpoints that are public, private (valid token) and private-scoped (valid token with a specific role).

<Callout> This documentation references our [example](https://github.com/zitadel/example-python-django-oauth) on GitHub. </Callout>

ZITADEL setup

Before we can start building our application, we have to do a few setup steps in the ZITADEL Management Console.

Create application

Create Service Account

Assign a role to the Service Account

Prerequisites

At the end you should have the following for the API:

Issuer, something like https://example.zitadel.cloud or http://localhost:8080
Introspection URL, something like https://example.zitadel.cloud/oauth/v2/introspect
Token URL, something like https://example.zitadel.cloud/oauth/v2/token
.json-key-file for the API, from the application
ID of the project

And the following from the Service Account:

.json-key-file from the service account

Setup new Django application

Setup Python

Install dependencies

For this example we need the following dependencies:

django: to create an API with django
python-dotenv: to use environment variables in the settings
authlib: client-side OAuth functionality
requests: HTTP requests for the introspection

For the dependencies we need a requirements.txt-file with the following content:

Then install all dependencies with:

bash

python -m pip install -U requirements.txt

Then in your folder of choice, call the following command to create a Django base:

bash

django-admin startproject myapi .

Define the Django API

Add to the settings.py to include ZITADEL info

There is info needed for the introspection calls, which we put into the settings.py:

and create a ".env"-file in the root folder with the settings as an example:

bash

ZITADEL_INTROSPECTION_URL = 'URL to the introspection endpoint to verify the provided token'
ZITADEL_DOMAIN = 'Domain used as audience in the token verification'
API_PRIVATE_KEY_FILE_PATH = 'Path to the key.json created in ZITADEL'

I should look something like this:

bash

ZITADEL_INTROSPECTION_URL = 'https://example.zitadel.cloud/oauth/v2/introspect'
ZITADEL_DOMAIN = 'https://example.zitadel.cloud'
API_PRIVATE_KEY_FILE_PATH = '/tmp/example/250719519163548112.json'

Validator definition

To validate the tokens, we need a validator which can be called in the event of API-calls.

validator.py: <GithubCodeBlock url="https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/validator.py"></GithubCodeBlock>

Requests and URLs

We define 3 different endpoints which differ in terms of requirements. views.py: <GithubCodeBlock url="https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/views.py"></GithubCodeBlock>

To handle endpoints the urls have to be added to the urls.py: <GithubCodeBlock url="https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/urls.py"></GithubCodeBlock>

DB

Create and run migrations:

bash

python manage.py migrate

Run

You can use a local Django server to test the application.

bash

python manage.py runserver

Call the API

To call the API you need an access token, which is then verified by ZITADEL. Please follow this guide here, ignoring the first step as we already have the .json-key-file from the serviceaccount.

Optionally set the token as an environment variable:

export TOKEN='MtjHodGy4zxKylDOhg6kW90WeEQs2q...'

With the access token, you can then do the following calls:

curl -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/public
curl -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/private
curl -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/private-scoped

Completion

Congratulations! You have successfully integrated your Django API with ZITADEL!

If you get stuck, consider checking out our example application. This application includes all the functionalities mentioned in this quick-start. You can start by cloning the repository and defining the settings in the settings.py. If you face issues, contact us or raise an issue on GitHub.