Amazon API Gateway
開発者ガイド

API Gateway Lambda オーソライザーの使用

Lambda オーソライザー (以前のカスタムオーソライザー) は、Lambda 関数を使用して API へのアクセスを制御する API Gateway の機能です。

Lambda オーソライザーは、OAuth や SAML などのベアラートークン認可戦略を使用する、または発信者 ID を判断するためにリクエストパラメータを使用するカスタム認証スキームを実装する場合に便利です。

クライアントが API のメソッドの 1 つにリクエストを送信すると、API Gateway は Lambda オーソライザーを呼び出します。これは発信者 ID を入力として受け取り、IAM ポリシーを出力として返します。

Lambda オーソライザーには 2 種類あります。

  • トークンベース の Lambda オーソライザー (TOKEN オーソライザーとも呼ばれる) は、JSON Web トークン (JWT) や OAuth トークンなどのベアラートークンで発信者 ID を受け取ります。

  • リクエストパラメータベースの Lambda オーソライザー (REQUEST オーソライザーとも呼ばれます) は、ヘッダー、クエリ文字列パラメータ、stageVariables、および $context 変数の組み合わせで、発信者 ID を受け取ります。

Lambda オーソライザーの関数として、別の AWS アカウントの AWS Lambda 関数を使用できます。詳細については、「クロスアカウントの Lambda オーソライザーを設定する」を参照してください。

ユーザーアカウントの管理にすでに Amazon Cognito ユーザープール を使用している場合、または管理を検討している場合は、Lambda オーソライザーではなく、Amazon Cognito ユーザープールを API のオーソライザーとして使用することを検討してください。

注記

WebSocket API では、リクエストパラメータベースのオーソライザーのみがサポートされています。

Lambda オーソライザーの認証の流れ

次の図は、Lambda オーソライザーの認証の流れを示しています。


                API Gateway Lambda 認証の流れ

API Gateway Lambda 認証の流れ

  1. クライアントは、API Gateway API メソッドでメソッドを呼び出し、ベアラートークンを渡したり、パラメータを要求したりします。

  2. API Gateway は、メソッドに対して Lambda オーソライザーが設定されているかどうかを確認します。その場合、API Gateway は Lambda 関数を呼び出します。

  3. Lambda 関数は、次のような方法で発信者を認証します。

    • OAuth アクセストークンを取得するために OAuth プロバイダーを呼び出します。

    • SAML アサーションを取得するために SAML プロバイダーを呼び出します。

    • リクエストパラメータ値に基づいて IAM ポリシーを生成します。

    • データベースで認証情報を取得します。

  4. 呼び出しが成功すると、Lambda 関数は少なくとも IAM ポリシーとプリンシパル ID を含む出力オブジェクトを返すことによってアクセスを許可します。

  5. API Gateway はポリシーを評価します。

    • アクセスが拒否された場合、API Gateway は 403 ACCESS_DENIED などの適切な HTTP ステータスコードを返します。

    • アクセスが許可されている場合、API Gateway はメソッドを実行します。オーソライザー設定でキャッシュが有効になっている場合、API Gateway はポリシーをキャッシュするため、Lambda オーソライザー関数を再度呼び出す必要はありません。

API Gateway Lambda オーソライザーを作成する手順

Lambda オーソライザーを作成するには、以下のタスクを実行する必要があります。

  1. Lambda コンソールで API Gateway Lambda オーソライザー関数を作成する の説明に従って、Lambda コンソールで Lambda オーソライザー関数を作成します。設計図の例の 1 つを出発点として使用し、必要に応じて入力出力をカスタマイズできます。

  2. API Gateway コンソールを使用して Lambda オーソライザーを設定する で説明されているように、Lambda 関数を API Gateway オーソライザーとして設定し、それを必要とする API メソッドを設定します。あるいは、クロスアカウント Lambda オーソライザーが必要な場合は、クロスアカウントの Lambda オーソライザーを設定する を参照してください。

    注記

    プログラムでオーソライザーを設定することもできます。「AWS CLI、API Gateway REST API、または AWS SDK を使用して Lambda オーソライザーを設定する」を参照してください。

  3. API Gateway Lambda オーソライザーで API を呼び出す の説明に従って、Postman を使用してオーソライザーをテストします。

