🔐

AWS IAM発行のJWTでAPI Gateway認証を試す|Outbound Identity Federation実践

に公開
2025/11/24

はじめに

2025年11月、AWSはIAM Outbound Identity Federationという新機能を発表しました。この機能を使うと、AWSのIAMプリンシパル(RoleやUser)が短命のJWTを取得し、外部サービスへの認証に利用できます。

本記事では、この機能で発行されたJWTを使い、API Gateway HTTP APIのJWTオーソライザーで認証する方法を実際に試してみました。

IAM Outbound Identity Federationとは

IAM Outbound Identity Federationは、AWS IAMプリンシパル(RoleやUser)が短命のJWTトークンを取得し、そのトークンを使って外部サービスに認証する機能です。

https://aws.amazon.com/about-aws/whats-new/2025/11/aws-iam-identity-federation-external-services-jwts/

主な特徴:

  • AWS STSのGetWebIdentityToken APIでJWTを取得
  • トークンには発行元のAWSアカウント、プリンシパル情報などが含まれる
  • 外部サービスはJWKS(JSON Web Key Set)エンドポイントでトークンを検証可能
  • トークンの有効期間は60秒〜3600秒(1分〜1時間)、デフォルトは300秒(5分)

https://aws.amazon.com/blogs/aws/simplify-access-to-external-services-using-aws-iam-outbound-identity-federation/

アーキテクチャ

今回構築するシステムの構成は以下の通りです:

構成要素:

  • API Gateway (HTTP API): JWTオーソライザーでトークンを検証
  • Lambda関数: バックエンドのハンドラー
  • IAM Issuer URL: トークン検証用のJWKSエンドポイントを提供

実装手順

前提条件

  • AWS CLIがインストールされ、適切に設定されていること
  • AWS CDKがインストールされていること
  • Node.js/TypeScript環境

Issuer URLの取得

まず、IAM Outbound Identity Federationを有効化し、Issuer URLを取得します。

  1. IAMコンソールで「アカウント設定」を開く
  2. 「Outbound Identity Federation」セクションで機能を有効化
  3. 表示されるIssuer URLをメモ(形式: https://xxxx.tokens.sts.global.api.aws)

CDKによるデプロイ

API GatewayとLambda関数をCDKでデプロイします。

lib/gekko-001-stack.ts
import { CfnOutput, RemovalPolicy, Stack, StackProps } from "aws-cdk-lib";
import { HttpApi } from "aws-cdk-lib/aws-apigatewayv2";
import { HttpJwtAuthorizer } from "aws-cdk-lib/aws-apigatewayv2-authorizers";
import { HttpLambdaIntegration } from "aws-cdk-lib/aws-apigatewayv2-integrations";
import { HttpMethod } from "aws-cdk-lib/aws-events";
import { Runtime } from "aws-cdk-lib/aws-lambda";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { LogGroup, RetentionDays } from "aws-cdk-lib/aws-logs";
import { Construct } from "constructs";

export class Gekko001Stack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const handler = new NodejsFunction(this, 'HelloWorldHandler', {
      runtime: Runtime.NODEJS_LATEST,
      entry: `${__dirname}/hello-handler.ts`,
      handler: 'handler',
      logGroup: new LogGroup(this, 'HelloWorldLogGroup', {
        logGroupName: '/gekko-001/hello-world',
        removalPolicy: RemovalPolicy.DESTROY,
        retention: RetentionDays.ONE_DAY,
      }),
    });

    const apiGw = new HttpApi(this, 'ApiGw');
    const integration = new HttpLambdaIntegration('HelloWorldIntegration', handler);

    // JWTオーソライザーの設定
    apiGw.addRoutes({
      methods: [HttpMethod.GET],
      path: '/jwt/hello',
      integration: integration,
      authorizer: new HttpJwtAuthorizer('IamJwtAuthorizer',
        'https://YOUR-ISSUER-ID.tokens.sts.global.api.aws', {
        jwtAudience: [apiGw.httpApiName!],
      }),
    });

    new CfnOutput(this, 'ApiGwUrl', {
      value: apiGw.apiEndpoint,
    });
    new CfnOutput(this, 'ApiGwName', {
      value: apiGw.httpApiName!,
    });
  }
}

Lambda関数のハンドラーコード:

lib/hello-handler.ts
import { APIGatewayProxyEventV2, Context } from 'aws-lambda';

