CZL Connect
CZL Connect 接入文档

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

如果您有任何问题，请随时在论坛留言

OIDC (OpenID Connect) 接入文档

通过标准OIDC协议进行身份认证，支持自动发现配置和ID Token

什么是OIDC？

OpenID Connect (OIDC) 是基于OAuth 2.0协议的身份认证层。它在OAuth 2.0的基础上增加了身份认证功能，提供了标准化的用户身份信息获取方式。OIDC支持自动发现配置，使得第三方应用可以更容易地集成身份认证功能。

OIDC vs OAuth2.0

  • OAuth2.0：主要用于授权，获取访问令牌来访问受保护的资源
  • OIDC：在OAuth2.0基础上增加身份认证，提供ID Token包含用户身份信息
  • 自动发现：OIDC支持通过发现端点自动获取配置信息
  • 标准化：OIDC提供了标准化的用户信息格式和获取方式

发现端点

发现配置
https://connect.czl.net/.well-known/openid-configuration

通过访问发现端点，您可以获得完整的OIDC配置信息，包括：

  • 授权端点 (authorization_endpoint)
  • 令牌端点 (token_endpoint)
  • 用户信息端点 (userinfo_endpoint)
  • JWKS端点 (jwks_uri)
  • 支持的响应类型和权限范围
  • 支持的签名算法

OIDC流程示例

1. 获取OIDC配置信息：

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

Response:
{
  "issuer": "https://connect.czl.net",
  "authorization_endpoint": "https://connect.czl.net/api/oidc/auth",
  "token_endpoint": "https://connect.czl.net/api/oidc/token",
  "userinfo_endpoint": "https://connect.czl.net/api/oidc/userinfo",
  "jwks_uri": "https://connect.czl.net/api/oidc/jwks",
  "response_types_supported": ["code", "id_token", "token id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email"]
}

2. 发起OIDC授权请求（必须包含openid scope）：

https://connect.czl.net/api/oidc/auth?
  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

3. 令牌交换（获得ID Token）：

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

Response:
{
  "access_token": "ACCESS_TOKEN",
  "id_token": "ID_TOKEN_JWT",
  "token_type": "bearer",
  "expires_in": 3600
}

4. ID Token包含的用户信息（解码后的JWT payload）：

{
  "iss": "https://connect.czl.net",
  "sub": "1",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1640995200,
  "iat": 1640991600,
  "nonce": "RANDOM_NONCE_VALUE",
  "username": "zhangsan",
  "nickname": "张三",
  "email": "zhangsan@gmail.com",
  "avatar": "https://avatars.githubusercontent.com/u/95951386?v=4",
  "groups": "t0,t1,t2,t3,t4,t5,viewer,admin"
}