Lambda コンソールで API Gateway Lambda オーソライザー関数を作成する

Lambda オーソライザーを作成する前に、ロジックを実装する Lambda 関数を作成して認証する必要があります。また、必要に応じて発信者を認証します。Lambda コンソールには Python の設計図が用意されています。[Use a blueprint (設計図を使用する)] を選択して [api-gateway-authorizer-python] 設計図を選択すると使用できます。それ以外の場合は、awslabs GitHub リポジトリの設計図の 1 つを開始点として使用します。

このセクションの他のサービスを呼び出さない Lambda オーソライザー関数の例では、組み込みの AWSLambdaBasicExecutionRole を使用できます。独自の API Gateway Lambda オーソライザーの Lambda 関数を作成する際に、この関数から他の AWS のサービスを呼び出す場合は、Lambda 関数に IAM 実行ロールを割り当てるよう求められます。ロールを作成するには、「AWS Lambda 実行ロール」の手順に従ってください。

例: トークンベースの Lambda オーソライザー関数を作成する

トークンベースの Lambda オーソライザー関数を作成するには、Lambda コンソールに次の Node.js 6.10 コードを入力し、API Gateway コンソールで次のようにテストします。

  1. Lambda コンソールで、[関数の作成] を選択します。

  2. [Author from scratch] を選択します。

  3. 関数の名前を入力します。

  4. [ランタイム] で [Node.js 6.10] を選択します。

  5. [Create function] を選択します。

  6. 以下のコードをコピーしてコードエディタに貼り付けます。

    // A simple TOKEN authorizer example to demonstrate how to use an authorization token // to allow or deny a request. In this example, the caller named 'user' is allowed to invoke // a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke // the request if the token value is 'deny'. If the token value is 'Unauthorized', the function // returns the 'Unauthorized' error with an HTTP status code of 401. For any other token value, // the authorizer returns an 'Invalid token' error. exports.handler = function(event, context, callback) { var token = event.authorizationToken; switch (token) { case 'allow': callback(null, generatePolicy('user', 'Allow', event.methodArn)); break; case 'deny': callback(null, generatePolicy('user', 'Deny', event.methodArn)); break; case 'unauthorized': callback("Unauthorized"); // Return a 401 Unauthorized response break; default: callback("Error: Invalid token"); } }; // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; }
  7. [Save] を選択します。

  8. API Gateway コンソールで、シンプルな API をまだ作成していない場合は作成します。

  9. API リストから API を選択します。

  10. [Authorizers (オーソライザー)] を選択します。

  11. [新しいオーソライザーの作成] を選択します。

  12. オーソライザーの名前を入力します。

  13. [Type (タイプ)] で、[Lambda] を選択します。

  14. [Lambda Function (Lambda 関数)] で、Lambda オーソライザー関数を作成したリージョンを選択し、ドロップダウンリストで関数名を選択します。

  15. [Lambda Invoke Role (Lambda 呼び出しロール)] は空白のままにします。

  16. [Lambda Event Payload (Lambda イベントペイロード)] の場合は、[Token (トークン)] を選択します。

  17. [Token Source (トークンのソース)] に tokenHeader と入力します。

  18. [Test] を選択します。

  19. [tokenHeader] 値に allow と入力します。

  20. [Test] を選択します。

