Zitadel：开源身份认证与授权平台完全指南

关注

原创 2026-04-15 20:19:46 236 阅读 AI 写同款· GEO 优化 ›

zitadel-net:zitadel的身份验证授权库（zitadel.ch），以点网形式编写，用于asp.net Web应用程序包 Zitadel .Net 欢迎使用Zitadel dotnet库的存储库。请前往以进一步阅读。立即下载

Zitadel：开源身份认证与授权平台完全指南

背景

身份认证是应用安全的第一道防线。现代应用通常需要用户注册登录、第三方社交登录、API 授权等身份管理功能。从零开发一套安全可靠的身份认证系统需要投入大量精力。使用成熟的身份认证服务商可以快速解决问题，但数据隐私和成本控制又是新的顾虑。Zitadel 作为开源的身份认证平台，提供了企业级的身份和访问管理能力，同时支持完全自托管部署，让团队完全掌控认证数据。本文分享 Zitadel 的部署与使用经验，帮助技术团队构建安全、灵活的身份认证体系。

一、项目概述与核心特性

Zitadel 是一个开源的身份和访问管理平台，GitHub Stars 数超过 10K。其设计目标是成为 Auth0、Okta 等商业产品的开源替代方案，提供完整的企业级功能同时保持部署灵活性。

标准协议支持：Zitadel 原生支持 OAuth 2.0、OpenID Connect (OIDC)、SAML 2.0 等行业标准认证协议。这意味着任何支持这些标准协议的应用都可以安全地集成 Zitadel，无需为每个应用单独开发认证逻辑。

多因素认证 (MFA/2FA)：内置对 TOTP（Google Authenticator、Microsoft Authenticator 等）、WebAuthn/FIDO2（硬件安全密钥）、邮件验证码等多种二次验证方式的支持。可以按组织或项目强制要求用户启用 MFA。

无密码认证：支持 WebAuthn 无密码登录，用户可以使用指纹、面部识别或硬件密钥登录，告别传统密码。

社交登录：开箱即用支持 Google、GitHub、Microsoft、SAML/SSO 等主流第三方登录方式，降低用户注册门槛。

企业级 SSO：支持通过 SAML 2.0 或 OIDC 与企业身份提供商（Active Directory、Okta、Azure AD 等）集成，实现企业单点登录。

角色与权限管理：提供细粒度的 RBAC（基于角色的访问控制）功能。支持定义角色、分配权限、控制资源访问级别。

组织与项目隔离：Zitadel 设计为多租户架构，支持创建多个组织和项目，每个组织可以独立管理用户、应用和配置。

审计日志：完整记录所有认证事件、用户操作和管理员行为，便于安全审计和合规要求。

提供 RESTful API 和 GraphQL API：所有管理功能都可以通过 API 调用，支持自动化运维和定制化集成。

二、Docker Compose 部署教程

环境准备

Zitadel 的 Docker 部署需要服务器满足以下要求：

Docker Engine 24.0+
Docker Compose v2.x
最低 2GB 内存（推荐 4GB+）
10GB+ 可用磁盘空间
支持 Linux AMD64

Zitadel 支持 PostgreSQL 作为数据库，推荐使用与 Zitadel 官方 Docker Compose 配置。

快速部署

创建 Zitadel 专用目录：

mkdir -p ~/zitadel
cd ~/zitadel

创建 docker-compose.yaml：

version: "3.8"

services:
  zitadel:
    image: ghcr.io/zitadel/zitadel:latest
    container_name: zitadel
    hostname: zitadel
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - ./data:/var/lib/zitadel
    environment:
      - ZITADEL_DATABASE_POSTGRES_HOST=postgres
      - ZITADEL_DATABASE_POSTGRES_PORT=5432
      - ZITADEL_DATABASE_POSTGRES_USER=postgres
      - ZITADEL_DATABASE_POSTGRES_PASSWORD=zitadel_password
      - ZITADEL_DATABASE_POSTGRES_DB=zitadel
      - ZITADEL_DATABASE_POSTGRES_SSL_MODE=disable
      - ZITADEL_FIRSTINSTANCE_ORG_MACHINE_USERNAME=admin
      - ZITADEL_FIRSTINSTANCE_ORG_MACHINE_PASSWORD=Admin@123
      - ZITADEL_FIRSTINSTANCE_ORG_NAME=Initial
    depends_on:
      - postgres
    restart: unless-stopped
    networks:
      - zitadel-network

  postgres:
    image: postgres:16-alpine
    container_name: postgres
    hostname: postgres
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=zitadel_password
      - POSTGRES_DB=zitadel
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - zitadel-network

