静的認証情報とサヨナラ！AWSでOIDC連携してみた！

皆さんこんにちは！いつも元気なクラフトマンです！クラウド環境における認証・認可の管理は、セキュリティと開発効率の両面で重要な課題です。従来のIAMユーザーとアクセスキーによる認証は、長期的な認証情報管理のリスクや運用コストの問題があります。そこで今回は、AWSでのOpenID Connect(以下、OIDC)連携による認証の仕組みを、初心者の方にもわかりやすく解説していきます！

本記事では、OIDC連携の具体例としてAWSを用いた構成を取り上げています。 OIDC連携自体はGoogle CloudやAzureなど他社パブリッククラウドでも実現可能ですが、本記事では構成が比較的シンプルで情報も多く、初めてOIDC連携を検証・導入する際のハードルが低いAWSを例に、基本的な考え方と実装イメージを整理することを目的としています。他のパブリッククラウドでの構成についても同様の考え方をベースに、各環境に応じた実装が可能です。

この記事で得られるもの

GitHub ActionsやHCP TerraformからAWSを操作する際、アクセスキーをSecretsに保存していませんか? この記事では、アクセスキー不要でAWSにアクセスできるOIDC連携の仕組みを解説します。アクセスキーのローテーション作業から解放され、より安全なクラウド運用を実現できるようになります。

この記事で得られるもの
なぜOIDC連携が必要なのか
- 従来の方式の3つの課題
- OIDC連携で解決できること
OIDC連携の仕組み - 4ステップで理解する認証フロー
- 全体像: GitHub ActionsがAWSにアクセスするまで
証明書(IDトークン)の中身 - JWT構造
実装手順: GitHub ActionsでOIDC連携を設定する
まとめと次のステップ
- この記事で学んだこと
- 次のステップ
参考リソース

なぜOIDC連携が必要なのか

従来の方式の3つの課題

1. セキュリティリスク: アクセスキーは"永続的なパスワード"

従来のIAMユーザー方式では、長期間有効なアクセスキーをGitHub SecretsやCI/CD環境に保存します。これは家の鍵をずっと玄関の下に隠しているようなもので、一度漏洩すると気づくまでずっと悪用され続けるリスクがあります。

2. 運用負荷: 定期的なローテーション作業

多くの企業では、セキュリティポリシーにより90日ごとのアクセスキーローテーションが義務付けられています。複数のプロジェクトやサービスで使われているキーを更新するには ...

新しいアクセスキーを発行
各サービスのSecrets設定を更新
旧キーの削除確認

この作業を忘れると、突然デプロイが止まってしまいます。

3. スケーラビリティの問題: サービスごとにユーザー作成

新しいマイクロサービスやワークフローが増えるたびにIAMユーザーを作成していると、「どのユーザーがどこで使われているか」の管理が複雑になります。

OIDC連携で解決できること

OIDC連携は「1時間だけ有効な使い捨て認証情報」を発行する仕組みです。これにより以下を実現することができます。

✅ 長期的な認証情報の保存が不要 - アクセスキー自体を管理しなくて良い
✅ 自動的に失効 - トークンは短時間で無効化されるため、漏洩リスクが最小化
✅ 細かい権限制御 - 「このリポジトリのmainブランチからのみ」といった条件設定が可能

次のセクションでは、この「使い捨て認証情報」がどのように発行されるのか、仕組みを見ていきましょう。

OIDC連携の仕組み - 4ステップで理解する認証フロー

全体像: GitHub ActionsがAWSにアクセスするまで

上の図を、喫茶店でコーヒーを注文する例えで説明します。

Step 1: 証明書の発行 (IDトークンの取得)

GitHub Actionsワークフローが実行される
GitHubが「このワークフローは正当です」という証明書(IDトークン)を発行
例: 会員カードを見せて「私は正規の会員です」と証明

Step 2: 証明書の検証 (AWSによる検証)

AWSがその証明書をチェック
「本当にGitHubからの正当なアクセスか?」を厳密に確認
例: 店員が会員カードの有効期限や会員番号を確認

Step 3: 一時パスワードの発行 (一時認証情報の取得)

検証が成功すると、1時間だけ有効な使い捨て認証情報を発行
この認証情報でAWSの操作が可能になる
例: 1日限定のクーポン券をもらう

Step 4: AWS操作の実行

その一時認証情報を使って、S3へのアップロードやEC2の操作を実行
1時間経つと自動的に無効化される
例: クーポン券でコーヒーを注文(有効期限切れたら使えない)

証明書(IDトークン)の中身 - JWT構造

証明書の実体はJWT (JSON Web Token) という形式で、3つの部分から構成されます。

ヘッダー: トークンの種類と署名方式

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "abcdef123456"
}

ペイロード: 「誰が、どこから」の情報

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:myorg/myrepo:ref:refs/heads/main",
  "aud": "sts.amazonaws.com",
  "iat": 1634215439,
  "exp": 1634216039,
  "nbf": 1634215439
}

