CZL Connect

接入文档

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

如果您有任何问题，请随时在论坛留言 https://www.q58.club/t/topic/278

OAuth2.0 接入文档

通过OAuth2.0标准协议进行身份认证和授权

什么是OAuth2.0？

OAuth2.0是一个开放标准的授权协议，允许第三方应用在不获取用户凭证的情况下，获得对用户资源的有限访问权限。通过OAuth2.0，用户可以授权第三方应用访问其在CZL Connect上的账户信息，而无需分享密码。

接入流程

  1. 在CZL Connect创建应用，获取client_id和client_secret
  2. 将用户重定向到授权端点进行身份验证
  3. 用户授权后，CZL Connect将用户重定向回您的应用，并附带授权码
  4. 使用授权码交换访问令牌和刷新令牌
  5. 使用访问令牌获取用户信息

端点信息

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

授权码流程示例

1. 重定向用户到授权端点：

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

2. 用户授权后，使用授权码交换令牌：

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

或者使用HTTP Basic认证方式传递client凭据：

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

3. 令牌交换响应：

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 86400
}

4. 使用访问令牌获取用户信息：

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

5. 用户信息响应：

{
  "id": 1,
  "username": "zhangsan",
  "email": "[email protected]",
  "avatar": "https://avatars.githubusercontent.com/u/95951386?v=4",
  "upstreams": [
    {
      "id": 1,
      "upstream_id": 1,
      "upstream_name": "Q58论坛",
      "upstream_type": "discourse",
      "upstream_icon": "https://i-aws.czl.net/oracle/img/2024/09/66e05b628ef04.webp",
      "upstream_user_id": "1",
      "upstream_username": "zhangsan",
      "upstream_email": "[email protected]",
      "upstream_avatar": "https://i-aws.czl.net/r2/original/1X/bd60759e04270de3bd845cca0567722c57452962.png",
      "provider_data": {
        "admin": "true",
        "card_background_url": "https://i-aws.czl.net/r2/original/1X/3df53ccb5f6ffb1bd1d19e5703e5884558041a63.jpeg",
        "groups": "管理员,trust_level_0,trust_level_1,trust_level_2,trust_level_3,trust_level_4,版主,管理人员",
        "moderator": "true",
        "profile_background_url": "https://i-aws.czl.net/r2/original/1X/478bf02b095b8da629f2af6e53fc7ee7c232c5e0.jpeg"
      }
    },
    {
      "id": 3,
      "upstream_id": 2,
      "upstream_name": "Github",
      "upstream_type": "github",
      "upstream_icon": "",
      "upstream_user_id": "95951386",
      "upstream_username": "zhangsan",
      "upstream_email": "[email protected]",
      "upstream_avatar": "https://avatars.githubusercontent.com/u/95951386?v=4",
      "provider_data": {
        "bio": "",
        "blog": "https://woodchen.ink",
        "company": "CZL",
        "created_at": "2021-12-11T04:08:19Z",
        "followers": "6",
        "following": "2",
        "html_url": "https://github.com/woodchen-ink",
        "location": "Shanghai",
        "public_gists": "0",
        "public_repos": "84",
        "updated_at": "2025-01-08T07:03:39Z"
      }
    }
  ]
}

刷新令牌

当访问令牌过期时，可以使用刷新令牌获取新的访问令牌：

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

或者使用HTTP 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

用户信息字段说明

  • id：用户ID
  • username：用户名
  • email：用户邮箱
  • avatar：用户头像URL
  • upstreams：用户绑定的上游账号信息
    • upstream_name：上游名称
    • upstream_type：上游类型（如：discourse, github）
    • upstream_username：上游用户名
    • upstream_email：上游邮箱
    • upstream_avatar：上游头像URL
    • provider_data：上游提供的额外数据，不同上游返回的数据结构可能不同