networks:
  zitadel-network:
    driver: bridge

启动 Zitadel 服务：

docker compose up -d

Zitadel 首次启动会自动初始化数据库，约需等待 1 分钟。使用浏览器访问：

管理控制台：http://服务器IP:8080
gRPC API：http://服务器IP:8081

生成安全的 Masterkey

生产环境应使用随机生成的 Masterkey（32 字节十六进制字符串）：

# 生成 32 字节随机密钥
openssl rand -hex 32

将生成的密钥添加到环境变量：

environment:
  - ZITADEL_MASTERKEY=your-generated-masterkey-here

使用外部 PostgreSQL

如果使用已有的 PostgreSQL 数据库服务，修改数据库配置指向外部实例：

environment:
  - ZITADEL_DATABASE_POSTGRES_HOST=your-postgres-host
  - ZITADEL_DATABASE_POSTGRES_PORT=5432
  - ZITADEL_DATABASE_POSTGRES_USER=your-user
  - ZITADEL_DATABASE_POSTGRES_PASSWORD=your-password
  - ZITADEL_DATABASE_POSTGRES_DB=zitadel

三、快速入门与基础使用

访问管理控制台

首次访问 Zitadel 管理控制台：

浏览器访问 http://服务器IP:8080
使用初始化时设置的机器用户名 admin 和密码 Admin@123 登录
首次登录后会提示创建初始组织（Organization）

创建第一个应用

在 Zitadel 中注册需要认证的客户端应用：

进入「Projects」→「New Project」
输入项目名称，如「MyApp」
创建应用：点击项目 → 「Applications」→「New」
选择应用类型：
- Web：传统 Web 应用（使用 Session Cookie）
- API：后端服务或 SPA（使用 Token）
- Native：桌面或移动应用
- SAML：支持 SAML 协议的应用
配置认证方式：
- Authorization Code：标准 OAuth2 授权码流程，推荐用于 Web 应用
- Client Credentials：客户端凭证模式，用于服务间认证
- PKCE：增强的安全授权码流程，用于 SPA 和移动应用

获取客户端凭据

创建应用后，保存以下信息用于应用集成：

# 应用配置
Client ID: <your-client-id>
Client Secret: <your-client-secret>
Auth URL: http://服务器IP:8080/oauth/v2/authorize
Token URL: http://服务器IP:8080/oauth/v2/token
Userinfo URL: http://服务器IP:8080/oidc/v1/userinfo
Logout URL: http://服务器IP:8080/oidc/v2/logout

集成到应用

Node.js Express 应用示例

安装依赖：

npm install openid-client passport

集成代码示例：

const { Issuer } = require('openid-client');

async function setupAuth() {
  const issuer = await Issuer.discover('http://服务器IP:8080');
  
  const client = new issuer.Client({
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    redirect_uris: ['http://localhost:3000/callback'],
    post_logout_redirect_uris: ['http://localhost:3000'],
  });
  
  return client;
}

// 登录路由
app.get('/login', async (req, res) => {
  const client = await setupAuth();
  const url = client.authorizationUrl({
    scope: 'openid profile email',
  });
  res.redirect(url);
});

// 回调路由
app.get('/callback', async (req, res) => {
  const client = await setupAuth();
  const tokenSet = await client.callback(req.url);
  
  // 获取用户信息
  const userinfo = await client.userinfo(tokenSet.access_token);
  console.log('User:', userinfo);
  
  res.send('登录成功');
});

Python Flask 应用示例

安装依赖：

pip install authlib requests

集成代码示例：

from authlib.integrations.flask_client import OAuth

oauth = OAuth(app)
oauth.register(
    name='zitadel',
    client_id='your-client-id',
    client_secret='your-client-secret',
    server_metadata_url='http://服务器IP:8080/.well-known/openid-configuration',
    client_kwargs={'scope': 'openid profile email'}
)

@app.route('/login')
def login():
    return oauth.zitadel.authorize_redirect(redirect_uri=url_for('callback', _external=True))

@app.route('/callback')
def callback():
    token = oauth.zitadel.authorize_redirect(redirect_uri=url_for('callback', _external=True))
    resp = oauth.zitadel.get('http://服务器IP:8080/oidc/v1/userinfo', token=token)
    user_info = resp.json()
    return f'User: {user_info}'

四、高级功能与最佳实践

多因素认证 (MFA) 配置

Zitadel 支持多种 MFA 方式，可以在组织或项目级别强制启用。

启用 TOTP MFA：

进入「Settings」→「Login & Registration」
找到「Multi-factor Authentication」设置
启用 TOTP（Time-based One-Time Password）
保存设置

用户登录后在个人资料中绑定 authenticator 应用：