署名: 改ざん検知のための電子署名
GitHubの秘密鍵で署名され、AWSが公開鍵で検証
途中で内容が書き換えられていないことを保証

AWS STSはこの証明書を検証し、問題なければ一時認証情報を返します。

実装手順: GitHub ActionsでOIDC連携を設定する

前提条件

AWSアカウントとIAM権限(iam:CreateOpenIDConnectProvider, iam:CreateRoleなど)
GitHubリポジトリ

Step 1: AWS側の準備 - OIDCプロバイダの作成

まず、「GitHubを信頼する設定」をAWSに登録します。

AWSコンソールでの設定手順

AWSマネジメントコンソールのIAMサービスに移動
サイドメニューから「IDプロバイダ」を選択
「プロバイダの作成」ボタンをクリック
プロバイダタイプとして「OpenID Connect」を選択
- 以下の情報を入力：
  - プロバイダのURL：IDプロバイダのエンドポイント（例：https://token.actions.githubusercontent.com）
  - オーディエンス：クライアントID（例：sts.amazonaws.com）
「プロバイダを追加」をクリックして保存

AWS CLIでの設定例

GitHub Actionsを利用する場合

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

HCP Terraformを利用する場合

aws iam create-open-id-connect-provider \
  --url https://app.terraform.io \
  --client-id-list aws.workload.identity

Step 2: IAMロールの作成 - 「誰がアクセスできるか」の定義

次に、「どのGitHubリポジトリからアクセスを許可するか」を定義したIAMロールを作成します。

信頼ポリシーの構造

信頼ポリシーは、どのエンティティ（ユーザーやサービス）がロールを引き受けられるかを定義します。OIDC連携の場合、以下のような信頼ポリシーを設定します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:myorg/myrepo:ref:refs/heads/main"
        }
      }
    }
  ]
}

重要な設定項目の解説

Federated: 先ほど作成したOIDCプロバイダのARN
Condition: アクセス条件の定義
- aud: トークンの宛先がsts.amazonaws.comであることを確認
- sub: セキュリティの要 - 特定のリポジトリ・ブランチのみに制限
  - repo:myorg/myrepo:ref:refs/heads/main → myorg の myrepo の main ブランチのみ許可
  - repo:myorg/* のようにワイルドカードも可能(組織全体など)

アクセス許可ポリシー(Permission Policy)の例

GitHub Actions用の条件設定（組織全体対応）

"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
  },
  "StringLike": {
    "token.actions.githubusercontent.com:sub": "repo:myorg/*"
  }
}

必要最小限の権限のみを付与します(最小権限の原則)。

Step 3: GitHub Actionsワークフローの実装

最後に、ワークフローファイルでOIDC認証を利用します。

ワークフローファイルの設定

# .github/workflows/deploy.yml
name: Deploy to AWS

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    # OIDC認証に必要な権限
    permissions:
      id-token: write  # IDトークンの取得に必要
      contents: read   # リポジトリの読み取り
    
    steps:
      - uses: actions/checkout@v4
      
      # OIDC認証でAWS認証情報を取得
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy-role
          aws-region: ap-northeast-1
      
      # 以降は通常のAWS CLI操作
      - name: Deploy to S3
        run: |
          aws s3 sync ./dist s3://my-deploy-bucket/
      
      - name: Verify deployment
        run: |
          aws s3 ls s3://my-deploy-bucket/

ポイント

permissionsのid-token: writeが必須
role-to-assumeに作成したIAMロールのARNを指定
configure-aws-credentialsアクションが自動的にOIDC認証を実行
以降のステップでは通常のAWS CLIコマンドが使える

動作確認 ワークフローを実行すると、GitHub Actionsのログで以下が確認できます

Run aws-actions/configure-aws-credentials@v4
Assuming role with OIDC
✓ Credentials loaded successfully

AWS CloudTrailでAssumeRoleWithWebIdentityイベントを確認すると、一時認証情報の発行履歴が見られます。

まとめと次のステップ

この記事で学んだこと

OIDC連携のメリット

アクセスキー管理からの解放
1時間で自動失効する一時認証情報
細かいアクセス制御が可能

認証フローの仕組み

GitHub → IDトークン発行 → AWS検証 → 一時認証情報取得
JWTトークンによる改ざん防止

基本的な実装方法

OIDCプロバイダの作成
信頼ポリシーによるアクセス制限
GitHub Actionsワークフローでの利用

次のステップ

今回は基本的なOIDC連携の仕組みと実装を解説しました。実際の運用では以下のような点も検討してみてください。

他のサービスとの連携: HCP Terraform、GitLab CI/CD、CircleCIなどでも同様の仕組みが利用可能
セキュリティの強化: IAMアクセスアナライザーを使った定期的な権限監査、マルチアカウント戦略の検討
トラブルシューティング: CloudTrailログを活用したアクセス履歴の確認

OIDC連携を導入することで、より安全で効率的なクラウド運用を実現できます。ぜひ実践してみてください！

SpireX Tech Note

SpireX株式会社（旧：セブン＆アイ・ネットメディア）

tech_7nmのブログ