Integrazione di un'API REST con un pool di utenti di Amazon Cognito

Crea una nuova API oppure selezionane una esistente in API Gateway.

Nel riquadro di navigazione principale, scegli Autorizzazioni.

Scegli Create Authorizer (Crea autorizzazioni).

Per configurare la nuova autorizzazione per usare un pool di utenti, esegui queste operazioni:

1. In Nome del provider di autorizzazioni, immetti un nome.

2. In Tipo di autorizzazione, seleziona Cognito.

3. Per il pool di utenti Cognito, scegli Regione AWS dove hai creato Amazon Cognito e seleziona un pool di utenti disponibile.

   Puoi utilizzare una variabile di fase per definire il tuo pool di utenti. Usa il seguente formato per il tuo pool di utenti:arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}.

4. In Origine token, immetti Authorization come nome di intestazione da passare al token di identità o di accesso restituito da Amazon Cognito quando un utente accede correttamente.

5. (Facoltativo) Immetti un'espressione regolare nel campo Convalida del token per convalidare il campo aud (Audience, Destinatari) del token di identità prima che la richiesta venga autorizzata con Amazon Cognito. Si noti che quando si utilizza un token di accesso questa convalida rifiuta la richiesta poiché il token di accesso non contiene il campo aud.

6. Scegli Create Authorizer (Crea autorizzazioni).

Dopo aver creato l'autorizzazione COGNITO_USER_POOLS, puoi facoltativamente testare la chiamata specificando un token di identità assegnato dal pool di utenti. Puoi ottenere questo token di identità chiamando l'SDK Amazon Cognito Identity per eseguire l'accesso dell'utente. È anche possibile usare l'operazione InitiateAuth. Se in Ambiti di autorizzazione non configuri alcun valore, Gateway API considera il token fornito come un token di identità.

Scegliere Resources (Risorse). Seleziona un nuovo metodo o scegline uno esistente. Se necessario, crea una risorsa.

Nella scheda Richiesta metodo, in Impostazioni richiesta metodo, scegli Modifica.

In Autorizzazioni, nel menu a discesa, seleziona Autorizzazioni del gruppo di utenti di Cognito.

Per usare un token di identità, esegui queste operazioni:

1. Non specificare alcun valore in Ambiti di autorizzazione.

2. Se necessario, in Richiesta di integrazione, aggiungi le espressioni $context.authorizer.claims['property-name'] o $context.authorizer.claims.property-name in un modello di mappatura del corpo per passare la proprietà delle richieste di identità specificata dal pool di utenti al back-end. Per i nomi di proprietà semplici, come sub o custom-sub, le due notazioni sono identiche. Per i nomi di proprietà complessi, come custom:role, non puoi usare la notazione punto. Ad esempio, le espressioni di mappatura seguenti passano i campi standard sub e email della richiesta al back-end:

   {
   	"context" : {
   		"sub" : "$context.authorizer.claims.sub",
   		"email" : "$context.authorizer.claims.email"
   	}
   }

   Se hai dichiarato un campo di richiesta personalizzato quando hai configurato un pool di utenti, puoi seguire lo stesso modello per accedere ai campi personalizzati. L'esempio seguente ottiene un campo role personalizzato di una richiesta:

   {
   	"context" : {
   		"role" : "$context.authorizer.claims.role"
       }
   }

   Se il campo personalizzato della richiesta viene dichiarato come custom:role, usa l'esempio seguente per ottenere le proprietà della richiesta:

   {
   	"context" : {
   		"role" : "$context.authorizer.claims['custom:role']"
       }
   }

Per usare un token di accesso, esegui queste operazioni:

1. In Ambiti di autorizzazione, immetti uno o più nomi completi di un ambito configurato quando è stato creato il pool di utenti di Amazon Cognito. Ad esempio, seguendo l'esempio fornito in Creazione di un pool di utenti di Amazon Cognito per un'API REST, uno degli ambiti è https://my-petstore-api.example.com/cats.read.

   In fase di runtime, la chiamata del metodo riesce se qualsiasi ambito specificato nel metodo in questa fase corrisponde a un ambito richiesto nel token in ingresso. Altrimenti, la chiamata non riesce e restituisce una risposta 401 Unauthorized.

2. Selezionare Salva.

Ripeti queste fasi per gli altri metodi scelti.

Crea (o esporta) un file di definizione OpenAPI per l'API.

Specificare la definizione JSON dell'autorizzazione COGNITO_USER_POOLS (MyUserPool) come parte della sezione securitySchemes OpenAPI 3.0 o della sezione securityDefinitions in OpenAPI 2.0, nel seguente modo as follows:

Per usare il token di identità per l'autorizzazione del metodo, aggiungi { "MyUserPool": [] } alla definizione security del metodo, come mostrato nel metodo GET seguente nella risorsa root.

  "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": []
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

Per usare il token di accesso per l'autorizzazione del metodo, modifica la definizione di sicurezza precedente in { "MyUserPool": [resource-server/scope, ...] }:

  "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"]
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

Se necessario, è possibile definire altre impostazioni di configurazione dell'API utilizzando le definizioni o estensioni OpenAPI appropriate. Per ulteriori informazioni, consulta APIEstensioni aperte per API Gateway.