mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
d8ea041c56
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
82 lines
6.3 KiB
Plaintext
82 lines
6.3 KiB
Plaintext
---
|
|
title: Django
|
|
sidebar_label: Django
|
|
framework_url: https://www.djangoproject.com
|
|
auth_library: "Authlib"
|
|
auth_library_url: https://authlib.org
|
|
example_repo: https://github.com/zitadel/example-auth-django
|
|
auth_flow: pkce
|
|
status: stable
|
|
---
|
|
|
|
## Overview
|
|
|
|
[Django](https://www.djangoproject.com) 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](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
|
|
|
|
#### Auth library
|
|
|
|
This example uses **[Authlib](https://authlib.org)**, the standard authentication library for Python web frameworks. Authlib implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/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](https://www.djangoproject.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) 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](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint).
|
|
|
|
The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/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)](https://zitadel.com/docs/guides/manage/console/roles).
|
|
|
|
---
|
|
|
|
## Getting started
|
|
|
|
### Prerequisites
|
|
|
|
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
|
|
|
|
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
|
|
2. Configure it to use the PKCE authentication method
|
|
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
|
|
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
|
|
5. Copy your **Client ID** for use in the next steps
|
|
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
|
|
|
|
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) 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](https://zitadel.com/docs/guides/manage/console/applications) configured:
|
|
|
|
1. Clone the [repository](https://github.com/zitadel/example-auth-django).
|
|
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **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](https://zitadel.com/docs/guides/manage/console/default-settings) 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))"`)
|
|
3. Install dependencies using [Poetry](https://python-poetry.org) 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.
|
|
|
|
---
|
|
|
|
## Learn more and resources
|
|
|
|
* [PKCE concept](https://oauth.net/2/pkce/)
|
|
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
|
|
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
|
|
* [Django documentation](https://www.djangoproject.com)
|
|
* [Authlib documentation](https://authlib.org)
|
|
* [Example repository](https://github.com/zitadel/example-auth-django)
|