Oggetto x-amazon-apigateway-authorizer - Amazon API Gateway
Esempi di x-amazon-apigateway-authorizer per API RESTEsempi di x-amazon-apigateway-authorizer per API HTTP

Oggetto x-amazon-apigateway-authorizer

Definisce un sistema di autorizzazione Lambda, pool di utenti Amazon Cognito o provider di autorizzazioni JWT da applicare per l'autorizzazione delle invocazioni dei metodi in API Gateway. Questa estensione si applica alla definizione di sicurezza in OpenAPI 2 e OpenAPI 3.

Nome proprietà Tipo Descrizione
type string

Il tipo di autorizzazione. Questa proprietà è obbligatoria.

Per API REST, specificare token per un'autorizzazione con l'identità dell'intermediario incorporata in un token di autorizzazione. Specificare request per un'autorizzazione con l'identità dell'intermediario contenuta nei parametri della richiesta. Specifica cognito_user_pools per un provider di autorizzazioni che utilizza un pool di utenti Amazon Cognito per controllare l'accesso all'API.

Per API HTTP, specificare request per un'autorizzazione Lambda con l'identità dell'intermediario contenuta nei parametri della richiesta. Specificare jwt per un'autorizzazione JWT.
authorizerUri string

L'URI (Uniform Resource Identifier) della funzione Lambda del provider di autorizzazioni. La sintassi è esposta di seguito: 

"arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:auth_function_name/invocations"
authorizerCredentials string

Le credenziali richieste per invocare il provider di autorizzazioni, se presente, nel formato di un ARN di un ruolo di esecuzione IAM. Ad esempio, "arn:aws:iam::account-id:IAM_role".

authorizerPayloadFormatVersion string

Per API HTTP, specifica il formato dei dati inviati da API Gateway a un provider di autorizzazioni Lambda e come API Gateway interpreta la risposta da Lambda. Per ulteriori informazioni, consulta Tipo di formato payload.
enableSimpleResponses Boolean

Per API HTTP, specifica se un provider di autorizzazioni request restituisce un valore booleano o una policy IAM. Supportato solo per le autorizzazioni con un authorizerPayloadFormatVersion 2.0. Se abilitata, la funzione del provider di autorizzazioni Lambda restituisce un valore booleano. Per ulteriori informazioni, consulta Risposta della funzione Lambda per il formato 2.0.
identitySource string

Un elenco separato da virgole di espressioni di mappatura dei parametri di richiesta come origine di identità. Applicabile solo per l'autorizzazione del tipo request e jwt.
jwtConfiguration Object

Specifica l'emittente e i gruppi di destinatari per un autorizzatore JWT. Per ulteriori informazioni, consulta JWTConfiguration nella documentazione di riferimento dell'API Gateway versione 2. Supportato solo per le API HTTP.
identityValidationExpression string

Espressione regolare per la convalida del token come identità in ingresso. Ad esempio, "^x-[a-z]+". Supportata solo per i sistemi di autorizzazione TOKEN per REST API.
authorizerResultTtlInSeconds string

Numero di secondi durante i quali il risultato dell'autorizzazione viene memorizzato nella cache.
providerARNs Una matrice di string

Un elenco di ARN del pool di utenti Amazon Cognito per COGNITO_USER_POOLS.

Esempi di x-amazon-apigateway-authorizer per API REST

Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda di tipo "token" denominato test-authorizer.


  "securityDefinitions" : {
    "test-authorizer" : {
      "type" : "apiKey",                         // Required and the value must be "apiKey" for an API Gateway API.
      "name" : "Authorization",                  // The name of the header containing the authorization token.
      "in" : "header",                           // Required and the value must be "header" for an API Gateway API.
      "x-amazon-apigateway-authtype" : "custom", // Specifies the authorization mechanism for the client.
      "x-amazon-apigateway-authorizer" : {       // An API Gateway Lambda authorizer definition
        "type" : "token",                        // Required property and the value must "token"
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
        "authorizerCredentials" : "arn:aws:iam::account-id:role",
        "identityValidationExpression" : "^x-[a-z]+",
        "authorizerResultTtlInSeconds" : 60
      }
    }
  }

Il seguente frammento di oggetto operazione OpenAPI imposta GET /http per l'uso del provider di autorizzazioni Lambda precedente.


   "/http" : {
      "get" : {
        "responses" : { },
        "security" : [ {
          "test-authorizer" : [ ]
        } ],
        "x-amazon-apigateway-integration" : {
          "type" : "http",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "httpMethod" : "GET",
          "uri" : "http://api.example.com"
        }
      }
    }

Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda di tipo "request", con un parametro di intestazione singolo (auth) come origine di identità. Il nome di securityDefinitions è request_authorizer_single_header.