export const handler = async (event: APIGatewayProxyEventV2, context: Context) => {
    return {
        statusCode: 200,
        body: JSON.stringify({
            message: 'Hello, World!',
            event: event,
            context: context
        }),
    };
}

ポイント:

  • HttpJwtAuthorizerにIAMのIssuer URLを指定
  • jwtAudienceにAPI Gatewayの名前を設定。IAMからトークン取得するときに指定する値としても利用します。

デプロイ:

cdk deploy

トークンの取得とアクセス

トークンを取得してAPI Gatewayにアクセスするスクリプト:

scripts/jwt-get.sh
#!/bin/bash

if [ -z "$1" ]; then
  echo "Usage: $0 <URL>" >&2
  exit 1
fi

TARGET_URL="$1"

# JWTトークンを取得
JWT_TOKEN=$(aws sts get-web-identity-token \
  --audience ApiGw \
  --signing-algorithm RS256 \
  --query 'WebIdentityToken' \
  --output text)

# API Gatewayにアクセス
curl -s -X GET "$TARGET_URL" \
  -H "Authorization: Bearer $JWT_TOKEN"

実行:

./scripts/jwt-get.sh https://YOUR-API-ID.execute-api.REGION.amazonaws.com/jwt/hello

スクリプト内のget-web-identity-tokenコマンドで使用しているオプション:

  • --audience ApiGw: JWTのaud claimに設定される値(オーソライザーのjwtAudience設定と一致させる必要がある)
  • --signing-algorithm RS256: 署名アルゴリズム(RS256=RSA、ES384=ECDSAから選択可能)
  • トークンの有効期間はデフォルトの300秒(5分)を使用(--duration-secondsで60〜3600秒の範囲で指定可能)

動作確認

正常にアクセスできると、以下のようなレスポンスが返ってきます:

scripts/jwt-get-response.json
{
  "message": "Hello, World!",
  "event": {
    "version": "2.0",
    "routeKey": "GET /jwt/hello",
    "requestContext": {
      "authorizer": {
        "jwt": {
          "claims": {
            "aud": "ApiGw",
            "sub": "arn:aws:iam::ACCOUNT_ID:role/...",
            "iss": "https://xxxx.tokens.sts.global.api.aws",
            "exp": "1763824092",
            "iat": "1763823192"
          }
        }
      }
    }
  }
}

Lambda関数内ではevent.requestContext.authorizer.jwt.claimsから、トークンのクレーム情報(発行元、サブジェクト、有効期限など)にアクセスできます。

IAMによるアクセス制御

必要な権限

トークンを発行するには、IAMプリンシパルにsts:GetWebIdentityToken権限が必要です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*"
    }
  ]
}

条件キーによる制限

以下の条件キーで、トークン発行をさらに制限できます:

条件キー 説明 例
sts:IdentityTokenAudience 発行可能なaudienceを制限 "StringEquals": {"sts:IdentityTokenAudience": "ApiGw"}
sts:DurationSeconds トークンの有効期間を制限 "NumericLessThanEquals": {"sts:DurationSeconds": "3600"}
sts:SigningAlgorithm 署名アルゴリズムを制限 "StringEquals": {"sts:SigningAlgorithm": "RS256"}

https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecuritytokenservice.html

実践的なポリシー例

特定のaudienceのみ許可し、有効期間を制限する例:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*",
      "Condition": {
        "ForAnyValue:StringEquals": {
          'sts:IdentityTokenAudience': ["ApiGw", "ApiGwProd"]
        }
        "NumericLessThanEquals": {
          "sts:DurationSeconds": "1800"
        }
      }
    }
  ]
}

このポリシーにより:

  • ApiGwまたはApiGwProdというaudienceのトークンのみ発行可能
  • トークンの有効期間は最大30分(1800秒)に制限

他のソリューションとの比較

API Gatewayでの認証方式として、IAM Outbound Federation、IAMオーソライザー、Cognitoの3つを比較します。

方式 クライアント実装 ポータビリティ 複雑さ 代表的ユースケース
IAM Outbound Federation aws sts get-web-identity-tokenでトークン取得 → HTTPヘッダに付与 高い(標準的なJWT) 低い M2M通信、検証環境、プロトタイピング
IAMオーソライザー リクエスト全体にSigV4署名(専用ツール必要) 低い(AWS専用) 高い AWS内部サービス間通信
Cognito User Pools OAuth 2.0 / OIDC フロー 中程度(業界標準) 中程度 エンドユーザー認証、本格的アプリ

