CZL Connect
CZL Connect 接入文档

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

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

OAuth2.0 接入文档

CZL Connect 提供标准 OAuth 2.0 Authorization Code 授权流程。
在 CZL Connect 后台，客户端认证方式统一为两类：

  • secret
  • none

其中 secret 客户端在协议层同时兼容 client_secret_basic 与 client_secret_post 两种标准传参方式。
当客户端认证方式为 none 时，授权码交换必须使用 PKCE。

适用范围

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

服务端应用可以安全保存 client_secret。
桌面端、移动端和浏览器前端无法将 client_secret 视为机密，应使用 PKCE。

认证方式

secret

CZL Connect 的 secret 客户端兼容以下两种标准 OAuth2 传参方式。

client_secret_basic

客户端通过 HTTP Basic 认证发送 client_id 与 client_secret。

Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)

client_secret_post

客户端通过 application/x-www-form-urlencoded 请求体发送 client_id 与 client_secret。

client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

none

客户端不发送 client_secret。
此模式下必须使用 PKCE。

PKCE

PKCE 适用于无法安全保存 client_secret 的客户端。
流程要求如下：

  1. 客户端生成高强度随机字符串 code_verifier
  2. 客户端计算 code_challenge = BASE64URL(SHA256(code_verifier))
  3. 授权请求携带 code_challenge 与 code_challenge_method=S256
  4. 令牌请求携带 code_verifier

CZL Connect 当前仅支持 S256。

端点

端点URL
授权端点https://connect.czl.net/oauth2/authorize
令牌端点https://connect.czl.net/api/oauth2/token
用户信息端点https://connect.czl.net/api/oauth2/userinfo
用户邮箱端点https://connect.czl.net/api/oauth2/user/emails

授权请求

基本参数

参数必填说明
response_type是固定为 code
client_id是应用的客户端 ID
redirect_uri是回调地址
scope否授权范围
state否客户端状态参数，建议始终提供
upstream_providers否限制可用上游认证方式，逗号分隔
code_challengePKCE 时必填PKCE challenge
code_challenge_methodPKCE 时必填固定为 S256

Traditional Client

https://connect.czl.net/oauth2/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=read
  &state=RANDOM_STATE_VALUE

Public Client + PKCE

https://connect.czl.net/oauth2/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=read
  &state=RANDOM_STATE_VALUE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256

令牌请求

授权码换取令牌

secret 客户端: client_secret_post

POST https://connect.czl.net/api/oauth2/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/oauth2/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/oauth2/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",
  "token_type": "bearer",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 86400,
  "scope": "read"
}

刷新令牌

secret 客户端: client_secret_post

POST https://connect.czl.net/api/oauth2/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/oauth2/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/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

用户信息

请求

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

响应

{
  "id": 1,
  "username": "zhangsan",
  "nickname": "张三",
  "email": "zhangsan@gmail.com",
  "avatar": "https://example.com/avatar.png",
  "groups": "t0,t1,t2,t3,t4,t5,viewer,admin",
  "upstreams": []
}

字段

字段说明
id用户 ID
username用户名
nickname用户昵称
email用户邮箱
avatar用户头像 URL
groups用户分组字段，包含继承展开后的分组值
upstreams用户绑定的上游账号信息

用户邮箱接口

请求

GET https://connect.czl.net/api/oauth2/user/emails
Authorization: Bearer ACCESS_TOKEN

响应

[
  {
    "email": "zhangsan@gmail.com",
    "verified": true,
    "primary": true,
    "visibility": "public"
  }
]

上游认证限制

upstream_providers 用于限制授权流程中可用的上游认证方式。

https://connect.czl.net/oauth2/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=read
  &state=RANDOM_STATE_VALUE
  &upstream_providers=discourse,github

常见取值包括：

  • discourse
  • github
  • google
  • qq
  • wechat

迁移到 PKCE

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

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

用户信息接口、回调地址、scope 和授权端点不需要调整。

安全要求

  • client_secret 仅适用于能够安全保存机密的服务端应用
  • 桌面端、移动端和浏览器前端不应内置 client_secret
  • Public Client 必须使用 PKCE
  • state 应始终由客户端生成并校验
  • 客户端仍需妥善保存 access_token 与 refresh_token
  • 当前仅支持 S256

应用更新推送

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

  • 客户端检查更新时，继续使用当前应用登录后得到的 access_token
  • 不需要也不应该在客户端内嵌 client_secret
  • 安装包下载通过短时票据保护
  • CI / 服务端自动发布版本时，使用独立的 Push Token

详细说明见：