GitHub Actions から Azure への OIDC 認証設定ガイド — シークレットレス連携

1. はじめに

GitHub Actions から Azure にデプロイする際、これまでは az ad sp create-for-rbac --sdk-auth で生成した長寿命の JSON シークレットを AZURE_CREDENTIALS として GitHub Secrets に保存する方法が広く使われてきました。しかし Azure CLI のリファレンス上でもこの --sdk-auth（--json-auth のエイリアス）は 非推奨（Deprecated） と明記されており、代わりに OIDC (OpenID Connect) による Workload Identity Federation への移行が公式に推奨されています。

本記事では、GitHub Actions の id-token: write 権限と Microsoft Entra ID の federated credential を組み合わせ、長寿命シークレットを一切保存せずに Azure へログインする 手順を、実際のセットアップ手順に沿って一般化して解説します。GitHub Actions のワークフロー設計そのものについては Reusable Workflows 実践ガイド でも扱っているので、あわせて参照してください。

2. OIDC 認証の仕組み

2.1 なぜ長寿命シークレットをやめるのか

GitHub Secrets に保存した長寿命のクラウド認証情報は、漏洩・失効忘れ・ローテーション運用の負荷といったリスクを常に抱えます。Microsoft Entra ID の公式ドキュメントも「ワークロード ID フェデレーションは、資格情報の手動管理負荷とシークレット漏洩・証明書失効リスクの両方を排除する」と説明しており、OIDC 方式へ切り替えることで次のメリットが得られます[^2]。

• クラウド側にシークレットを複製する必要がない
• クラウド側の IAM（Entra ID / Azure RBAC）でアクセスを一元管理できる
• トークンが自動的に短命失効するため、ローテーション運用が不要になる

2.2 OIDC トークン交換の流れ

permissions: id-token: write は「JWT を要求・使用する権限」のみを付与するものであり、他のリソースへの書き込み権限を直接与えるものではありません[^1]。実際の認証フローは次のようになります。

1. Azure 側で事前に federated credential（issuer / subject / audience）を設定しておく
2. ジョブ実行のたびに GitHub の OIDC プロバイダーが短命 JWT を発行する
3. ワークフロー内の azure/login などのアクションが JWT を提示してトークン交換を要求する
4. Entra ID がクレームを検証し、一致すれば短命のアクセストークンを返す
5. 発行されたアクセストークンで Azure Resource Manager や コンテナレジストリの API を呼び出す

2.3 主要クレームと federated credential の 3 条件一致

OIDC トークンの主要クレームは次のとおりです[^3]。

Entra ID 側は、登録した federated credential の issuer / subject / audience が提示された JWT のクレームと 完全一致 するかどうかだけを検証します。この仕組みは Kubernetes・GCP・AWS・SPIFFE/SPIRE などでも採用されている「workload identity federation」の一種です[^4]。

3. 移行の背景 — 旧方式からの脱却

az ad sp create-for-rbac --sdk-auth（--json-auth のエイリアス）は Azure CLI のリファレンス上で明示的に Deprecated と表示され、マネージド ID が利用できる場合はそちらを優先検討するよう案内されています[^5]。

4. セットアップ手順

4.1 必要な GitHub Secrets

リポジトリの Settings → Secrets and variables → Actions に以下を設定します。長寿命シークレットは含まれません。

廃止対象: 旧 AZURE_CREDENTIALS（az ad sp create-for-rbac --sdk-auth で生成した JSON）を使っている場合は、移行後に Settings → Secrets and variables → Actions から削除してください。

4.2 Entra ID アプリケーションとサービスプリンシパルの作成

APP_NAME="<your-repo>-github-actions"
SUBSCRIPTION_ID="<your-subscription-id>"
RESOURCE_GROUP="<your-resource-group>"
ACR_NAME="<your-acr-name>"

# シークレットなしでアプリ + サービスプリンシパルを作成
az ad app create --display-name "$APP_NAME"
APP_ID=$(az ad app list --display-name "$APP_NAME" --query "[0].appId" -o tsv)
az ad sp create --id "$APP_ID"
SP_OBJECT_ID=$(az ad sp show --id "$APP_ID" --query id -o tsv)

