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

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 管理控制台：

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

创建第一个应用

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

1. 进入「Projects」→「New Project」

2. 输入项目名称，如「MyApp」

3. 创建应用：点击项目 → 「Applications」→「New」

4. 选择应用类型：

   • Web：传统 Web 应用（使用 Session Cookie）
   • API：后端服务或 SPA（使用 Token）
   • Native：桌面或移动应用
   • SAML：支持 SAML 协议的应用

5. 配置认证方式：

   • 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：

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

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

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

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

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

社交登录配置

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

GitHub 登录配置：

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

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

角色与权限管理

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

创建角色：

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

分配权限：

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

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

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

单点登录 (SSO) 配置

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

SAML 2.0 SSO：

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

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

自定义登录页面

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

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

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

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

审计日志

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

查看审计日志：

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

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

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

API 自动化

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

获取 Service User Token：

1. 创建 Machine User：进入「Users」→「New」→「Machine User」
2. 创建 PAT（Personal Access Token）：用户设置 → 「Tokens」→ 「New Token」
3. 保存 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：

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

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

Q3：如何迁移 Zitadel 实例？

完整迁移步骤：

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

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 是构建安全身份认证体系的可靠选择。

© 版权归无边界科技所有，发表评论请注明出处。