---
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` 依儲存庫計數，而不是依工作流計數。