mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-08 19:10:32 +00:00
2af7b60fd9
Document the OpenID Connect tokens that Gitea Actions jobs can request since https://github.com/go-gitea/gitea/pull/39052, so they can sign in to cloud providers without long-lived secrets. - Add an OpenID Connect page covering how to trust Gitea, request a token and match its claims - Document the `id-token` permission scope and its maximum - Translate both for zh-cn and zh-tw, which still listed `id-token` as unsupported Co-authored-by: silverwind <[email protected]> Co-authored-by: silverwind <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/526 Reviewed-by: silverwind <[email protected]> Co-authored-by: Max P. <[email protected]>
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
---
|
||
date: "2026-08-23T00:00:00+00:00"
|
||
slug: "openid-connect"
|
||
sidebar_position: 40
|
||
---
|
||
|
||
# OpenID Connect
|
||
|
||
Job 可以請求短期有效的 OpenID Connect（OIDC）令牌來登入雲端服務供應商和其他服務，不必儲存長期有效的密鑰。這些令牌採用 GitHub Actions 的格式，因此 `aws-actions/configure-aws-credentials`、`google-github-actions/auth` 和 `azure/login` 等 Action 不需修改即可使用。
|
||
|
||
<a id="trusting-gitea"></a>
|
||
## 信任 Gitea
|
||
|
||
在服務中將 Gitea 新增為 OIDC 身分提供者：
|
||
|
||
- Issuer：`<ROOT_URL>/api/actions/oidc`
|
||
- Audience：`<ROOT_URL>/<owner>`，除非工作流請求了其他值
|
||
|
||
接著透過 [`sub` 宣告](#claims)上的條件，限制哪些工作流可以登入。
|
||
|
||
Gitea 使用它在 `<APP_DATA_PATH>/jwt/actions_oidc.pem` 建立的金鑰簽署令牌。位於負載平衡器後方的多個執行個體必須共用此檔案。
|
||
|
||
<a id="requesting-a-token"></a>
|
||
## 請求令牌
|
||
|
||
為工作流或 Job 授予 `id-token` 權限：
|
||
|
||
```yaml
|
||
permissions:
|
||
id-token: write
|
||
```
|
||
|
||
預設權限一律不包含此權限，來自 fork 的拉取請求的 Job 也永遠無法取得。所有者和儲存庫可以透過[最大令牌權限](token-permissions.md#maximum-token-permissions-clamping)停用它。
|
||
|
||
上述 Action 會自行請求令牌。在指令碼中，請使用 `ACTIONS_ID_TOKEN_REQUEST_URL` 和 `ACTIONS_ID_TOKEN_REQUEST_TOKEN`：
|
||
|
||
```shell
|
||
curl --fail --silent --show-error \
|
||
--header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
|
||
"${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
|
||
```
|
||
|
||
令牌位於回應的 `value` 欄位中，五分鐘後過期。
|
||
|
||
<a id="claims"></a>
|
||
## 宣告
|
||
|
||
`sub` 宣告包含所有者和儲存庫的名稱及 ID，因此重新命名或重新建立的儲存庫無法符合既有的信任政策：
|
||
|
||
```text
|
||
repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
|
||
repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
|
||
```
|
||
|
||
`pull_request` 事件使用第二種格式，其他所有事件（包括 `pull_request_target`）使用第一種。
|
||
|
||
其他宣告與 GitHub 相同，例如 `repository`、`ref`、`sha`、`workflow_ref` 和 `job_workflow_ref`。位於 `<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration` 的探索文件列出了所有宣告。
|
||
|
||
與 GitHub Actions 的差異：
|
||
|
||
- 沒有 `environment` 宣告。
|
||
- 拉取請求的執行使用 `refs/pull/<index>/head` 及其提交，而不是合併參考和合併提交。
|
||
- `run_number` 依儲存庫計數，而不是依工作流計數。
|