API Gateway Lambdaオーソライザーの作り方｜トークン型とリクエスト型

Lambda オーソライザーは、API Gateway が本体の処理の前に呼ぶ Lambda 関数です。 受け取ったトークンやヘッダーを調べ、REST API なら IAM ポリシー（Allow／Deny）、HTTP API なら {"isAuthorized": true/false} を返します。認証に失敗したら raise Exception("Unauthorized") で 401 にします。

# 返す形（REST API）
{
    "principalId": "ユーザーID",
    "policyDocument": {
        "Version": "2012-10-17",
        "Statement": [{"Action": "execute-api:Invoke", "Effect": "Allow",
                       "Resource": "arn:aws:execute-api:ap-northeast-1:123456789012:abcdef123/prod/*/*"}]
    },
    "context": {"sub": "...", "scope": "..."}
}

確認環境：Python 3.11・awslambdaric 4.2.0・PyJWT 2.15.1・cryptography 50.0.2（Linux）、AWS CLI 1.46.1。オーソライザーの関数を awslambdaric（Lambda の Python ランタイムと同じ実行部）で起動し、Lambda の Runtime API と同じ形でイベントを渡すサーバーを手元に用意して、TOKEN・REQUEST・HTTP API（2.0）の 11 通りのイベントの返り値とエラーの形を記録しました。JWT は自分で作った RSA 鍵で署名し、JWKS を返すサーバーも手元に置いています。create-authorizer は moto 5.2.4 のサーバーモードで通しました。API Gateway が返り値をどう扱うか（401・403・500、キャッシュ）は、AWS のドキュメントと AWS re:Post の記事に基づいています（確認日 2026年10月13日）。

流れ：API Gateway・オーソライザー・本体

クライアント ──Authorization: Bearer eyJ...──► API Gateway
                                              │ ① ID ソースが無い → 401（オーソライザーは呼ばれない）
                                              │ ② キャッシュにあれば、それを使う
                                              ▼
                                     Lambda オーソライザー
                                              │ Allow ポリシー → ③ 本体へ（context を渡す）
                                              │ Deny ポリシー → 403
                                              │ raise Exception("Unauthorized") → 401
                                              │ それ以外の例外・形の誤り → 500
                                              ▼
                                     本体（Lambda・HTTP など）

REST API と HTTP API の違いそのものは、関連記事「API Gateway Lambda｜REST APIとHTTP APIの違い」で扱っています。

トークン型とリクエスト型の選び方

Bearer トークン（JWT）を1つ見るだけなら TOKEN、IP やクエリも見たい・経路ごとに判定したいなら REQUEST が向いています。

受け取るイベントの形

{
  "type": "TOKEN",
  "authorizationToken": "Bearer eyJraWQiOi...",
  "methodArn": "arn:aws:execute-api:ap-northeast-1:123456789012:abcdef123/prod/GET/items/1"
}

REQUEST 型（REST API）は、methodArn に加えて resource・path・httpMethod・headers・queryStringParameters・pathParameters・stageVariables・requestContext が届きます。HTTP API のペイロード 2.0 は、version: "2.0"・routeArn・identitySource（配列）・routeKey・headers（名前は小文字）などです。

完成コード（Python）：JWT を検証して Allow／Deny

Cognito・Auth0・Keycloak など、JWKS（公開鍵の一覧）を公開している発行元の JWT を検証します。1つの関数で TOKEN・REQUEST・HTTP API（簡易レスポンス）に対応させています。

"""API Gateway Lambda オーソライザー（TOKEN / REQUEST / HTTP API 2.0 簡易レスポンス対応）"""
import os
import jwt  # PyJWT（pip install "pyjwt[crypto]" -t .）

JWKS_URL = os.environ["JWKS_URL"]          # 例: https://cognito-idp.<region>.amazonaws.com/<pool-id>/.well-known/jwks.json
ISSUER = os.environ["ISSUER"]              # 例: https://cognito-idp.<region>.amazonaws.com/<pool-id>
AUDIENCE = os.environ.get("AUDIENCE")      # aud を確かめるとき（無ければ確かめない）
REQUIRED_SCOPE = os.environ.get("REQUIRED_SCOPE")

