Django

Overview

Django is a high-level Python web framework that encourages rapid development and clean, pragmatic design. It provides a robust set of features for web applications, making it one of the most popular choices for building server-side applications. This example demonstrates how to integrate Zitadel using the OAuth 2.0 PKCE flow to authenticate users securely and maintain sessions across your application.

Auth library

This example uses Authlib, the standard authentication library for Python web frameworks. Authlib implements the OpenID Connect (OIDC) flow, manages PKCE, performs secure token exchange, and provides session management helpers. The integration uses Authlib's Django client which seamlessly handles OAuth 2.0 flows within Django applications.

What this example demonstrates

This example shows a complete authentication implementation using Django with Zitadel. Users start on a public landing page, click a login button to authenticate with Zitadel using the secure PKCE flow, and are redirected to a protected profile page displaying their user information after successful authentication.

The application implements server-side session management with Django's built-in session framework, storing authentication state securely in signed cookies. Protected routes use the @require_auth decorator to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including OIDC claims and session metadata.

The application demonstrates proper federated logout by terminating sessions both locally and with Zitadel's end-session endpoint, complete with CSRF protection using state parameters. Additionally, it includes automatic token refresh using refresh tokens to maintain long-lived sessions without requiring users to re-authenticate. The example uses Zitadel-specific scopes like urn:zitadel:iam:user:metadata and urn:zitadel:iam:org:projects:roles to access extended user attributes and role information for implementing role-based access control (RBAC).

Getting started

Prerequisites

Before running this example, you need to create and configure a PKCE application in the ZITADEL Management Console. Follow the PKCE application setup guide to:

Create a new Web application in your Zitadel project
Configure it to use the PKCE authentication method
Set up your redirect URIs (e.g., http://localhost:3000/auth/callback for development)
Configure post-logout redirect URIs (e.g., http://localhost:3000/auth/logout/callback)
Copy your Client ID for use in the next steps
Optionally enable refresh tokens in Token Settings for long-lived sessions

Note: Make sure to enable Dev Mode in the ZITADEL Management Console if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.

Run the example

Once you have your Zitadel application configured:

Clone the repository.
Create a .env file (copy from .env.example) and configure it with the values from your Zitadel application. Use these exact environment variable names:
```
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual Zitadel instance URL for ZITADEL_DOMAIN (the issuer)
- The Client ID you copied when creating the application for ZITADEL_CLIENT_ID
- The redirect URI you configured in the PKCE setup for ZITADEL_CALLBACK_URL (must match exactly)
- The post-logout redirect URI for ZITADEL_POST_LOGOUT_URL
- A strong random string for SESSION_SECRET (generate using: python -c "import secrets; print(secrets.token_hex(32))")
- A randomly generated string for ZITADEL_CLIENT_SECRET (generate using: python -c "import secrets; print(secrets.token_hex(32))")
Install dependencies using Poetry with poetry install and start the development server with poetry run python manage.py runserver localhost:3000 to verify the authentication flow end-to-end.