AWS IAM発行のJWTでAPI Gateway認証を試す|Outbound Identity Federation実践
はじめに
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トークンを取得し、そのトークンを使って外部サービスに認証する機能です。
主な特徴:
- AWS STSの
GetWebIdentityTokenAPIでJWTを取得 - トークンには発行元のAWSアカウント、プリンシパル情報などが含まれる
- 外部サービスはJWKS(JSON Web Key Set)エンドポイントでトークンを検証可能
- トークンの有効期間は60秒〜3600秒(1分〜1時間)、デフォルトは300秒(5分)
アーキテクチャ
今回構築するシステムの構成は以下の通りです:
構成要素:
- 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を取得します。
- IAMコンソールで「アカウント設定」を開く
- 「Outbound Identity Federation」セクションで機能を有効化
- 表示されるIssuer URLをメモ(形式:
https://xxxx.tokens.sts.global.api.aws)
CDKによるデプロイ
API GatewayとLambda関数をCDKでデプロイします。
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関数のハンドラーコード:
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にアクセスするスクリプト:
#!/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秒の範囲で指定可能)
動作確認
正常にアクセスできると、以下のようなレスポンスが返ってきます:
{
"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"} |
実践的なポリシー例
特定の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内のマイクロサービス間の一時的な認証(プロトタイピング)
- 開発・検証環境でのシンプルな認証
- 外部サービスへのアウトバウンド通信(本来の用途)
適していない:
- 本格的なエンドユーザー向けアプリケーション
- 複雑な権限管理が必要なシステム
- スコープベースのアクセス制御が必要な場合
セキュリティ考慮事項
本番環境で使用する場合の注意点:
-
トークンの有効期間
- デフォルトの5分は用途に応じて調整
- 必要最小限の期間に設定
-
Audienceの設計
- 各APIやサービスごとに異なるaudienceを使用
- ワイルドカードや汎用的な値は避ける
-
IAMポリシーの厳密化
- 条件キーで発行可能なトークンを制限
- 最小権限の原則を適用
-
監査とモニタリング
- CloudTrailでトークン発行を記録
- 異常なトークン発行パターンを検知
まとめ
本記事では、AWS IAM Outbound Identity Federationで発行したJWTを使って、API GatewayのJWTオーソライザーで認証する方法を試しました。
主な発見:
- IAM発行のJWTでもAPI GatewayのJWTオーソライザーで検証できる
- 実装はシンプルで、標準的なJWT認証フローとして扱える
- IAMポリシーでトークン発行を細かく制御可能
適用シーン:
- AWS内のM2M通信の軽量な認証ソリューション
- プロトタイピングや開発環境での利用
- Cognitoほどの機能が不要なシンプルな用途
注意点:
- 本来は外部サービス向けの機能であり、設計意図とは異なる使い方
- 本番環境ではユースケースを慎重に検討
- スコープベースの権限管理が必要な場合はCognitoの検討を
この機能の本来の提供目的は外部サービスへのアクセスですが、AWS上で稼働するサービス間のアクセス制御にも応用できる可能性を感じました。今後は他のAWSサービスとの連携パターンも探っていきたいと思います。
Discussion