取得した値は GitHub Secrets に次のように対応させます。

• APP_ID → AZURE_CLIENT_ID
• az account show --query tenantId -o tsv → AZURE_TENANT_ID
• サブスクリプション ID → AZURE_SUBSCRIPTION_ID

4.3 ロールの付与（最小権限の考え方）

az ad sp create-for-rbac と異なり、az ad app create / az ad sp create は既定でいかなるロールも割り当てません。必要なロールを スコープを絞って 個別に付与します。

# デプロイ先リソースグループ単位で Contributor を付与する例
az role assignment create --assignee "$APP_ID" \
  --role "Contributor" \
  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP"

# コンテナレジストリへの push 権限のみを付与する例
az role assignment create --assignee "$APP_ID" \
  --role "AcrPush" \
  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.ContainerRegistry/registries/$ACR_NAME"

最小権限のポイント: サブスクリプション全体ではなく、対象リソースグループ・対象リソースまでスコープを絞ります。Contributor より狭い権限で足りる場合は Website Contributor のようなサービス固有ロールへの置き換えを検討してください。

4.4 GitHub Environments の設定

federated credential の subject に environment:staging / environment:production を指定する構成を採る場合、Entra ID 側に登録するより前に GitHub 側の Environment を作成しておく必要があります。Settings → Environments で staging と production を作成します。

Environment には次の保護ルールを追加設定することを強く推奨します。

• 対象ブランチ・タグの制限
• 必須レビュアー（承認者）
• wait timer（デプロイまでの待機時間）

4.5 federated credential の登録

GitHub Environment 単位で subject を発行する構成が代表的です（例: staging と production）。4.4 で作成した Environment 名と subject の値を一致させます。

fic-staging.json:

{
  "name": "<your-repo>-staging",
  "issuer": "https://token.actions.githubusercontent.com",
  "subject": "repo:<your-org>/<your-repo>:environment:staging",
  "audiences": ["api://AzureADTokenExchange"]
}

fic-production.json:

{
  "name": "<your-repo>-production",
  "issuer": "https://token.actions.githubusercontent.com",
  "subject": "repo:<your-org>/<your-repo>:environment:production",
  "audiences": ["api://AzureADTokenExchange"]
}

登録コマンド:

az ad app federated-credential create --id "$APP_ID" --parameters fic-staging.json
az ad app federated-credential create --id "$APP_ID" --parameters fic-production.json

注意: federated credential の管理（作成・更新・削除）には Application Administrator / Cloud Application Administrator / Global Administrator / Hybrid Identity Administrator のいずれかのロールが必要です。1 アプリあたり最大 20 個まで登録でき、issuer / subject はそれぞれ最大 600 文字です。

4.6 subject 形式のバリエーション

federated credential の subject は用途に応じて 4 つの形式から選びます[^3]。

セキュリティ上の注意点:

• GitHub 公式は「未信頼のリポジトリがアクセストークンを要求できないよう、最低 1 つの条件（subject など）を必ず定義しなければならない」と明記しています[^3]。
• pull_request をトリガーとするワークフローに、Azure デプロイのような強い権限を紐付けることは推奨されません。fork 由来の PR でも同一リポジトリ名で subject が成立し得るためです。
• Entra ID 側は「subject の値が一致していない場合、作成時にはエラーにならず、トークン交換のタイミングで初めてサイレントに失敗する」と警告しています[^2]。登録直後は必ず実際のワークフロー実行で疎通確認してください。
• ワイルドカードは非対応です。

build のようにビルド・push を行う job が environment を指定していない場合は、その job にも environment を付与するか、ブランチ subject（repo:<owner>/<repo>:ref:refs/heads/<branch>）を別途登録する必要があります。

4.7 ワークフロー側の permissions 設定

permissions: id-token: write は OIDC を必要とする job のみ に付与し、lint / test のような CI job には付与しません。

