AWSハンズオン - Cognito + API Gateway + Lambda で認証付きAPIをSAMで構築しよう【コンソール版との比較付き】

はじめに

「認証付きAPIの構成をコードで管理して、チームで再現できるようにしたい」——そんな要件に、AWS SAM（Serverless Application Model） は最適な選択肢のひとつです。

この記事では、AWS SAM を使って、Cognito + API Gateway + Lambda による認証付き REST API をゼロから構築するハンズオンを紹介します。

クライアント（curl）
  │
  ├─ GET /hello  → API Gateway（認証なし）→ Lambda → 200 OK
  │
  └─ GET /profile
        ├─ Authorization ヘッダーなし → API Gateway が 401 を返す
        └─ Authorization: <IDトークン>
              → Cognito Authorizer が JWT を検証（Lambda 不要）
              → Lambda → email / sub を返す → 200 OK

このハンズオンで体験できること：

• AWS::Cognito::UserPool と AWS::Cognito::UserPoolClient の SAM 定義
• DefaultAuthorizer を使ったエンドポイント単位の認証制御（1行で全エンドポイントに認証を適用）
• Authorizer: NONE で特定エンドポイントだけ認証を除外するパターン
• CLI でのテスト実行（ユーザー作成 → IDトークン取得 → 認証済みリクエスト）

このハンズオンの特徴：

• sam build + sam deploy の 2コマンドで全リソースをデプロイ
• Cognito User Pool / User Pool Client / API Gateway / Lambda / IAM ロールを template.yaml 1ファイルで管理
• sam delete で全リソースを一括削除（コンソール版では各リソースを個別に削除する必要がある）

Amazon検索[本 AWS 開発]

SAM vs コンソール：どれだけ違うか

キーワード解説

前提条件

aws sts get-caller-identity

アカウントIDが表示されれば認証設定済みです。

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\cognito-api-lambda

フォルダ構造

cognito-api-lambda/
├── template.yaml       # SAMテンプレート（Cognito + API Gateway + Lambda 定義）
├── samconfig.toml      # デプロイ設定（gitignore 対象・毎回手動作成が必要）
├── docs/
│   ├── 1_console.md    # AWSコンソール版手順
│   └── 2_sam.md        # SAM版手順
└── src/
    └── app.py          # Lambda 関数（/hello と /profile を処理）

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml は全 AWSリソースの設計図です。ポイントを確認しておきます。

Cognito リソースの定義

Resources:
  UserPool:
    Type: AWS::Cognito::UserPool
    Properties:
      UsernameAttributes: [email]     # メールアドレスでログイン
      Policies:
        PasswordPolicy:
          MinimumLength: 8            # 記号・大文字不要（テスト用に緩和）

  # アプリクライアント: CLI から initiate-auth で使う
  UserPoolClient:
    Type: AWS::Cognito::UserPoolClient
    Properties:
      GenerateSecret: false           # シークレットなし（CLI テスト用）
      ExplicitAuthFlows:
        - ALLOW_USER_PASSWORD_AUTH    # username/password で直接認証（テスト用）
        - ALLOW_REFRESH_TOKEN_AUTH

API Gateway と Cognito Authorizer の定義

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Auth:
        # DefaultAuthorizer を指定 → 全エンドポイントにデフォルトで認証が必要になる
        DefaultAuthorizer: CognitoAuthorizer
        Authorizers:
          CognitoAuthorizer:
            UserPoolArn: !GetAtt UserPool.Arn  # User Pool と自動的に紐付け
            Identity:
              Header: Authorization            # JWT を Authorization ヘッダーで受け取る

Lambda 関数とエンドポイントの定義

  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        PublicEndpoint:              # /hello: 公開エンドポイント
          Type: Api
          Properties:
            Path: /hello
            Method: get
            Auth:
              Authorizer: NONE       # DefaultAuthorizer を明示的に無効化

        PrivateEndpoint:             # /profile: 認証必須
          Type: Api
          Properties:
            Path: /profile
            Method: get
            # Auth 指定なし → DefaultAuthorizer（CognitoAuthorizer）が自動適用

template.yaml のポイント解説

Step 3: Lambda コードの確認（src/app.py）

src/app.py の構造を把握しておきます。

import json


