Zugriffssteuerung für HTTP-APIs mit AWS Lambda-Genehmigern - Amazon API Gateway
NutzlastformatversionAntwortformat des Lambda-GenehmigersBeispiel für Lambda-Genehmiger-FunktionenIdentitätsquellenZwischenspeichern der Antworten des GenehmigersErstellen eines Lambda-GenehmigersFehlerbehebung für Lambda-Genehmiger

Zugriffssteuerung für HTTP-APIs mit AWS Lambda-Genehmigern

Sie verwenden einen Lambda-Genehmiger, um den Zugriff auf Ihre HTTP-API mit einer Lambda-Funktion zu steuern. Wenn dann ein Client Ihre API aufruft, ruft API Gateway Ihre Lambda-Funktion auf. API Gateway verwendet die Antwort Ihrer Lambda-Funktion, um festzustellen, ob der Client auf Ihre API zugreifen kann.

Nutzlastformatversion

Die Nutzlastformatversion des Genehmigers gibt das Format der Daten an, die API Gateway an einen Lambda-Genehmiger sendet, und wie API Gateway die Antwort von Lambda interpretiert. Wenn Sie keine Nutzlastformatversion angeben, verwendet die AWS Management Console standardmäßig die neueste Version. Wenn Sie einen Lambda-Genehmiger mithilfe der AWS CLI, AWS CloudFormation oder eines SDK erstellen, müssen Sie eine authorizerPayloadFormatVersion angeben. Die unterstützten Werte sind 1.0 und 2.0.

Wenn Sie Kompatibilität mit REST-APIs benötigen, 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 Formatversion 1.0 auswählen, müssen Lambda-Genehmiger eine IAM-Richtlinie zurückgeben, die den Zugriff auf Ihre API-Route zulässt oder verweigert. Sie können die IAM-Standardrichtliniensyntax in der Richtlinie verwenden. Beispiele für IAM-Richtlinien finden Sie unter Kontrollieren des Zugriffs für den API-Aufruf. Mit $context.authorizer.property können Sie Kontexteigenschaften an Lambda-Integrationen oder -Zugriffsprotokolle übergeben. Das context-Objekt ist optional und claims ist ein reservierter Platzhalter, der nicht als Kontextobjekt verwendet werden kann. Weitere Informationen hierzu finden Sie unter HTTP-API-Zugriffsprotokolle anpassen.

JSON
{
  "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 Formatversion 2.0 auswählen, können Sie einen booleschen Wert oder eine IAM-Richtlinie zurückgeben, die die IAM-Standardrichtliniensyntax 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 $context.authorizer.property können Sie Kontexteigenschaften an Lambda-Integrationen oder -Zugriffsprotokolle übergeben. Weitere Informationen hierzu finden Sie unter HTTP-API-Zugriffsprotokolle anpassen.

Simple response
{
  "isAuthorized": true/false,
  "context": {
    "exampleKey": "exampleValue"
  }
}
IAM policy
{
  "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"
  }
}

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 Anforderung des Clients die Identitätsquellen nicht enthält, ruft API Gateway Ihren Lambda-Genehmiger nicht auf, und der Client erhält einen 401-Fehler.

In der folgenden Tabelle werden die unterstützten Identitätsquellen für einen Lambda-Genehmiger 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 $context.Variablenname Der Wert einer unterstützten Kontextvariablen.
Stufenvariable $stageVariables.Variablenname Der Wert einer Stufenvariablen.

Sie können auch direkt {"errorMessage" : "Unauthorized"} aus Ihrer Lambda-Funktion zurückgeben, um einen 401-Fehler an die Clients zurückzugeben. Wenn Sie einen 401-Fehler direkt aus Ihrer Lambda-Funktion an die Clients zurückgeben, geben Sie beim Erstellen Ihres Lambda-Genehmigers keine Identitätsquellen an.

Zwischenspeichern der Antworten des Genehmigers

Sie können die Zwischenspeicherung für einen Lambda-Genehmiger aktivieren, indem Sie eine Wert für authorizerResultTtlInSeconds angeben. Wenn für einen Genehmiger Zwischenspeicherung aktiviert ist, verwendet API Gateway die Identitätsquellen des Genehmigers als Cache-Schlüssel. Wenn ein Client dieselben Parameter in Identitätsquellen innerhalb der konfigurierten TTL angibt, verwendet API Gateway das zwischengespeicherte Genehmiger-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 Genehmiger aktivieren, erlaubt oder verweigert die Antwort des Genehmigers alle API-Anforderungen, die mit den zwischengespeicherten Identitätsquellwerten übereinstimmen, vollständig. Um detailliertere Berechtigungen zu erhalten, deaktivieren Sie einfache Antworten und geben Sie eine IAM-Richtlinie zurück. Je nach Genehmiger muss Ihre IAM-Richtlinie möglicherweise den Zugriff auf mehrere Ressourcen steuern.

Standardmäßig verwendet API Gateway die zwischengespeicherte Genehmiger-Antwort für alle Routen einer API, die den Genehmiger 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-Genehmiger 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. Der create-authorizer-Befehl erstellt einen Lambda-Genehmiger:

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 add-permission-Befehl aktualisiert die Ressourcenrichtlinie der Lambda-Funktion, um API Gateway die Berechtigung zum Aufrufen der Funktion zu erteilen. Wenn API Gateway nicht zum Aufrufen Ihrer Funktion berechtigt ist, erhalten Clients einen 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 Genehmiger erstellt und API Gateway die Berechtigung zum Aufrufen erteilt haben, aktualisieren Sie Ihre Route, um den Genehmiger zu verwenden. Der folgende update-route-Befehl fügt der Route den Lambda-Genehmiger hinzu. Wenn Ihr Lambda-Genehmiger eine Richtlinienspeicherung verwendet, stellen Sie sicher, dass Sie die Richtlinie aktualisieren, um den Zugriff für die zusätzliche Route zu steuern.

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

Fehlerbehebung für Lambda-Genehmiger

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

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

Wenn die Protokolle darauf hinweisen, dass API Gateway keine Berechtigung zum Aufrufen Ihrer Funktion besitzt, aktualisieren Sie die Ressourcenrichtlinie Ihrer Funktion oder stellen Sie eine IAM-Rolle bereit, um die API Gateway-Berechtigung zum Aufrufen des Genehmigers 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.