jobs:
  ci:
    # lint / test のみ。OIDC は不要なため id-token は付与しない
    permissions:
      contents: read
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
      - run: npm test

  build-and-deploy:
    needs: ci
    if: github.ref == 'refs/heads/main'
    environment: staging
    permissions:
      contents: read
      id-token: write # OIDC トークン取得に必須
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Azure login (OIDC)
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Build and push image
        run: |
          az acr build --registry "${{ secrets.AZURE_ACR_NAME }}" \
            --image "<your-image>:${{ github.sha }}" .

      - name: Deploy to staging slot
        run: |
          az webapp deployment slot swap \
            --resource-group "${{ secrets.AZURE_RESOURCE_GROUP }}" \
            --name "${{ secrets.AZURE_WEBAPP_NAME }}" \
            --slot "${{ secrets.AZURE_DEPLOY_SLOT_NAME }}" \
            --target-slot production

5. トラブルシューティング

6. 2025〜2026 年の最新動向

6.1 Immutable subject claims（2026 年 7 月 15 日〜）

従来の GitHub 既定の sub は organization 名・repository 名のみを使用していたため、リポジトリを削除して同名で再作成すると、別の所有者が同じ subject を取得できてしまう 問題がありました。2026 年 7 月 15 日以降に作成・リネーム・移管されたリポジトリでは、owner ID と repository ID を含む immutable な sub 形式（例: repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:refs/heads/main）が既定になります[^3]。既存リポジトリは明示的なオプトインまで従来形式を維持しますが、AWS・GCP・Azure・HashiCorp Vault いずれの信頼ポリシーもこの新形式への更新が将来的に必要になり得ます。

次の表は、旧形式と immutable 形式の違いをまとめたものです。

6.2 その他のアップデート

7. 他クラウドとの比較

Azure 以外の主要クラウドも同様の OIDC 連携をサポートしています[^7] [^8]。

8. まとめ

GitHub Actions から Azure への OIDC 連携は、長寿命シークレットを保存せずにデプロイを自動化できる、現時点で最も推奨される認証方式です。既に AZURE_CREDENTIALS を使っている場合は、次の順序で移行を進めるとスムーズです。

1. Entra ID アプリケーション・サービスプリンシパルを新規作成する
2. 最小権限でロールを付与する
3. federated credential を Environment 単位で登録する
4. ワークフローの OIDC 対応 job にのみ id-token: write を付与する
5. 疎通確認後、旧 AZURE_CREDENTIALS を GitHub Secrets から削除する

2026 年 7 月 15 日以降は immutable subject claims のデフォルト化も控えているため、リポジトリの作成・移管を予定している場合は subject 形式の変更点も併せて確認しておくことをおすすめします。ワークフロー全体の再利用性を高めたい場合は、Reusable Workflows 実践ガイド と組み合わせて OIDC ログイン部分を共通化するのも有効です。

9. 参考リンク

9.1 脚注

[^1]: Configuring OpenID Connect in Azure — GitHub Docs [^2]: Workload identity federation — Microsoft Entra ID [^3]: About security hardening with OpenID Connect — GitHub Docs [^4]: Security hardening your deployments — OpenID Connect concepts [^5]: az ad sp — Azure CLI reference [^6]: GitHub Actions security roadmap discussion [^7]: Configuring OpenID Connect in Amazon Web Services — GitHub Docs [^8]: Configuring OpenID Connect in Google Cloud Platform — GitHub Docs [^9]: Workload identity federation for app considerations — Microsoft Entra Workload ID（「Time for federated credential changes to propagate」節に AADSTS70021: No matching federated identity record found for presented assertion. の文言が明記されている）

9.2 参考リンク一覧

• Configuring OpenID Connect in Azure — GitHub Docs
• Workload identity federation — Microsoft Entra ID
• About security hardening with OpenID Connect — GitHub Docs
• Security hardening your deployments — OpenID Connect concepts
• az ad sp — Azure CLI reference
• GitHub Actions security roadmap discussion
• Configuring OpenID Connect in Amazon Web Services — GitHub Docs
• Configuring OpenID Connect in Google Cloud Platform — GitHub Docs
• Workload identity federation for app considerations — Microsoft Entra Workload ID

この記事の執筆にあたり、AI の支援を受けています。