"securityDefinitions": {
    "request_authorizer_single_header" : {
      "type" : "apiKey",
      "name" : "auth",               // The name of a single header or query parameter as the identity source.
      "in" : "header",               // The location of the single identity source request parameter. The valid value is "header" or "query"
      "x-amazon-apigateway-authtype" : "custom",
      "x-amazon-apigateway-authorizer" : {
        "type" : "request",
        "identitySource" : "method.request.header.auth",   // Request parameter mapping expression of the identity source. In this example, it is the 'auth' header.
        "authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
        "authorizerResultTtlInSeconds" : 300
      }
    }
}

Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda di tipo "request", con un'intestazione (HeaderAuth1) e un parametro di stringa di query QueryString1 come origini di identità.

"securityDefinitions": {
    "request_authorizer_header_query" : {
      "type" : "apiKey",
      "name" : "Unused",             // Must be "Unused" for multiple identity sources or non header or query type of request parameters.
      "in" : "header",               // Must be "header" for multiple identity sources or non header or query type of request parameters.
      "x-amazon-apigateway-authtype" : "custom",
      "x-amazon-apigateway-authorizer" : {
        "type" : "request",
        "identitySource" : "method.request.header.HeaderAuth1, method.request.querystring.QueryString1",   // Request parameter mapping expressions of the identity sources.
        "authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
        "authorizerResultTtlInSeconds" : 300
      }
    }
}

Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda API Gateway di tipo "request", con una variabile di fase singola (stage) come origine di identità. 

"securityDefinitions": {
    "request_authorizer_single_stagevar" : {
      "type" : "apiKey",
      "name" : "Unused",             // Must be "Unused", for multiple identity sources or non header or query type of request parameters.
      "in" : "header",               // Must be "header", for multiple identity sources or non header or query type of request parameters.
      "x-amazon-apigateway-authtype" : "custom",
      "x-amazon-apigateway-authorizer" : {
        "type" : "request",
        "identitySource" : "stageVariables.stage",   // Request parameter mapping expression of the identity source. In this example, it is the stage variable.
        "authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
        "authorizerResultTtlInSeconds" : 300
      }
    }
}

Il seguente esempio di definizione di sicurezza OpenAPI specifica un pool di utenti Amazon Cognito come provider di autorizzazioni.

 "securityDefinitions": {
    "cognito-pool": {
      "type": "apiKey",
      "name": "Authorization",
      "in": "header",
      "x-amazon-apigateway-authtype": "cognito_user_pools",
      "x-amazon-apigateway-authorizer": {
        "type": "cognito_user_pools",
        "providerARNs": [
          "arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_ABC123"
        ]
      }
    }

Il seguente frammento di oggetto dell'operazione OpenAPI imposta GET /http per utilizzare il pool di utenti di Amazon Cognito precedente come provider di autorizzazioni, senza ambiti personalizzati.


   "/http" : {
      "get" : {
        "responses" : { },
        "security" : [ {
          "cognito-pool" : [ ]
        } ],
        "x-amazon-apigateway-integration" : {
          "type" : "http",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "httpMethod" : "GET",
          "uri" : "http://api.example.com"
        }
      }
    }

Esempi di x-amazon-apigateway-authorizer per API HTTP

Nell'esempio OpenAPI 3.0 riportato di seguito viene creato un provider di autorizzazioni JWT per un'API HTTP che utilizza Amazon Cognito come provider di identità, con l'intestazione Authorization come origine identità.

"securitySchemes": {
  "jwt-authorizer-oauth": {
    "type": "oauth2",
     "x-amazon-apigateway-authorizer": {
       "type": "jwt",
       "jwtConfiguration": {
          "issuer": "https://cognito-idp.region.amazonaws.com/userPoolId",
          "audience": [
            "audience1",
            "audience2"
          ]
        },
        "identitySource": "$request.header.Authorization"
    }
  }
}

L'esempio di OpenAPI 3.0 seguente produce lo stesso autorizzatore JWT dell'esempio precedente. Tuttavia, questo esempio utilizza la proprietà openIdConnectUrl di OpenAPI per rilevare automaticamente l'emittente. Il openIdConnectUrl deve essere completamente formato.

"securitySchemes": {
  "jwt-authorizer-autofind": {
    "type": "openIdConnect",
    "openIdConnectUrl": "https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/openid-configuration",
    "x-amazon-apigateway-authorizer": {
      "type": "jwt",
      "jwtConfiguration": {
        "audience": [
          "audience1",
          "audience2"
        ]
      },
      "identitySource": "$request.header.Authorization"
    }
  }
}

Nell'esempio seguente viene creato un provider di autorizzazioni Lambda per un'API HTTP. In questo esempio l'autorizzazione utilizza l'intestazione Authorization come origine di identità. L'autorizzazione utilizza il tipo di formato payload 2.0 e restituisce il valore booleano, poiché enableSimpleResponses è impostato su true.

"securitySchemes" : {
  "lambda-authorizer" : {
    "type" : "apiKey",
    "name" : "Authorization",
    "in" : "header",
    "x-amazon-apigateway-authorizer" : {
      "type" : "request",
      "identitySource" : "$request.header.Authorization",
      "authorizerUri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:function-name/invocations",
      "authorizerPayloadFormatVersion" : "2.0",
      "authorizerResultTtlInSeconds" : 300,
      "enableSimpleResponses" : true
    }
  }
}