ZITADEL with Django Python

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 endpoint which are public, private(valid token) and private-scoped(valid token with specific role).

info

This documentation references our example on GitHub.

ZITADEL setup

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

Create application

Go to your Project and click on the New button as shown below.

Give a name to your application (Test API is the name given below) and select type API.

Select JWT as the authentication method and click Continue.

Now review your configuration and click Create.

You will now see the API’s Client ID. You will not see a Client Secret because we are using a private JWT key.

Next, we must create the key pairs. Click on New.

Select JSON as the type of key. You can also set an expiration time for the key or leave it empty. Click on Add.

Download the created key by clicking the Download button and then click Close.

The key will be downloaded.

When you click on URLs on the left, you will see the relevant OIDC URLs. Note down the issuer URL, token_endpoint and introspection_endpoint.

The key that you downloaded will be of the following format.

{
  "type":"application",
  "keyId":"<YOUR_KEY_ID>",
  "key":"-----BEGIN RSA PRIVATE KEY-----\<YOUR_PRIVATE_KEY>\n-----END RSA PRIVATE KEY-----\n",
  "appId":"<YOUR_APP_ID>",
  "clientId":"<YOUR_CLIENT_ID>"
}

Also note down the Resource ID of your project.

Create Serviceuser

Go to the Users tab in your organization as shown below and click on the Service Users tab.

To add a service user, click on the New button.

Next, add the details of the service user and select either Bearer or JWT for Access Token Type and click on Create. For this example, we will select JWT.

Now you will see the saved details.

Next, we need to generate a private-public key pair in ZITADEL and you must get the private key to sign your JWT. Go to Keys and click on New.

Select type JSON and click Add.

Download the key by clicking Download. After the download, click Close.

You will see the following screen afterwards.

The downloaded key will be of the following format:

{
    "type":"serviceaccount",
    "keyId":"<YOUR_KEY_ID>",
    "key":"-----BEGIN RSA PRIVATE KEY-----\n<YOUR_KEY>\n-----END RSA PRIVATE KEY-----\n",
    "userId":"<YOUR_USER_ID>"
}

Give Serviceuser an authorization

In order to access this route, you must create the role read:messages in your ZITADEL project and also create an authorization for the service user you created by adding the role to the user. Follow these steps to do so:

Go to your project and select Roles. Click New.

Add the read:messages role as shown below and click Save.

You will see the created role listed.

To assign this role to a user, click on Authorizations.

Select the user you want to assign the role to.

Select the project where this authorization is applicable.

Select the role read:messages and click Save.

You will now see the your service user has been assigned the role read:messages.

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 Serviceuser:

.json-key-file from the serviceuser

Setup new Django application

Setup Python

You have to install Python as described in their documentation.

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 configuration
authlib: client-side OAuth functionality
requests: HTTP requests for the introspection

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

requirements.txt
loading...

See full example on GitHub

Then install all dependencies with:

python -m pip install -U requirements.txt

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

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:

myapi/settings.py
loading...

See full example on GitHub

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

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:

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:

myapi/validator.py
loading...

See full example on GitHub

Requests and URLs

We define 3 different endpoints which differ in terms of requirements. views.py:

myapi/views.py
loading...

See full example on GitHub

To handle endpoints the urls have to be added to the urls.py:

myapi/urls.py
loading...

See full example on GitHub

DB

Create and run migrations:

python manage.py migrate

Run

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

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.

ZITADEL setup​

Create application​

Create Serviceuser​

Give Serviceuser an authorization​

Prerequisites​

Setup new Django application​

Setup Python​

Install dependencies​

Define the Django API​

Add to the settings.py to include ZITADEL info​

Validator definition​

Requests and URLs​

DB​

Run​

Call the API​

Completion​

ZITADEL setup

Create application

Create Serviceuser

Give Serviceuser an authorization

Prerequisites

Setup new Django application

Setup Python

Install dependencies

Define the Django API

Add to the settings.py to include ZITADEL info

Validator definition

Requests and URLs

DB

Run

Call the API

Completion