在 Azure 中配置 OpenID Connect

在工作流程中使用 OpenID Connect 向 Azure 进行身份验证。

本文内容

Note

GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

概述

OpenID Connect (OIDC) 允许您的 GitHub Actions 工作流程访问 Azure 中的资源，而无需将任何 Azure 凭据存储为长期 GitHub 机密。

本指南概述了如何配置 Azure 信任 GitHub 的 OIDC 作为联合标识，并包含 azure/login 操作的工作流示例，该操作使用令牌向 Azure 进行身份验证并访问资源。

先决条件

  • 若要了解 GitHub 如何使用 OpenID Connect (OIDC) 及其体系结构和优势的基本概念，请参阅“关于使用 OpenID Connect 进行安全强化”。

  • 在继续之前，必须规划安全策略，以确保仅以可预测的方式分配访问令牌。 要控制云提供商颁发访问令牌的方式，必须至少定义一个条件，以便不受信任的存储库无法为云资源请求访问令牌。 有关详细信息，请参阅“关于使用 OpenID Connect 进行安全强化”。

  • 必须确保你的云提供商可以访问以下 OIDC 端点：

    • https://HOSTNAME/_services/token/.well-known/openid-configuration
    • https://HOSTNAME/_services/token/.well-known/jwks

    Note

    Microsoft Entra ID（以前称为 Azure AD）没有为这些终结点定义的固定 IP 范围。

  • 确保 JSON Web 令牌 (JWT) 随附的颁发者声明的值已设置为可公开路由的 URL。 有关详细信息，请参阅“关于使用 OpenID Connect 进行安全强化”。

将联合身份验证凭证添加到 Azure

GitHub 的 OIDC 提供商与 Azure 的工作负载联合身份验证配合使用。 有关概述，请参阅“工作负载联合身份验证”中的 Microsoft 文档。

要在 Azure 中配置 OIDC 身份提供商，您需要执行以下配置。 有关进行这些更改的说明，请参阅 Azure 文档。

  1. 创建 Entra ID 应用程序和服务主体。
  2. 为 Entra ID 应用程序添加联合身份验证凭证。
  3. 创建用于存储 Azure 配置的 GitHub 机密。

配置身份提供商的附加指导：

更新 GitHub Actions 工作流程

要更新 OIDC 的工作流程，您需要对 YAML 进行两项更改：

  1. 为令牌添加权限设置。
  2. 使用操作 azure/login 将 OIDC 令牌 (JWT) 交换为云访问令牌。

Note

在工作流或 OIDC 策略中使用环境时，建议将保护规则添加到环境中以提高安全性。 例如，可以在环境中配置部署规则，以限制可以部署到环境或访问环境机密的分支和标记。 有关详细信息，请参阅“管理部署环境”。

添加权限设置

作业或工作流运行需要使用 id-token: write 的 permissions 设置，以允许 GitHub 的 OIDC 提供程序为每个运行创建 JSON Web 令牌。 如果 id-token 的 permissions 未设置为 write，则无法请求 OIDC JWT ID 令牌，但是此值并不表示授予对任何资源的写权限，而只能提取和设置操作或步骤的 OIDC 令牌，以启用通过短期访问令牌进行身份验证。 任何实际信任设置均通过 OIDC 声明定义，有关详细信息，请参阅“关于使用 OpenID Connect 进行安全强化”。

id-token: write 设置允许使用下列方法之一从 GitHub 的 OIDC 提供程序请求 JWT：

  • 在运行器上使用环境变量（ACTIONS_ID_TOKEN_REQUEST_URL 和 ACTIONS_ID_TOKEN_REQUEST_TOKEN）。
  • 使用“操作”工具包中的 getIDToken()。

如果需要为工作流提取 OIDC 令牌，则可以在工作流级别设置权限。 例如：

YAML
permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

如果只需要为单个作业提取 OIDC 令牌，则可在该作业中设置此权限。 例如：

YAML
permissions:
  id-token: write # This is required for requesting the JWT

可能需要在此处指定额外权限，具体取决于你的工作流要求。

对于与调用方工作流属于同一用户、组织或企业的可重用工作流，可以从调用方的上下文访问在可重用工作流中生成的 OIDC 令牌。 对于企业或组织外部的可重用工作流，应在调用方工作流级别或在调用可重用工作流的特定作业中将 id-token 的 permissions 设置显式设置为 write。 这可确保仅允许可重用工作流中生成的 OIDC 令牌按预期在调用方工作流中使用。

有关详细信息，请参阅“重新使用工作流”。

请求访问令牌

azure/login 操作从 GitHub OIDC 提供商接收 JWT，然后从 Azure 请求访问令牌。 有关详细信息，请参阅 azure/login 文档。

以下示例将 OIDC ID 令牌与 Azure 交换以接收访问令牌，然后可以使用该令牌访问云资源。

YAML
name: Run Azure Login with OIDC
on: [push]

permissions:
  id-token: write
  contents: read
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 'Az CLI login'
        uses: azure/login@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: 'Run az commands'
        run: |
          az account show
          az group list

延伸阅读