def lambda_handler(event, context):
    resource = event.get("resource", "/")   # API Gateway プロキシ統合: リクエストパスが入る

    if resource == "/hello":
        return {"statusCode": 200, "body": json.dumps({"message": "Hello! This is a public endpoint."})}

    if resource == "/profile":
        # Cognito Authorizer が JWT を検証済み
        # JWT ペイロードが event["requestContext"]["authorizer"]["claims"] に格納される
        claims = (
            event.get("requestContext", {})
            .get("authorizer", {})
            .get("claims", {})
        )
        return {
            "statusCode": 200,
            "headers": {"Content-Type": "application/json"},
            "body": json.dumps(
                {
                    "message": "認証成功",
                    "email": claims.get("email"),
                    "sub": claims.get("sub"),          # Cognito が生成したユーザーの一意 ID
                    "token_use": claims.get("token_use"),  # "id" が返る（IDトークンを使っているため）
                },
                ensure_ascii=False,
            ),
        }

    return {"statusCode": 404, "body": json.dumps({"message": "Not Found"})}

app.py のポイント：

• Lambda 側でトークン検証は一切不要。Cognito Authorizer が自動で行う
• claims には email / sub / token_use など JWT ペイロードの全フィールドが格納される
• /hello への呼び出しでは claims は空（Authorizer が動作しないため）

各コードの全文はコンソール版記事を参照してください。
SAM版・コンソール版で使用する Lambda コードは共通です。コンソール版では手順とあわせてコードを全文掲載しています。

→ AWSコンソールだけでCognito + API Gateway + Lambda の認証付きAPIを構築する手順

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

cognito-api-lambda/samconfig.toml を新規作成して以下を貼り付けます。

version = 0.1

[default.deploy.parameters]
stack_name = "cognito-api-lambda-stack"
resolve_s3 = true
s3_prefix = "cognito-api-lambda-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

samconfig.toml の置き場所：
cognito-api-lambda/ フォルダの直下に置く必要があります。

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\cognito-api-lambda
sam build

成功すると以下のように表示されます。

Build Succeeded

Built Artifacts  : .aws-sam/build
Built Template   : .aws-sam/build/template.yaml

sam build が行っていること：

• src/ フォルダを ZIP パッケージ化して .aws-sam/build/ に配置
• template.yaml を .aws-sam/build/template.yaml にコピー
• Lambda デプロイの準備を整える

Step 6: sam deploy（デプロイ）

sam deploy

変更内容が表示されて確認を求められます。

Deploy this changeset? [y/N]: y

y を入力して進めます。数分でデプロイが完了します。

デプロイ完了の確認

ターミナルに Outputs が表示されます。

Outputs
----------------------------------------------------------------------
Key    ApiUrl
Value  https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod

Key    UserPoolId
Value  ap-northeast-1_XXXXXXXX

Key    UserPoolClientId
Value  XXXXXXXXXXXXXXXXXXXXXXXXXX
----------------------------------------------------------------------

3つの値を全て控えておきます。（テスト実行コマンドで使用）

デプロイされるリソース一覧

Cognito User Pool × 1              : cognito-api-lambda-stack-user-pool
Cognito User Pool Client × 1       : シークレットなし（ALLOW_USER_PASSWORD_AUTH 有効）
API Gateway REST API × 1           : cognito-api-lambda-stack + Prod ステージ
Lambda 関数 × 1                    : cognito-api-lambda-stack-ApiFunction-XXXX
IAM ロール × 1                     : Lambda 実行ロール
S3                                 : SAM デプロイパッケージ
CloudWatch Logs                    : Lambda 自動生成ログ × 1

Step 7: 動作テスト

事前準備: 変数を設定する

set API_URL=https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod
set USER_POOL_ID=ap-northeast-1_XXXXXXXX
set CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXX

テスト1: テストユーザーを作成する

aws cognito-idp admin-create-user ^
  --user-pool-id %USER_POOL_ID% ^
  --username test@example.com ^
  --region ap-northeast-1

ユーザーが FORCE_CHANGE_PASSWORD 状態で作成されます。次のコマンドで永続パスワードを設定して CONFIRMED 状態にします。

aws cognito-idp admin-set-user-password ^
  --user-pool-id %USER_POOL_ID% ^
  --username test@example.com ^
  --password TestPass1 ^
  --permanent ^
  --region ap-northeast-1

レスポンスなし（エラーが出なければ成功）。

