跳至主要内容
版本: 1.22.3

OAuth2 提供者

Gitea 支持充当 OAuth2 提供者，允许第三方应用程序在用户同意的情况下访问其资源。此功能自 1.8.0 版本开始提供。

端点​

端点URL
OpenID Connect 发现/.well-known/openid-configuration
授权端点/login/oauth/authorize
访问令牌端点/login/oauth/access_token
OpenID Connect 用户信息/login/oauth/userinfo
JSON Web 密钥集/login/oauth/keys

支持的 OAuth2 授权类型​

目前，Gitea 只支持 授权码授权类型 标准，并额外支持以下扩展

要将授权码授权类型用作第三方应用程序，需要通过设置中的“设置”（/user/settings/applications）部分注册一个新的应用程序。要进行测试或调试，可以使用 web 工具 https://oauthdebugger.com/.

范围​

Gitea 支持有范围的访问令牌，允许用户将令牌限制为仅在选定的 url 路径上运行。范围按高级 API 路径分组，并进一步细化为以下内容

  • read: GET 路径
  • write: POST、PUT、PATCH 和 DELETE 路径（除 GET 之外）

Gitea 令牌范围如下

名称描述
(无范围)不支持。即使对于公共存储库，也需要范围。
activitypubactivitypub API 路径：与 ActivityPub 相关的操作。
    read:activitypub授予 ActivityPub 操作的读取权限。
    write:activitypub授予 ActivityPub 操作的读/写/删除权限。
