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

Dopo aver creato un pool di utenti di Amazon Cognito in API Gateway, devi creare un'autorizzazione COGNITO_USER_POOLS che usa il pool di utenti. La procedura seguente illustra come eseguire questa operazione tramite la console API Gateway.

Nota

Puoi utilizzare l'operazione CreateAuthorizer per creare un'autorizzazione COGNITO_USER_POOLS che utilizzi più pool di utenti. Puoi utilizzare fino a 1.000 pool di utenti per un unica autorizzazione COGNITO_USER_POOLS. Questo limite non può essere aumentato.

Importante

Dopo aver eseguito una delle procedure di seguito, è necessario distribuire o ridistribuire l'API per la propagazione delle modifiche. Per ulteriori informazioni sulla distribuzione della tua API, vedi Distribuzione di un'API REST in Amazon API Gateway.

Per creare un'autorizzazione `COGNITO_USER_POOLS` tramite la console API Gateway

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à.

La procedura precedente crea un'autorizzazione COGNITO_USER_POOLS che utilizza il nuovo pool di utenti di Amazon Cognito appena creato. A seconda del modo in cui abiliti l'autorizzazione per un metodo API, puoi usare un token di identità o un token di accesso assegnato dal pool di utenti integrato.

Per configurare un'autorizzazione `COGNITO_USER_POOLS` per i metodi

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.

Se con l'autorizzazione COGNITO_USER_POOLS l'opzione OAuth Scopes (Ambiti OAuth) non è specificata, API Gateway considera il token specificato un token di identità e verifica l'identità richiesta rispetto a quella del pool di utenti. Altrimenti, API Gateway considera il token specificato un token di accesso e verifica gli ambiti di accesso richiesti nel token rispetto agli ambiti di autorizzazione dichiarati nel metodo.

Invece di usare la console API Gateway, puoi anche abilitare un pool di utenti di Amazon Cognito in un metodo specificando un file di definizione OpenAPI e importando la definizione API in API Gateway.

Per importare un'autorizzazione COGNITO_USER_POOLS con un file di definizione OpenAPI

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 Utilizzo di estensioni API Gateway in OpenAPI.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Creazione di un pool di utenti di Amazon Cognito per un'API REST

Chiamata di un'API REST integrata con un pool di utenti