用户登录后进入「My Security」
点击「Add MFA」
选择 TOTP
使用 Google Authenticator 等应用扫描二维码
输入验证码完成绑定

强制 MFA：管理员可以在组织级别强制用户使用 MFA：

进入「Organization Settings」→「Login & Registration」
启用「Force MFA」
选择强制 MFA 的时机（首次登录、每次登录、指定时间后）

社交登录配置

Zitadel 支持配置第三方社交登录。

GitHub 登录配置：

在 GitHub Developer Settings 创建 OAuth App
设置回调 URL：http://服务器IP:8080/ui/console/callback
获取 Client ID 和 Client Secret
在 Zitadel 中进入「Settings」→「Identity Providers」
添加 GitHub 提供商，填入凭据

用户登录页面会出现 GitHub 登录选项。

角色与权限管理

Zitadel 的 RBAC 能力支持精细化的权限控制。

创建角色：

进入「Projects」→「MyApp」→「Roles」
点击「New Role」
定义角色 ID 和显示名称
添加角色描述

分配权限：

进入「Users」或「Members」
选择用户或添加新成员
分配项目角色

应用获取 Token 时可以请求特定角色：

const url = client.authorizationUrl({
  scope: 'openid profile email',
  resource: 'urn:zitadel:project:myapp',  // 项目标识
});

单点登录 (SSO) 配置

企业用户可以通过 SSO 直接使用企业账号登录。

SAML 2.0 SSO：

在 Zitadel 中创建 SAML Identity Provider
获取 Zitadel 的 SAML 元数据 URL
在企业 IdP（Okta、Azure AD 等）中配置新应用
将 Zitadel 元数据提供给企业 IdP
配置属性映射（email、name 等）

配置完成后，企业用户访问应用时会自动跳转到企业 IdP 进行认证。

自定义登录页面

Zitadel 允许自定义登录流程和界面样式。

自定义样式：通过设置 CSS 变量覆盖默认主题：

:root {
  --primary-color: #3B82F6;
  --background-color: #F3F4F6;
}

自定义文案：可以覆盖默认的界面文案和错误消息。

审计日志

Zitadel 自动记录所有认证和管理事件。

查看审计日志：

进入「Auditing」
筛选时间范围、事件类型、操作者
查看详细事件信息

导出日志：支持将日志导出为 CSV 格式用于分析：

点击「Export」
选择时间范围和筛选条件
下载 CSV 文件

API 自动化

Zitadel 提供完整的 API 用于自动化运维。

获取 Service User Token：

创建 Machine User：进入「Users」→「New」→「Machine User」
创建 PAT（Personal Access Token）：用户设置 → 「Tokens」→ 「New Token」
保存 Token

使用 PAT 调用管理 API：

curl -X GET "http://服务器IP:8080/admin/v1/users" \
  -H "Authorization: Bearer your-pat-token"

五、常见问题与解决方案

Q1：如何重置管理员密码？

如果忘记管理员密码，可以通过命令行重置：

docker exec -it zitadel zitadel rootkey add --username admin

这会生成一个新的管理员密钥用于恢复访问。

Q2：Client Secret 泄露怎么办？

立即轮换 Secret：

进入应用设置
点击「Regenerate Secret」
更新应用配置中的 Secret

在「Security」→「Sessions」中可以查看所有活跃会话，必要时可以撤销所有会话。

Q3：如何迁移 Zitadel 实例？

完整迁移步骤：

停止服务
备份 PostgreSQL 数据库
备份 Zitadel 数据目录
在新环境恢复数据
修改新环境的域名配置

Q4：支持高可用部署吗？

Zitadel 支持集群部署：

多个 Zitadel 实例共享同一个 PostgreSQL
使用负载均衡器分发请求
会话状态存储在数据库中，无状态扩展

建议配合健康检查和自动故障转移实现高可用。

Q5：如何对接已有用户库？

Zitadel 提供多种用户同步方案：

LDAP/AD 同步：通过 LDAP 导入企业用户
SCIM 协议：支持标准 SCIM 2.0 进行用户配置自动化
自定义 Webhook：监听用户变更事件同步到外部系统

六、总结

Zitadel 作为开源身份认证平台的优秀代表，提供了企业级 IAM 系统的完整功能，同时支持完全自托管部署。通过 Docker Compose 可以快速搭建包含身份认证、授权管理、MFA、SSO 在内的完整认证体系。OAuth 2.0 和 OIDC 标准协议的原生支持使集成变得简单可靠。对于注重数据隐私、希望掌控认证基础设施的团队，Zitadel 是构建安全身份认证体系的可靠选择。