詳細な比較

vs IAMオーソライザー

「IAMでトークン発行を制御するなら、API Gateway側でIAMオーソライザーを使っても同じでは?」という疑問があるかもしれません。

主な違い:クライアント側の実装の複雑さ

項目 IAM Outbound Federation (JWT) IAMオーソライザー
認証方式 JWTトークン SigV4署名
クライアント実装 Authorization: Bearer <token>ヘッダを付与 リクエスト全体(ヘッダー、パス、クエリ、ボディ)を署名
必要なツール AWS CLI/SDKのみ awscurl等の専用ツールまたは複雑な実装
ポータビリティ 高い(標準的なHTTP/JWT) 低い(AWS固有)
外部サービス連携 容易 困難

この違いは、外部サービスとの連携時に特に重要になります。

vs Cognito User Pools

「Cognitoでいいのでは?」という意見もあるでしょう。確かにCognitoは優れた選択肢ですが、用途によって使い分けができます。

項目 IAM Outbound Federation Cognito User Pools
セットアップ
必要なリソース なし(IAM設定のみ) User Pool、App Client、Resource Server等
初期構築の手間 最小限 中程度
認証機能
アクセス制御 audienceベース(シンプル) スコープベース(柔軟)
カスタムクレーム リクエストタグで追加可能 柔軟に追加可能
ユーザー管理 なし サインアップ、パスワードリセット等
認証フロー トークン取得のみ OAuth 2.0、SAML、ソーシャルログイン等
クライアント実装
秘密情報管理 不要 Client ID、シークレット等
実装の複雑さ シンプル 中程度

推奨される使い分け:

  • IAM方式: AWS内のM2M通信、プロトタイピング、シンプルな認証要件、検証環境
  • Cognito: エンドユーザー認証、複雑な権限管理、本格的なアプリケーション、豊富な認証フロー

⚠️ 本番利用における注意事項

設計意図との乖離

重要: この機能は本来、AWSワークロードが外部サービスにアクセスするために設計されています。今回のようにAPI Gatewayで使用することは、設計意図とは異なる利用方法です。

公式ドキュメントでも、外部サービス(サードパーティクラウド、SaaS、オンプレミスアプリケーション)での利用を想定しています。

推奨されるユースケース

本番環境での利用を検討する場合、以下のユースケースが適しています:

適している:

  • AWS内のマイクロサービス間の一時的な認証(プロトタイピング)
  • 開発・検証環境でのシンプルな認証
  • 外部サービスへのアウトバウンド通信(本来の用途)

適していない:

  • 本格的なエンドユーザー向けアプリケーション
  • 複雑な権限管理が必要なシステム
  • スコープベースのアクセス制御が必要な場合

セキュリティ考慮事項

本番環境で使用する場合の注意点:

  1. トークンの有効期間

    • デフォルトの5分は用途に応じて調整
    • 必要最小限の期間に設定
  2. Audienceの設計

    • 各APIやサービスごとに異なるaudienceを使用
    • ワイルドカードや汎用的な値は避ける
  3. IAMポリシーの厳密化

    • 条件キーで発行可能なトークンを制限
    • 最小権限の原則を適用
  4. 監査とモニタリング

    • CloudTrailでトークン発行を記録
    • 異常なトークン発行パターンを検知

まとめ

本記事では、AWS IAM Outbound Identity Federationで発行したJWTを使って、API GatewayのJWTオーソライザーで認証する方法を試しました。

主な発見:

  • IAM発行のJWTでもAPI GatewayのJWTオーソライザーで検証できる
  • 実装はシンプルで、標準的なJWT認証フローとして扱える
  • IAMポリシーでトークン発行を細かく制御可能

適用シーン:

  • AWS内のM2M通信の軽量な認証ソリューション
  • プロトタイピングや開発環境での利用
  • Cognitoほどの機能が不要なシンプルな用途

注意点:

  • 本来は外部サービス向けの機能であり、設計意図とは異なる使い方
  • 本番環境ではユースケースを慎重に検討
  • スコープベースの権限管理が必要な場合はCognitoの検討を

この機能の本来の提供目的は外部サービスへのアクセスですが、AWS上で稼働するサービス間のアクセス制御にも応用できる可能性を感じました。今後は他のAWSサービスとの連携パターンも探っていきたいと思います。

参考リンク

Discussion