# コールドスタートのときに1回だけ作る。JWKS はキャッシュされ、知らない kid が来たときに取り直す
_jwks = jwt.PyJWKClient(JWKS_URL, cache_keys=True, lifespan=3600)


def _verify(token: str) -> dict:
    if token.lower().startswith("bearer "):
        token = token[7:]
    key = _jwks.get_signing_key_from_jwt(token).key
    claims = jwt.decode(
        token,
        key,
        algorithms=["RS256"],              # 受け付けるアルゴリズムを固定する（none・HS256 を拒む）
        issuer=ISSUER,
        audience=AUDIENCE,
        options={"require": ["exp", "iss", "sub"], "verify_aud": AUDIENCE is not None},
        leeway=30,
    )
    if REQUIRED_SCOPE and REQUIRED_SCOPE not in claims.get("scope", "").split():
        raise PermissionError("scope")
    return claims


def _wildcard_arn(method_arn: str) -> str:
    # arn:aws:execute-api:ap-northeast-1:123456789012:abcdef123/prod/GET/items/1
    #   → arn:aws:execute-api:ap-northeast-1:123456789012:abcdef123/prod/*/*
    api_arn, stage = method_arn.split("/")[:2]
    return f"{api_arn}/{stage}/*/*"


def _policy(principal_id: str, effect: str, resource: str, context: dict) -> dict:
    return {
        "principalId": principal_id,
        "policyDocument": {
            "Version": "2012-10-17",
            "Statement": [{"Action": "execute-api:Invoke", "Effect": effect, "Resource": resource}],
        },
        # context の値は文字列・数値・真偽値だけ（オブジェクト・配列は不可）
        "context": context,
    }


def _context(claims: dict) -> dict:
    return {
        "sub": claims["sub"],
        "email": claims.get("email", ""),
        "scope": claims.get("scope", ""),
        "groups": ",".join(claims.get("cognito:groups", [])),  # 配列は文字列にして渡す
    }


def lambda_handler(event, context):
    # HTTP API（ペイロード 2.0・簡易レスポンス）
    if event.get("version") == "2.0":
        token = (event.get("headers") or {}).get("authorization", "")
        try:
            claims = _verify(token)
        except Exception as e:
            print(f"deny: {type(e).__name__}: {e}")
            return {"isAuthorized": False}
        return {"isAuthorized": True, "context": _context(claims)}

    # REST API（TOKEN：authorizationToken、REQUEST：headers）
    if event.get("type") == "TOKEN":
        token = event.get("authorizationToken", "")
    else:
        headers = {k.lower(): v for k, v in (event.get("headers") or {}).items()}
        token = headers.get("authorization", "")

    try:
        claims = _verify(token)
    except PermissionError:
        # 本人だが権限が足りない → 403
        return _policy("user", "Deny", _wildcard_arn(event["methodArn"]), {})
    except Exception as e:
        print(f"unauthorized: {type(e).__name__}: {e}")
        raise Exception("Unauthorized")  # 文字列はこの通り。401 になる

    return _policy(claims["sub"], "Allow", _wildcard_arn(event["methodArn"]), _context(claims))

Cognito の ID トークン・アクセストークンの違いと token_use の確かめ方は、関連記事「Amazon Cognito入門｜ユーザープール作成とJWT検証コード」で扱っています。JWT そのものの注意点は、関連記事「JWTとは｜仕組みと、安全に使うための注意点」で扱っています。

パッケージにする

PyJWT の RS256 は cryptography を使います。cryptography は OS・CPU ごとのバイナリなので、Lambda のアーキテクチャに合わせて取ってきます。

mkdir -p build && cp authorizer.py build/
pip install "pyjwt[crypto]" -t build/ \
  --platform manylinux2014_x86_64 --only-binary=:all: --python-version 3.13
(cd build && zip -qr ../authorizer.zip .)

aws lambda create-function --function-name jwt-authorizer \
  --runtime python3.13 --architectures x86_64 \
  --handler authorizer.lambda_handler --zip-file fileb://authorizer.zip \
  --role arn:aws:iam::123456789012:role/lambda-basic-execution \
  --environment 'Variables={JWKS_URL=https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_EXAMPLE/.well-known/jwks.json,ISSUER=https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_EXAMPLE}'

