[AWS,APIGateway,SAM]InvokeRoleのCALLER_CREDENTIALSについて

AWS SAMでtemplate.yamlを書いており、APIGatewayのリソースを作成しようとした際に迷ったので記事にしておきます。
AWS公式の記事は少し読みづらいです。
とても限定的な記事なのでほとんど読まれないと思いますが、同じような疑問を思っている人の助けになれば。

InvokeRoleでは何を設定するのか

InvokeRokeに設定するのはずばり__「APIGatewayの権限」__になります。
IAMロールのARNを入れれば、APIGatewayの権限は指定したIAMロールと同等の権限をもつことになります。

公式ドキュメントによると、InvokeRoleに設定できるのは以下の値です。
CALLER_CREDENTIALS, NONE, IAMRoleArn
何も設定しない場合、CALLER_CREDENTIALSが適用されます。

さて、ここでCALLER_CREDENTIALSについてです。
一見すると意味が分かりません。

CALLER_CREDENTIALSとは

CALLER_CREDENTIALSとは、APIGatewayを呼び出す際に渡した認証情報をそのまま使うということです。CALLERのCREDENTIALSですので、呼び出し側の認証情報です。
実際にマネジメントコンソールのヘルプにも、以下のように表示されています。

ここで、「APIGatewayによって受信された認証情報ってなんじゃい！」という話になってきます。

具体例を見ていきましょう。
APIGatewayを呼び出す際に、以下のように__IAMロールの認証情報__を一緒に送ることが出来ます。
以下のソースではaws_requests_authというライブラリを利用していますので、詳しい実装を知りたい場合はこちらを参考にしてください。

    credentials = get_credentials() # stsからIAMロールのcredentialsを取得
    auth = AWSRequestsAuth(
        aws_access_key=credentials['AccessKeyId'],
        aws_secret_access_key=credentials['SecretAccessKey'],
        aws_host=aws_host,
        aws_region=REGION_NAME,
        aws_service='execute-api'
    )
    headers = {'x-amz-security-token': credentials['SessionToken']}

    response = requests.post(
        url, json={"foo": "bar"}, auth=auth, headers=headers)

この時、APIGatewayでは__IAMロールの認証情報__が受信されています。
というわけで、このような形で「受信された認証情報」をつかうことになるわけです。

なので、ここで指定しているIAMロールの権限と同等の権限をAPIGatewayが行使することになります。APIGatewayの呼び先がLambdaである場合、IAMロールにはLambdaの実行権限を付けてあげないと実行できなくなるということです。