この例では、API がメソッドリクエストを受信すると、API Gateway は event.authorizationToken 属性でこの Lambda オーソライザー関数にソーストークンを渡します。Lambda オーソライザー関数はトークンを読み取り、次のように動作します。

  • トークン値が 'allow' の場合、オーソライザー関数は 200 OK HTTP レスポンスと次のような IAM ポリシーを返し、メソッドリクエストは成功します。

    { "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
  • トークン値が 'deny' の場合、オーソライザー関数は 403 Forbidden HTTP レスポンスと次のような Deny IAM ポリシーを返し、メソッドリクエストは失敗します。

    { "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
  • トークン値が 'unauthorized' の場合、認証機能は 401 Unauthorized HTTP レスポンスを返し、メソッド呼び出しは失敗します。

  • それ以外のトークンの場合、クライアントは 500 Internal Server Error レスポンスを受け取り、メソッド呼び出しは失敗します。

注記

本番稼働コードでは、権限を付与する前にユーザーの認証が必要になる場合があります。その場合は、そのプロバイダーのドキュメントの指示に従って認証プロバイダーを呼び出すことで、Lambda 関数に認証ロジックを追加できます。

IAM オーソライザー関数は、Lambda ポリシーだけでなく、発信者のプリンシパル ID を返す必要があります。オプションで、context オブジェクトを返すこともできます。これには、統合バックエンドに渡すことができる追加情報が含まれます。詳細については、「Amazon API Gateway Lambda オーソライザーからの出力」を参照してください。

例: リクエストベースの Lambda オーソライザー関数を作成する

リクエストベースの Lambda オーソライザー関数を作成するには、Lambda コンソールに次の Node.js 6.10 コードを入力し、API Gateway コンソールで次のようにテストします。

  1. Lambda コンソールで、[関数の作成] を選択します。

  2. [Author from scratch] を選択します。

  3. 関数の名前を入力します。

  4. [ランタイム] で [Node.js 6.10] を選択します。

  5. [Create function] を選択します。

  6. 以下のコードをコピーしてコードエディタに貼り付けます。

    exports.handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // A simple REQUEST authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied HeaderAuth1 header, QueryString1 // query parameter, and stage variable of StageVar1 all match // specified values of 'headerValue1', 'queryValue1', and 'stageValue1', // respectively. // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var pathParameters = event.pathParameters; var stageVariables = event.stageVariables; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var restApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var method = apiGatewayArnTmp[2]; var resource = '/'; // root resource if (apiGatewayArnTmp[3]) { resource += apiGatewayArnTmp[3]; } // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. var authResponse = {}; var condition = {}; condition.IpAddress = {}; if (headers.HeaderAuth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1" && stageVariables.StageVar1 === "stageValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback("Unauthorized"); } } // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); }
  7. [Save] を選択します。

  8. API Gateway コンソールで、シンプルな API をまだ作成していない場合は作成します。

  9. API リストから API を選択します。

  10. [Authorizers (オーソライザー)] を選択します。

  11. [新しいオーソライザーの作成] を選択します。

  12. オーソライザーの名前を入力します。

  13. [Type (タイプ)] で、[Lambda] を選択します。

  14. [Lambda Function (Lambda 関数)] で、Lambda オーソライザー関数を作成したリージョンを選択し、ドロップダウンリストで関数名を選択します。

  15. [Lambda Invoke Role (Lambda 呼び出しロール)] は空白のままにします。

  16. [Lambda Event Payload (Lambda イベントペイロード)] の場合は、[Request (リクエスト)] を選択します。

  17. [Identity Sources (ID ソース)] の下に、HeaderAuth1 という名前の [Header (ヘッダー)]、QueryString1 という名前の [Query String (クエリ文字列)]、および StageVar1 という名前の [Stage Variable (ステージ変数)] を追加します。

  18. [Test] を選択します。

  19. [HeaderAuth1] に、headerValue1 と入力します。[QueryString1] に、queryValue1 と入力します。[StageVar1] に、stageValue1 と入力します。

  20. [Test] を選択します。

この例では、Lambda オーソライザー関数は入力パラメータをチェックして次のように動作します。

  • 必要なすべてのパラメータ値が予想値と一致する場合、オーソライザー関数は 200 OK HTTP レスポンスと次のような IAM ポリシーを返し、メソッドリクエストは成功します。

    { "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
  • そうでない場合、オーソライザー関数は 401 Unauthorized HTTP レスポンスを返し、メソッド呼び出しは失敗します。

注記

本番稼働コードでは、権限を付与する前にユーザーの認証が必要になる場合があります。その場合は、そのプロバイダーのドキュメントの指示に従って認証プロバイダーを呼び出すことで、Lambda 関数に認証ロジックを追加できます。

IAM オーソライザー関数は、Lambda ポリシーだけでなく、発信者のプリンシパル ID を返す必要があります。オプションで、context オブジェクトを返すこともできます。これには、統合バックエンドに渡すことができる追加情報が含まれます。詳細については、「Amazon API Gateway Lambda オーソライザーからの出力」を参照してください。