arm64 の関数なら manylinux2014_aarch64 にします。Lambda の作成と更新は、関連記事「AWS CLIでLambdaを作成・更新 環境変数とレイヤー」で扱っています。

動かして確かめた返り値（11 通り）

手元で RSA 鍵を作り、JWKS を返すサーバーを置いて、上のコードを awslambdaric で起動しました。REQUIRED_SCOPE=items/write にしています。

関数のログに出た、失敗の理由です（PyJWT の例外）。

unauthorized: ExpiredSignatureError: Signature has expired
unauthorized: InvalidIssuerError: Invalid issuer
unauthorized: PyJWKClientError: Unable to find a signing key that matches: "kid-9"
unauthorized: InvalidSignatureError: Signature verification failed
unauthorized: InvalidAlgorithmError: The specified alg value is not allowed
unauthorized: DecodeError: Invalid header string: 'utf-8' codec can't decode byte 0xb7 in position 1: invalid start byte
deny: ExpiredSignatureError: Signature has expired

Allow のときに Runtime API へ返された中身です。

{"principalId": "4e1f-user-1",
 "policyDocument": {"Version": "2012-10-17",
   "Statement": [{"Action": "execute-api:Invoke", "Effect": "Allow",
     "Resource": "arn:aws:execute-api:ap-northeast-1:123456789012:abcdef123/prod/*/*"}]},
 "context": {"sub": "4e1f-user-1", "email": "", "scope": "items/read items/write", "groups": "admin,dev"}}

raise Exception("Unauthorized") のときは、関数のエラーとして次の JSON が Runtime API に送られました。API Gateway は、この errorMessage が Unauthorized であることを見て 401 を返します。

{"errorMessage": "Unauthorized", "errorType": "Exception", "requestId": "9d0ba85b-...", "stackTrace": ["..."]}

Lambda のハンドラとローカルでのテストのしかたは、関連記事「AWS Lambda Python入門｜3.14対応handler例とローカルテスト」で扱っています。

REST API のポリシー形式と HTTP API の簡易レスポンス

{
  "isAuthorized": true,
  "context": {
    "sub": "4e1f-user-1",
    "scope": "items/read items/write"
  }
}

HTTP API でも、簡易レスポンスを有効にしなければ IAM ポリシー形式で返せます。ペイロード 2.0 で経路ごとに許可を分けたいときは、ポリシー形式にします。

context を本体に渡す

ドキュメントでは、context の値はすべて文字列にされ、JSON のオブジェクトや配列は値にできません。 上のコードで groups をカンマ区切りの文字列にしているのはこのためです。

キャッシュ：TTL と Resource をワイルドカードにする理由

キャッシュされるのは、オーソライザーが返したポリシーそのものです。 同じトークンで TTL の間に来た別の経路のリクエストにも、そのポリシーが使われます。

① GET /items/1 → オーソライザーが Resource = .../prod/GET/items/1 で Allow → キャッシュ
② 同じトークンで GET /items/2 → キャッシュのポリシーを使う
   → Resource が .../GET/items/1 だけなので、/items/2 は許可されていない → 403