admin/admin/* API 路径：站点范围的管理操作（对非管理员帐户隐藏）。
    read:admin授予管理操作的读取权限，例如获取 cron 作业或已注册用户的电子邮件。
    write:admin授予管理操作的读/写/删除权限，例如运行 cron 作业或更新用户帐户。
issueissues/*、labels/*、milestones/* API 路径：与问题相关的操作。
    read:issue授予问题操作的读取权限，例如获取问题评论、问题附件和里程碑。
    write:issue授予问题操作的读/写/删除权限，例如发布或编辑问题评论或附件，以及更新里程碑。
misc保留供将来使用。
    read:misc保留供将来使用。
    write:misc保留供将来使用。
notificationnotification/* API 路径：用户通知操作。
    read:notification授予用户通知的读取权限，例如用户订阅了哪些通知以及读取新的通知。
    write:notification授予用户通知的读/写/删除权限，例如将通知标记为已读。
organizationorgs/* 和 teams/* API 路径：组织和团队管理操作。
    read:organization授予组织和团队状态的读取权限，例如列出用户有权查看的所有组织、团队和团队成员。
    write:organization授予组织和团队状态的读/写/删除权限，例如创建和更新团队以及更新组织设置。
package/packages/* API 路径：包操作
    read:package授予包操作的读取权限，例如读取和下载可用的包。
    write:package授予包操作的读/写/删除权限。目前与 read:package 相同。
repository/repos/* API 路径，但不包括 /repos/issues/*：存储库文件、拉取请求和发布操作。
    read:repository授予存储库操作的读取权限，例如获取存储库文件、版本、合作者。
    write:repository授予存储库操作的读/写/删除权限，例如获取更新存储库文件、创建拉取请求、更新合作者。
user/user/* 和 /users/* API 路径：与用户相关的操作。
    read:user授予用户操作的读取权限，例如获取用户存储库订阅和用户设置。
    write:user授予用户操作的读/写/删除权限，例如更新用户存储库订阅、关注的用户和用户设置。

预配置的应用程序​

Gitea 在启动时默认情况下为以下服务创建 OAuth 应用程序，因为我们认为这些应用程序普遍有用。

应用程序描述客户端 ID
git-credential-oauthGit 凭据助手a4792ccc-144e-407e-86c9-5e7d8d9c3269
Git 凭据管理器Git 凭据助手e90ee53c-94e2-48ac-9358-a874fb9e0662
teatead57cb8c4-630c-4168-8324-ec79935e18d4

为了防止意外行为，它们在 UI 中被显示为锁定，并且它们的创建可以通过 app.ini 中的 DEFAULT_APPLICATIONS 参数来控制。

客户端类型​

Gitea 支持机密和公共两种客户端类型，如 RFC 6749 中所定义.

对于公共客户端，回送 IP 地址（例如 http://127.0.0.1/）的重定向 URI 允许任何端口。避免使用 localhost，如 RFC 8252 所建议的那样.

示例​

机密客户端​

注意

此示例未使用 PKCE。

  1. 将用户重定向到授权端点以获取他们访问资源的同意

    https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE

    CLIENT_ID 可以通过在设置中注册应用程序来获取。STATE 是一个随机字符串，将在用户授权后发送回您的应用程序。state 参数是可选的，但应用于防止 CSRF 攻击。

    Authorization Page

    现在将要求用户授权您的应用程序。如果他们授权，用户将被重定向到 REDIRECT_URL，例如

    https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE

  2. 使用重定向中提供的 code，您可以请求一个新的应用程序和刷新令牌。访问令牌端点接受具有 application/json 和 application/x-www-form-urlencoded 主体的 POST 请求，例如

    POST https://[YOUR-GITEA-URL]/login/oauth/access_token
    {
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "code": "RETURNED_CODE",
      "grant_type": "authorization_code",
      "redirect_uri": "REDIRECT_URI"
    }

    响应

    {
      "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
    }

    CLIENT_SECRET 是为此应用程序生成的唯一秘密代码。请注意，您在 Gitea 中创建/注册应用程序后，秘密代码才会可见，并且无法恢复。如果您丢失了秘密代码，则必须通过应用程序的设置重新生成秘密代码。

    access_token 请求中的 REDIRECT_URI 必须与 authorize 请求中的 REDIRECT_URI 相匹配。

  3. 使用 access_token 向 API 发出请求 以访问用户的资源。

公共客户端 (PKCE)​

PKCE（代码交换证明密钥）是 OAuth 流程的扩展，允许在没有提供客户端密钥的情况下进行安全凭据交换。

注意：请确保您已将 OAuth 应用程序注册为公共客户端。

为此，您必须为每个授权请求提供一个 code_verifier。code_verifier 必须是一个随机字符串，长度至少为 43 个字符，最多为 128 个字符。它可以包含字母数字字符以及字符 -、.、_ 和 ~。

使用此 code_verifier 字符串，使用两种方法之一创建新的 code_challenge 字符串

  • 如果您在客户端上具有所需的功能，请将 code_challenge 设置为 code_verifier 的 SHA256 哈希的 URL 安全 Base64 编码字符串。在这种情况下，您的 code_challenge_method 将变为 S256。
  • 如果您无法执行此操作，则可以将 code_verifier 作为纯字符串提供给 code_challenge。然后您必须将 code_challenge_method 设置为 plain。

生成这些值后，您可以继续进行请求。

  1. 将用户重定向到授权端点以获取他们访问资源的同意

    https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&code_challenge_method=CODE_CHALLENGE_METHOD&code_challenge=CODE_CHALLENGE&state=STATE

    CLIENT_ID 可以通过在设置中注册应用程序来获取。STATE 是一个随机字符串，将在用户授权后发送回您的应用程序。state 参数是可选的，但应用于防止 CSRF 攻击。

    Authorization Page

    现在将要求用户授权您的应用程序。如果他们授权，用户将被重定向到 REDIRECT_URL，例如

    https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE

  2. 使用重定向中提供的 code，您可以请求一个新的应用程序和刷新令牌。访问令牌端点接受具有 application/json 和 application/x-www-form-urlencoded 主体的 POST 请求，例如

    POST https://[YOUR-GITEA-URL]/login/oauth/access_token
    {
      "client_id": "YOUR_CLIENT_ID",
      "code": "RETURNED_CODE",
      "grant_type": "authorization_code",
      "redirect_uri": "REDIRECT_URI",
      "code_verifier": "CODE_VERIFIER",
    }

    响应

    {
      "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
    }

    access_token 请求中的 REDIRECT_URI 必须与 authorize 请求中的 REDIRECT_URI 相匹配。

  3. 使用 access_token 向 API 发出请求 以访问用户的资源。