CZL Connect
CZL Connect 接入文档

本文档将指导您如何将CZL Connect集成到您的应用中。

如果您有任何问题，请随时在论坛留言
复制提示词发送给 AI，即可自动编写OIDC 接入代码

OIDC 接入文档

CZL Connect 提供基于 OAuth 2.0 Authorization Code 的 OpenID Connect 能力。
支持 Discovery、JWKS、id_token、PKCE 以及多种客户端认证方式。

协议范围

OIDC 在 OAuth 2.0 的基础上增加身份认证能力。
对于接入方，主要差异体现在以下几点：

  • scope 必须包含 openid
  • 令牌响应中包含 id_token
  • 可通过 Discovery 端点获取配置
  • 可通过 JWKS 端点获取签名公钥

客户端认证方式

客户端类型推荐认证方式
服务端 Web 应用secret
桌面端应用none + PKCE
移动端应用none + PKCE
SPA / 浏览器前端none + PKCE

CZL Connect 后台中的 secret 客户端兼容 client_secret_basic 与 client_secret_post 两种标准 OIDC/OAuth2 传参方式。
当客户端认证方式为 none 时，授权码交换必须使用 PKCE。

Discovery

端点

端点URL
Discoveryhttps://connect.czl.net/.well-known/openid-configuration

示例

GET https://connect.czl.net/.well-known/openid-configuration

响应

{
  "issuer": "https://connect.czl.net",
  "authorization_endpoint": "https://connect.czl.net/oidc/authorize",
  "token_endpoint": "https://connect.czl.net/api/oidc/token",
  "userinfo_endpoint": "https://connect.czl.net/api/oidc/userinfo",
  "introspection_endpoint": "https://connect.czl.net/api/oidc/introspect",
  "jwks_uri": "https://connect.czl.net/api/oidc/jwks",
  "response_types_supported": ["code", "id_token", "code id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "response_modes_supported": ["query", "fragment"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"]
}

授权请求

参数

参数必填说明
response_type是固定为 code
client_id是客户端 ID
redirect_uri是回调地址
scope是必须包含 openid
state否状态参数，建议始终提供
nonce否建议提供，用于防止重放
code_challengePKCE 时必填PKCE challenge
code_challenge_methodPKCE 时必填固定为 S256

Traditional Client

https://connect.czl.net/oidc/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=openid profile email
  &state=RANDOM_STATE_VALUE
  &nonce=RANDOM_NONCE_VALUE

Public Client + PKCE

https://connect.czl.net/oidc/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=openid profile email
  &state=RANDOM_STATE_VALUE
  &nonce=RANDOM_NONCE_VALUE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256

令牌请求

授权码换取令牌

secret 客户端: client_secret_post

POST https://connect.czl.net/api/oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_REDIRECT_URI

secret 客户端: client_secret_basic

POST https://connect.czl.net/api/oidc/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(YOUR_CLIENT_ID:YOUR_CLIENT_SECRET)

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI

none + PKCE

POST https://connect.czl.net/api/oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&code_verifier=YOUR_CODE_VERIFIER

响应

{
  "access_token": "ACCESS_TOKEN",
  "id_token": "ID_TOKEN_JWT",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid profile email"
}

ID Token

示例

{
  "jti": "UNIQUE_TOKEN_ID",
  "iss": "https://connect.czl.net",
  "sub": "1",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1640995200,
  "iat": 1640991600,
  "nbf": 1640991600,
  "nonce": "RANDOM_NONCE_VALUE",
  "at_hash": "ACCESS_TOKEN_HASH",
  "name": "zhangsan",
  "email": "zhangsan@gmail.com",
  "email_verified": true,
  "picture": "https://example.com/avatar.png",
  "groups": "t0,t1,t2,t3,t4,t5,viewer,admin"
}

字段

字段说明
iss颁发者
sub用户唯一标识
aud目标客户端
exp过期时间
iat签发时间
nbf生效时间
nonce客户端请求中的 nonce
at_hashAccess Token 摘要
groups用户分组字段，包含继承展开后的分组值

UserInfo

请求

GET https://connect.czl.net/api/oidc/userinfo
Authorization: Bearer ACCESS_TOKEN

刷新令牌

secret 客户端: client_secret_post

POST https://connect.czl.net/api/oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

secret 客户端: client_secret_basic

POST https://connect.czl.net/api/oidc/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(YOUR_CLIENT_ID:YOUR_CLIENT_SECRET)

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN

none

POST https://connect.czl.net/api/oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

迁移到 PKCE

从传统 client_secret 模式迁移到 PKCE 时，需要修改以下内容：

  1. 将客户端认证方式改为 none
  2. 授权请求增加 code_challenge 与 code_challenge_method=S256
  3. 令牌请求删除 client_secret
  4. 令牌请求增加 code_verifier

scope、Discovery 地址、JWKS 地址、UserInfo 地址不需要调整。

验证要求

接入方应验证以下内容：

  • id_token 签名
  • iss
  • aud
  • exp
  • nonce

安全要求

  • scope 必须包含 openid
  • client_secret 仅适用于能够安全保存机密的服务端应用
  • Public Client 必须使用 PKCE
  • 当前仅支持 S256
  • 桌面端、移动端和浏览器前端不应内置 client_secret

应用更新推送

如果你的应用已经通过 OIDC 接入 CZL Connect，也可以直接启用“更新推送”能力：

  • 更新检查仍然使用当前用户的 access_token
  • id_token 继续只用于身份声明校验，不用于调用更新接口
  • 不需要在客户端保存 client_secret
  • 自动发布版本时使用独立的 Push Token，而不是 OAuth/OIDC client_secret

详细说明见：