AWS re:Post の記事では、{proxy+} のような経路で、キャッシュされたポリシーの経路と次のリクエストの経路が違うと User is not authorized to access this resource の 403 になる、と説明されています。避け方として、ポリシーの Resource をワイルドカード（*/*）にして、API の全メソッド・全経路に効くようにすることが挙げられています。API Gateway のドキュメントでも、キャッシュを有効にするなら、ポリシーが API の全リソース・全メソッドに当てはまるようにするよう書かれています。

経路ごとに権限を変えたい場合の例です。管理者だけ /admin/* を許可します。

def _resources(method_arn: str, groups: list[str]) -> list[str]:
    api_arn, stage = method_arn.split("/")[:2]
    res = [f"{api_arn}/{stage}/GET/items", f"{api_arn}/{stage}/GET/items/*"]
    if "admin" in groups:
        res.append(f"{api_arn}/{stage}/*/admin/*")
    return res

Resource に ARN の配列を入れると、キャッシュされたポリシーでも、各経路の許可・拒否が正しく決まります。ARN の形は、関連記事「AWS ARNとは？形式の読み方とサービス別の書き方一覧」で扱っています。

ログアウトしたトークンや権限を変えたユーザーも、TTL の間はキャッシュの結果で通ります。 すぐに反映したいときは、キャッシュを消します。

aws apigateway flush-stage-authorizers-cache --rest-api-id abcdef123 --stage-name prod

HTTP API で経路ごとにキャッシュを分けるには、ドキュメントでは ID ソースに $context.routeKey を足す方法が案内されています。

401・403・500 の出方

401 にするには、例外の文字列を Unauthorized の通りにします。 ドキュメントの TOKEN 型のサンプルでは、Unauthorized 以外の結果は 500 になると説明されています。

ゲートウェイの応答（UNAUTHORIZED・ACCESS_DENIED など）は、REST API では本文やヘッダーを変えられます。CORS のヘッダーを 401・403 にも付けたいときに使います。

aws apigateway put-gateway-response --rest-api-id abcdef123 \
  --response-type UNAUTHORIZED \
  --response-parameters '{"gatewayresponse.header.Access-Control-Allow-Origin":"'"'"'*'"'"'"}'

500 の原因は、REST API なら実行ログ（CloudWatch Logs）、HTTP API ならアクセスログに $context.authorizer.error を入れて調べるよう、ドキュメントで案内されています。ログの検索は、関連記事「CloudWatch LogsのAWS CLI tail・検索・クエリ例」で扱っています。

CLI で設定する

REST API

API_ID=abcdef123
FN_ARN=arn:aws:lambda:ap-northeast-1:123456789012:function:jwt-authorizer

# TOKEN 型
AUTH_ID=$(aws apigateway create-authorizer --rest-api-id $API_ID \
  --name jwt-token --type TOKEN \
  --authorizer-uri arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03-31/functions/$FN_ARN/invocations \
  --identity-source method.request.header.Authorization \
  --identity-validation-expression '^Bearer [-0-9A-Za-z_.]+$' \
  --authorizer-result-ttl-in-seconds 300 \
  --query id --output text)

# REQUEST 型（ヘッダー＋メソッドでキャッシュを分ける）
aws apigateway create-authorizer --rest-api-id $API_ID \
  --name jwt-request --type REQUEST \
  --authorizer-uri arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03-31/functions/$FN_ARN/invocations \
  --identity-source 'method.request.header.Authorization,context.httpMethod' \
  --authorizer-result-ttl-in-seconds 300

# API Gateway に関数を呼ぶ権限を与える
aws lambda add-permission --function-name jwt-authorizer \
  --statement-id apigw-authorizer --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:ap-northeast-1:123456789012:$API_ID/authorizers/$AUTH_ID"

# メソッドに付ける
aws apigateway update-method --rest-api-id $API_ID --resource-id a1b2c3 --http-method GET \
  --patch-operations op=replace,path=/authorizationType,value=CUSTOM op=replace,path=/authorizerId,value=$AUTH_ID

# 試す（API Gateway のテスト呼び出し。Deny でも 200 で結果が返る）
aws apigateway test-invoke-authorizer --rest-api-id $API_ID --authorizer-id $AUTH_ID \
  --headers Authorization="Bearer eyJ..."

aws apigateway create-deployment --rest-api-id $API_ID --stage-name prod

moto で create-authorizer（TOKEN）を通した応答です。

{
    "id": "oturrahmvc",
    "name": "jwt-token",
    "type": "TOKEN",
    "authorizerUri": "arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-northeast-1:123456789012:function:jwt-authorizer/invocations",
    "identitySource": "method.request.header.Authorization",
    "authorizerResultTtlInSeconds": 300
}

HTTP API

aws apigatewayv2 create-authorizer --api-id $HTTP_API_ID \
  --authorizer-type REQUEST --name jwt-http \
  --identity-source '$request.header.Authorization' \
  --authorizer-uri arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03-31/functions/$FN_ARN/invocations \
  --authorizer-payload-format-version 2.0 \
  --enable-simple-responses \
  --authorizer-result-ttl-in-seconds 300

aws apigatewayv2 update-route --api-id $HTTP_API_ID --route-id abc123 \
  --authorization-type CUSTOM --authorizer-id def123

moto では、AuthorizerPayloadFormatVersion: "2.0"・EnableSimpleResponses: true・IdentitySource: ["$request.header.Authorization"] の形で作られました。

HTTP API で JWT を確かめるだけなら、Lambda を使わない「JWT オーソライザー」（--authorizer-type JWT）もあります。 発行元（issuer）と audience を指定すると、API Gateway が署名と期限を確かめます。独自の判定（DB の参照、IP の制限、context の組み立て）が要るときに Lambda オーソライザーを使います。

よくある質問

Q. 401 と 403 は、どう使い分けますか。 A. トークンが無い・壊れている・期限切れなど「誰か分からない」は 401（raise Exception("Unauthorized")）、本人だが権限が無いは 403（Deny）にします。クライアントは、401 ならログインし直し、403 なら権限の不足と判断できます。

Q. オーソライザーの関数が遅いと、API 全体が遅くなりますか。 A. キャッシュが効かないリクエストごとに関数が呼ばれるため、その分の時間が足されます。JWKS の取得を関数の外で1回にする、キャッシュの TTL を設ける、が主な対策です。

Q. principalId には何を入れますか。 A. ユーザーを表す ID（JWT の sub など）です。REST API では $context.authorizer.principalId で本体から読めます。返さないと呼び出しは失敗します。

Q. API キー（使用量プラン）と組み合わせられますか。 A. REST API で apiKeySource を AUTHORIZER にすると、オーソライザーが返す usageIdentifierKey の値を API キーとして使います。

まとめ

• REST API は IAM ポリシー＋principalId＋context、HTTP API は isAuthorized＋context（簡易レスポンス）
• 認証の失敗は raise Exception("Unauthorized") で 401、権限不足は Deny で 403、それ以外の例外は 500
• JWT は アルゴリズムを固定し、iss・exp（必要なら aud・scope）を確かめる。PyJWT の PyJWKClient は関数の外で作る
• キャッシュ（REST の既定 300 秒）を使うなら、Resource をワイルドカードか許可する経路の配列に。methodArn だけだと別の経路で 403
• context の値は文字列（配列はカンマ区切りなどにする）

参考・出典

確認日はいずれも 2026年10月13日です。

• Amazon API Gateway 開発者ガイド「API Gateway Lambda オーソライザーを使用する」：https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html
• Amazon API Gateway 開発者ガイド「API Gateway Lambda オーソライザーを設定する」：https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/configure-api-gateway-lambda-authorization.html
• Amazon API Gateway 開発者ガイド「API Gateway Lambda オーソライザーへの入力」：https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-lambda-authorizer-input.html
• Amazon API Gateway Developer Guide「Output from an API Gateway Lambda authorizer」：https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-lambda-authorizer-output.html
• Amazon API Gateway Developer Guide「Control access to HTTP APIs with AWS Lambda authorizers」：https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html
• Amazon API Gateway Developer Guide「Gateway response types for API Gateway」：https://docs.aws.amazon.com/apigateway/latest/developerguide/supported-gateway-response-types.html
• Amazon API Gateway API Reference（CreateAuthorizer の authorizerResultTtlInSeconds）：https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html
• AWS re:Post ナレッジセンター「How do I troubleshoot 403 errors from API Gateway with a Lambda authorizer?」：https://repost.aws/knowledge-center/api-gateway-403-error-lambda-authorizer
• AWS re:Post ナレッジセンター「Lambda authorizer errors」：https://repost.aws/knowledge-center/api-gateway-lambda-authorization-errors
• AWS Compute Blog「Introducing IAM and Lambda authorizers for Amazon API Gateway HTTP APIs」：https://aws.amazon.com/blogs/compute/introducing-iam-and-lambda-authorizers-for-amazon-api-gateway-http-apis/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。