Nutzlastformatversion Antwortformat des Lambda-Genehmigers Beispiel für Lambda-Genehmiger-Funktionen Identitätsquellen Zwischenspeichern der Antworten des Genehmigers Erstellen eines Lambda-Genehmigers Fehlerbehebung für Lambda-Genehmiger

Steuern Sie den Zugriff HTTP APIs mit AWS Lambda Autorisierern

Sie verwenden einen Lambda-Autorisierer, um eine Lambda-Funktion zu verwenden, um den Zugriff auf Ihre zu kontrollieren. HTTP API Wenn dann ein Client Ihren aufruftAPI, ruft API Gateway Ihre Lambda-Funktion auf. APIGateway verwendet die Antwort Ihrer Lambda-Funktion, um festzustellen, ob der Client auf Ihre API zugreifen kann.

Nutzlastformatversion

Die Version des Authorizer-Payload-Formats spezifiziert das Format der Daten, die API Gateway an einen Lambda-Autorisierer sendet, und wie API Gateway die Antwort von Lambda interpretiert. Wenn Sie keine Version im Payload-Format angeben, wird standardmäßig die AWS Management Console neueste Version verwendet. Wenn Sie einen Lambda-Autorisierer mithilfe von AWS CLI, oder an SDK erstellen AWS CloudFormation, müssen Sie einen angeben. authorizerPayloadFormatVersion Die unterstützten Werte sind 1.0 und 2.0.

Wenn Sie Kompatibilität mit benötigen RESTAPIs, verwenden Sie Version. 1.0

Die folgenden Beispiele zeigen die Struktur jeder Nutzlastformatversion.

2.0