FORCE_CHANGE_PASSWORD 状態とは：
Cognito で管理者が作成したユーザーの初期状態です。この状態で initiate-auth を実行すると NEW_PASSWORD_REQUIRED チャレンジが返されてトークンが取得できません。--permanent フラグを付けて admin-set-user-password を実行することで CONFIRMED（認証済み）状態に変えられます。

テスト2: 公開エンドポイントのテスト（/hello）→ 200

curl %API_URL%/hello

期待するレスポンス:

{"message": "Hello! This is a public endpoint."}

テスト3: 未認証でプライベートエンドポイント（/profile）→ 401

curl %API_URL%/profile

期待するレスポンス（API Gateway が返す。Lambda は呼ばれていない）:

{"message": "Unauthorized"}

テスト4: IDトークンを取得する

aws cognito-idp initiate-auth ^
  --auth-flow USER_PASSWORD_AUTH ^
  --auth-parameters "USERNAME=test@example.com,PASSWORD=TestPass1" ^
  --client-id %CLIENT_ID% ^
  --region ap-northeast-1

レスポンス例（抜粋）:

{
    "AuthenticationResult": {
        "IdToken": "eyJra...",
        "AccessToken": "eyJra...",
        "RefreshToken": "eyJjb...",
        "ExpiresIn": 3600,
        "TokenType": "Bearer"
    }
}

IdToken の値をコピーします（次のテストで使用）。

IdToken と AccessToken の違い：

トークン	用途	JWT ペイロード
IdToken	ユーザー認証（今回使用）	email / sub など
AccessToken	Cognito API へのアクセス	sub / scope など

API Gateway の Cognito Authorizer に渡すのは IdToken。AccessToken を渡すと 403 になります。

テスト5: 認証ありでプライベートエンドポイント（/profile）→ 200

set ID_TOKEN=eyJra...（上記で取得した IdToken の値）

curl -H "Authorization: %ID_TOKEN%" %API_URL%/profile

重要： Bearer プレフィックスは不要です。raw JWT（eyJra...）をそのまま Authorization ヘッダーに指定してください。

期待するレスポンス:

{
  "message": "認証成功",
  "email": "test@example.com",
  "sub": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "token_use": "id"
}

Step 8: AWSコンソールで確認（任意）

SAM でデプロイしたリソースはコンソールでも確認できます。

• API Gateway: APIs → cognito-api-lambda-stack → オーソライザー → CognitoAuthorizer が作成されていることを確認
• Cognito: ユーザープール → 作成された User Pool → ユーザー一覧で test@example.com が「確認済み」になっていることを確認
• Lambda: Lambda → 関数 → cognito-api-lambda-stack-ApiFunction-XXXX → 「モニタリング」タブ → テスト5実行後に呼び出し回数が増加していることを確認

Step 9: リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

sam delete --stack-name cognito-api-lambda-stack --region ap-northeast-1

対話式で確認が入ります。両方 y で進めます。

Are you sure you want to delete the stack cognito-api-lambda-stack? [y/N]: y
Are you sure you want to delete the folder cognito-api-lambda-stack in S3? [y/N]: y

削除完了の確認

aws cloudformation describe-stacks --stack-name cognito-api-lambda-stack --region ap-northeast-1

An error occurred (ValidationError): Stack with id cognito-api-lambda-stack does not exist

このメッセージが表示されれば削除完了です。

sam delete で削除されるリソース一覧

コンソール版との大きな違い（SAMのメリット）：
コンソール版では API Gateway / Lambda / Cognito / IAM ロール / ロググループを個別に削除する必要があります。
SAMでは sam delete 1コマンドで全リソースを一括削除できます。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• GenerateSecret: false + ExplicitAuthFlows でシークレットなしクライアントを定義（コンソール版では SPA タイプのクライアントを別途手動作成）
• DefaultAuthorizer の1行で全エンドポイントに Cognito 認証を適用（コンソール版では各エンドポイントに手動設定）
• UserPoolArn: !GetAtt UserPool.Arn で Cognito Authorizer と User Pool を自動連携（コンソール版では手動選択 + トークンのソースを手入力）

コンソール版と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。Cognitoの新UIで変わった操作（「アプリケーションを作成」からのウィザード、シークレットなしクライアントの作成方法、Authorizer のトークンソース設定）など、コンソール版ならではのつまずきポイントを解説しています。

関連記事

Amazon検索[本 AWS 開発]