{
  "version": "2.0",
  "type": "REQUEST",
  "routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
  "identitySource": ["user1", "123"],
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": ["cookie1", "cookie2"],
  "headers": {
    "header1": "value1",
    "header2": "value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "api-id",
    "authentication": {
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "IP",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "pathParameters": { "parameter1": "value1" },
  "stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}

1.0


{
  "version": "1.0",
  "type": "REQUEST",
  "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
  "identitySource": "user1,123",
  "authorizationToken": "user1,123",
  "resource": "/request",
  "path": "/request",
  "httpMethod": "GET",
  "headers": {
    "X-AMZ-Date": "20170718T062915Z",
    "Accept": "*/*",
    "HeaderAuth1": "headerValue1",
    "CloudFront-Viewer-Country": "US",
    "CloudFront-Forwarded-Proto": "https",
    "CloudFront-Is-Tablet-Viewer": "false",
    "CloudFront-Is-Mobile-Viewer": "false",
    "User-Agent": "..."
  },
  "queryStringParameters": {
    "QueryString1": "queryValue1"
  },
  "pathParameters": {},
  "stageVariables": {
    "StageVar1": "stageValue1"
  },
  "requestContext": {
    "path": "/request",
    "accountId": "123456789012",
    "resourceId": "05c7jb",
    "stage": "test",
    "requestId": "...",
    "identity": {
      "apiKey": "...",
      "sourceIp": "...",
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "resourcePath": "/request",
    "httpMethod": "GET",
    "apiId": "abcdef123"
  }
}

Antwortformat des Lambda-Genehmigers

Die Nutzlastformatversion bestimmt auch die Struktur der Antwort, die von Ihrer Lambda-Funktion zurückgeben werden muss.

Lambda-Funktionsantwort für Format 1.0

Wenn Sie die 1.0 Formatversion wählen, müssen Lambda-Autorisierer eine IAM Richtlinie zurückgeben, die den Zugriff auf Ihre Route erlaubt oder verweigert. API Sie können die IAM Standardrichtliniensyntax in der Richtlinie verwenden. Beispiele für IAM-Richtlinien finden Sie unter Steuern Sie den Zugriff für das Aufrufen eines API. Mit können Sie Kontexteigenschaften an Lambda-Integrationen oder -Zugriffsprotokolle übergebe $context.authorizer.property. Das context-Objekt ist optional und claims ist ein reservierter Platzhalter, der nicht als Kontextobjekt verwendet werden kann. Weitere Informationen hierzu finden Sie unter Passen Sie die HTTP API Zugriffsprotokolle an.


{
  "principalId": "abcdef", // The principal user identification associated with the token sent by the client.
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": "execute-api:Invoke",
        "Effect": "Allow|Deny",
        "Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
      }
    ]
  },
  "context": {
    "exampleKey": "exampleValue"
  }
}

Lambda-Funktionsantwort für Format 2.0

Wenn Sie die 2.0 Formatversion wählen, können Sie einen booleschen Wert oder eine IAM Richtlinie zurückgeben, die die IAM Standardrichtliniensyntax aus Ihrer Lambda-Funktion verwendet. Um einen booleschen Wert zurückzugeben, aktivieren Sie einfache Antworten für den Genehmiger. Die folgenden Beispiele veranschaulichen das Format, das Sie für die Rückgabe Ihrer Lambda-Funktion codieren müssen. Das Objekt context ist optional. Mit können Sie Kontexteigenschaften an Lambda-Integrationen oder -Zugriffsprotokolle übergebe $context.authorizer.property. Weitere Informationen hierzu finden Sie unter Passen Sie die HTTP API Zugriffsprotokolle an.

Beispiel für Lambda-Genehmiger-Funktionen

Die Lambda-Funktionen des folgenden Node.js-Beispiels veranschaulichen die erforderlichen Antwortformate, die Sie von Ihrer Lambda-Funktion für Formatversion 2.0 der Nutzlast zurückgeben müssen.

Simple response - Node.js


export const handler = async(event) => {
    let response = {
        "isAuthorized": false,
        "context": {
            "stringKey": "value",
            "numberKey": 1,
            "booleanKey": true,
            "arrayKey": ["value1", "value2"],
            "mapKey": {"value1": "value2"}
        }
    };
    
    if (event.headers.authorization === "secretToken") {
        console.log("allowed");
        response = {
            "isAuthorized": true,
            "context": {
                "stringKey": "value",
                "numberKey": 1,
                "booleanKey": true,
                "arrayKey": ["value1", "value2"],
                "mapKey": {"value1": "value2"}
            }
        };
    }

    return response;

};

Simple response - Python


import json


def lambda_handler(event, context):
    response = {
        "isAuthorized": False,
        "context": {
            "stringKey": "value",
            "numberKey": 1,
            "booleanKey": True,
            "arrayKey": ["value1", "value2"],
            "mapKey": {"value1": "value2"}
        }
    }

    try:
        if (event["headers"]["authorization"] == "secretToken"):
            response = {
                "isAuthorized": True,
                "context": {
                    "stringKey": "value",
                    "numberKey": 1,
                    "booleanKey": True,
                    "arrayKey": ["value1", "value2"],
                    "mapKey": {"value1": "value2"}
                }
            }
            print('allowed')
            return response
        else:
            print('denied')
            return response
    except BaseException:
        print('denied')
        return response

IAM policy - Node.js


export const handler = async(event) => {
  if (event.headers.authorization == "secretToken") {
    console.log("allowed");
    return {
      "principalId": "abcdef", // The principal user identification associated with the token sent by the client.
      "policyDocument": {
        "Version": "2012-10-17",
        "Statement": [{
          "Action": "execute-api:Invoke",
          "Effect": "Allow",
          "Resource": event.routeArn
        }]
      },
      "context": {
        "stringKey": "value",
        "numberKey": 1,
        "booleanKey": true,
        "arrayKey": ["value1", "value2"],
        "mapKey": { "value1": "value2" }
      }
    };
  }
  else {
    console.log("denied");
    return {
      "principalId": "abcdef", // The principal user identification associated with the token sent by the client.
      "policyDocument": {
        "Version": "2012-10-17",
        "Statement": [{
          "Action": "execute-api:Invoke",
          "Effect": "Deny",
          "Resource": event.routeArn
        }]
      },
      "context": {
        "stringKey": "value",
        "numberKey": 1,
        "booleanKey": true,
        "arrayKey": ["value1", "value2"],
        "mapKey": { "value1": "value2" }
      }
    };
  }
};

IAM policy - Python


import json


def lambda_handler(event, context):
    response = {
        # The principal user identification associated with the token sent by
        # the client.
        "principalId": "abcdef",
        "policyDocument": {
            "Version": "2012-10-17",
            "Statement": [{
                "Action": "execute-api:Invoke",
                "Effect": "Deny",
                "Resource": event["routeArn"]
            }]
        },
        "context": {
            "stringKey": "value",
            "numberKey": 1,
            "booleanKey": True,
            "arrayKey": ["value1", "value2"],
            "mapKey": {"value1": "value2"}
        }
    }

    try:
        if (event["headers"]["authorization"] == "secretToken"):
            response = {
                # The principal user identification associated with the token
                # sent by the client.
                "principalId": "abcdef",
                "policyDocument": {
                    "Version": "2012-10-17",
                    "Statement": [{
                        "Action": "execute-api:Invoke",
                        "Effect": "Allow",
                        "Resource": event["routeArn"]
                    }]
                },
                "context": {
                    "stringKey": "value",
                    "numberKey": 1,
                    "booleanKey": True,
                    "arrayKey": ["value1", "value2"],
                    "mapKey": {"value1": "value2"}
                }
            }
            print('allowed')
            return response
        else:
            print('denied')
            return response
    except BaseException:
        print('denied')
        return response

Identitätsquellen

Sie können optional Identitätsquellen für einen Lambda-Genehmiger angeben. Identitätsquellen geben den Speicherort der Daten an, die für die Autorisierung einer Anforderung erforderlich sind. Beispielsweise können Sie Header- oder Abfragezeichenfolgenwerte als Identitätsquellen angeben. Wenn Sie Identitätsquellen angeben, müssen Clients diese in die Anforderung aufnehmen. Wenn die Anfrage des Clients die Identitätsquellen nicht enthält, ruft API Gateway Ihren Lambda-Autorisierer nicht auf und der Client erhält eine Fehlermeldung. 401

In der folgenden Tabelle werden die unterstützten Identitätsquellen für einen Lambda-Authorizer beschrieben.

Typ	Beispiel	Hinweise
Header-Wert	$request.header.`name`	Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden.
Abfragezeichenfolgenwert	$request.querystring.`name`	Abfragezeichenfolgennamen unterscheiden zwischen Groß- und Kleinschreibung.
Kontextvariable	$Kontext.`variableName`	Der Wert einer unterstützten Kontextvariablen.
Stufenvariable	$stageVariables.`variableName`	Der Wert einer Stufenvariablen.

Zwischenspeichern der Antworten des Genehmigers

Sie können das Caching für einen Lambda-Autorisierer aktivieren, indem Sie einen angeben. authorizerResultTtlInSeconds Wenn das Caching für einen Autorisierer aktiviert ist, verwendet API Gateway die Identitätsquellen des Autorisierers als Cache-Schlüssel. Wenn ein Client dieselben Parameter in Identitätsquellen innerhalb der Konfiguration angibtTTL, verwendet API Gateway das zwischengespeicherte Authorizer-Ergebnis, anstatt Ihre Lambda-Funktion aufzurufen.

Um das Caching zu aktivieren, muss der Genehmiger über mindestens eine Identitätsquelle verfügen.

Wenn Sie einfache Antworten für einen Autorisierer aktivieren, lässt die Antwort des Autorisierers alle API Anfragen, die den zwischengespeicherten Identitätsquellenwerten entsprechen, vollständig zu oder lehnt sie ab. Für detailliertere Berechtigungen deaktivieren Sie einfache Antworten und geben Sie eine Richtlinie zurück. IAM

Standardmäßig verwendet API Gateway die zwischengespeicherte Autorisierungsantwort für alle Routen eines Benutzers, API die den Autorisierer verwenden. Um Antworten pro Route zwischenzuspeichern, fügen Sie den Identitätsquellen Ihres Genehmigers $context.routeKey hinzu.

Erstellen eines Lambda-Genehmigers

Wenn Sie einen Lambda-Autorisierer erstellen, geben Sie die Lambda-Funktion an, die API Gateway verwenden soll. Sie müssen API Gateway die Berechtigung zum Aufrufen der Lambda-Funktion erteilen, indem Sie entweder die Ressourcenrichtlinie der Funktion oder eine IAM Rolle verwenden. In diesem Beispiel aktualisieren wir die Ressourcenrichtlinie für die Funktion, sodass sie API Gateway die Berechtigung erteilt, unsere Lambda-Funktion aufzurufen.


aws apigatewayv2 create-authorizer \
    --api-id abcdef123 \
    --authorizer-type REQUEST \
    --identity-source '$request.header.Authorization' \
    --name lambda-authorizer \ 
    --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
    --authorizer-payload-format-version '2.0' \
    --enable-simple-responses

Der folgende Befehl erteilt API Gateway die Erlaubnis, Ihre Lambda-Funktion aufzurufen. Wenn API Gateway nicht berechtigt ist, Ihre Funktion aufzurufen, erhalten Clients eine. 500 Internal Server Error


aws lambda add-permission \
    --function-name my-authorizer-function \
    --statement-id apigateway-invoke-permissions-abc123 \ 
    --action lambda:InvokeFunction \
    --principal apigateway.amazonaws.com \
    --source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id"

Nachdem Sie einen Autorisierer erstellt und API Gateway die Erlaubnis erteilt haben, ihn aufzurufen, aktualisieren Sie Ihre Route, um den Autorisierer zu verwenden.


aws apigatewayv2 update-route \
    --api-id abcdef123 \
    --route-id acd123 \
    --authorization-type CUSTOM \
    --authorizer-id def123

Fehlerbehebung für Lambda-Genehmiger

Wenn API Gateway Ihren Lambda-Authorizer nicht aufrufen kann oder Ihr Lambda-Authorizer eine Antwort in einem ungültigen Format zurückgibt, erhalten Clients eine. 500 Internal Server Error

Um Fehler zu beheben, aktivieren Sie die Zugriffsprotokollierung für Ihre Phase. API Fügen Sie die $context.authorizer.error-Protokollierungsvariable in Ihr Protokollformat ein.

Wenn aus den Protokollen hervorgeht, dass API Gateway nicht berechtigt ist, Ihre Funktion aufzurufen, aktualisieren Sie die Ressourcenrichtlinie Ihrer Funktion oder geben Sie eine IAM Rolle an, um API Gateway die Berechtigung zum Aufrufen Ihres Autorisierers zu erteilen.

Wenn die Protokolle darauf hinweisen, dass Ihre Lambda-Funktion eine ungültige Antwort zurückgibt, überprüfen Sie, ob Ihre Lambda-Funktion eine Antwort im erforderlichen Format zurückgibt.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Zugriffskontrolle

JWTAutorisierer