Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore In alternativa all'utilizzo di [ruoli e policy IAM](permissions.md) o [autorizzazioni Lambda](apigateway-use-lambda-authorizer.md) (note in precedenza come autorizzazioni ad hoc), puoi utilizzare un [pool di utenti di Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) per controllare chi può accedere all'API in Amazon API Gateway. Per usare un pool di utenti di Amazon Cognito con l'API, devi prima creare l'autorizzazione di tipo `COGNITO_USER_POOLS` e quindi configurare un metodo API per usare tale autorizzazione. Una volta distribuita l'API, il client deve innanzitutto registrare l'utente nel pool di utenti, ottenere un [token di identità o di accesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) per l'utente e quindi chiamare il metodo API con uno dei token, che sono in genere impostati sull'intestazione `Authorization` della richiesta. La chiamata API riesce solo se viene fornito il token necessario e se questo è valido. In caso contrario, il client non è autorizzato ad effettuare la chiamata perché non ha credenziali che è stato possibile autorizzare. Il token di identità viene usato per autorizzare chiamate API in base alle richieste di identità dell'utente connesso. Il token di accesso viene usato per autorizzare chiamate API in base agli ambiti personalizzati di risorse con accesso protetto specificate. Per ulteriori informazioni, consulta [Utilizzo di token con pool di utenti](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) e la pagina relativa a [server di risorse e ambiti personalizzati](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Per creare e configurare un pool di utenti di Amazon Cognito per l'API, esegui le attività seguenti: + Usa la console Amazon Cognito, CLI/SDK o API per creare un pool di utenti o usane uno di proprietà di un altro account. AWS + Usa la console, l'interfaccia a riga di comando/SDK o l'API di API Gateway, per creare autorizzazioni API Gateway con il pool di utenti scelto. + Usa la console, l'interfaccia a riga di comando/SDK o l'API di API Gateway, per abilitare le autorizzazioni per i metodi API selezionati. Per chiamare qualsiasi metodo API con un pool di utenti abilitato, i client API eseguono le attività seguenti: + Usa Amazon Cognito CLI/SDK o l'API per far accedere un utente al pool di utenti scelto e ottenere un token di identità o un token di accesso. Per ulteriori informazioni sull'utilizzo di SDKs, consulta [Esempi di codice per l'utilizzo di Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). AWS SDKs + Utilizzano un framework specifico del client per chiamare l'API di API Gateway distribuita e specificare il token appropriato nell'intestazione `Authorization`. In quanto sviluppatore dell'API, devi fornire agli sviluppatori client l'ID pool di utenti, un ID client e possibilmente i segreti client definiti come parte del pool di utenti. **Nota** Per permettere a un utente di accedere usando credenziali Amazon Cognito e anche di ottenere credenziali temporanee da usare con le autorizzazioni di un ruolo IAM, usa [identità federate di Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). Per ogni metodo HTTP dell'endpoint della risorsa API, imposta il tipo di autorizzazione, la categoria `Method Execution`, su `AWS_IAM`. In questa sezione descriveremo come creare un pool di utenti, come integrare un'API di API Gateway con il pool di utenti e come richiamare un'API integrata con il pool di utenti. **Topics** + [Creazione di un pool di utenti di Amazon Cognito per un'API REST](apigateway-create-cognito-user-pool.md) + [Integrazione di un'API REST con un pool di utenti di Amazon Cognito](apigateway-enable-cognito-user-pool.md) + [Chiamata di un'API REST integrata con un pool di utenti di Amazon Cognito](apigateway-invoke-api-integrated-with-cognito-user-pool.md) + [Configurazione dell'autorizzazione Amazon Cognito tra account per un'API REST tramite la console API Gateway](apigateway-cross-account-cognito-authorizer.md) + [Crea un autorizzatore Amazon Cognito per un'API REST utilizzando CloudFormation](apigateway-cognito-authorizer-cfn.md) # Creazione di un pool di utenti di Amazon Cognito per un'API REST Prima di integrare l'API con un pool di utenti, devi creare il pool di utenti in Amazon Cognito. La configurazione del pool di utenti deve rispettare tutte le [quote di risorse per Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Tutte le variabili Amazon Cognito definite dall'utente, come gruppi, utenti e ruoli, devono utilizzare solo caratteri alfanumerici. Per istruzioni su come creare un pool di utenti, consulta [Tutorial: Creazione di un bacino d'utenza](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) nella *Guida per gli sviluppatori di Amazon Cognito*. Prendi nota dell'ID pool di utenti, dell'ID client e di qualsiasi segreto client. Il client dovrà fornirli ad Amazon Cognito perché l'utente possa registrarsi con il pool di utenti, accedere al pool di utenti e ottenere un token di identità o di accesso da includere nelle richieste per chiamare metodi API configurati con il pool di utenti. Inoltre, devi specificare il nome del pool di utenti quando configuri il pool di utenti come autorizzazioni in API Gateway, come descritto nella prossima sezione. Se stai usando token di accesso per autorizzare le chiamate di metodi API, assicurati di configurare l'integrazione dell'app con il pool di utenti per configurare gli ambiti personalizzati che desideri in un determinato server di risorse. Per ulteriori informazioni sull'utilizzo di token con pool di utenti di Amazon Cognito, consulta [Utilizzo di token con pool di utenti](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Per ulteriori informazioni sui server di risorse, consulta [Definizione dei server di risorse per il pool di utenti](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Annota gli identificatori dei server di risorse configurati e i nomi degli ambiti personalizzati. Ti servono per creare i nomi completi dell'ambito di accesso per **OAuth Scopes**, che viene utilizzato dall'autorizzatore. `COGNITO_USER_POOLS` ![\[Server di risorse e ambiti del pool di utenti di Amazon Cognito\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png) # 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) 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 [Implementazione di REST API in Gateway API](how-to-deploy-api.md). **Per creare un'autorizzazione `COGNITO_USER_POOLS` tramite la console API Gateway** 1. Crea una nuova API oppure selezionane una esistente in API Gateway. 1. Nel riquadro di navigazione principale, scegli **Autorizzazioni**. 1. Scegli **Crea autorizzazioni**. 1. Per configurare la nuova autorizzazione per usare un pool di utenti, esegui queste operazioni: 1. In **Nome del provider di autorizzazioni**, immetti un nome. 1. In **Tipo di autorizzazione**, seleziona **Cognito**. 1. Per il **pool di utenti Cognito**, scegli Regione AWS dove hai creato Amazon Cognito e seleziona un pool di utenti disponibile. Per definire il pool di utenti è possibile usare una variabile di fase. Utilizza il seguente formato per il pool di utenti: `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. 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. 1. (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`. 1. Scegli **Crea autorizzazioni**. 1. Dopo aver creato il sistema di autorizzazione `COGNITO_USER_POOLS`, è possibile testarne l’invocazione specificando un token di identità allocato dal pool di utenti. Non è possibile utilizzare un token di accesso per testare l’invocazione del sistema di autorizzazione. Puoi ottenere questo token di identità chiamando l'[SDK Amazon Cognito Identity](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) per eseguire l'accesso dell'utente. È anche possibile usare l'operazione [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). 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** 1. Scegliere **Resources** (Risorse). Seleziona un nuovo metodo o scegline uno esistente. Se necessario, crea una risorsa. 1. Nella scheda **Richiesta metodo**, in **Impostazioni richiesta metodo**, scegli **Modifica**. 1. In **Autorizzazioni**, nel menu a discesa, seleziona **Autorizzazioni del gruppo di utenti di Cognito**. 1. Per usare un token di identità, esegui queste operazioni: 1. Non specificare alcun valore in **Ambiti di autorizzazione**. 1. 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](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) `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']" } } ``` 1. 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](apigateway-create-cognito-user-pool.md), 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`. 1. Scegli **Save** (Salva). 1. Ripeti queste fasi per gli altri metodi scelti. Con l'`COGNITO_USER_POOLS`authorizer, se l'opzione **OAuthScopes** non è specificata, API Gateway tratta il token fornito come un token di identità e verifica l'identità dichiarata 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\$1USER\$1POOLS con un file di definizione OpenAPI** 1. Crea (o esporta) un file di definizione OpenAPI per l'API. 1. 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: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "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:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "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:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. 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" } }, ... } ``` 1. 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" } }, ... } ``` 1. Se necessario, è possibile definire altre impostazioni di configurazione dell'API utilizzando le definizioni o estensioni OpenAPI appropriate. Per ulteriori informazioni, consulta [Estensioni OpenAPI per Gateway API](api-gateway-swagger-extensions.md). # Chiamata di un'API REST integrata con un pool di utenti di Amazon Cognito Per chiamare un metodo con un'autorizzazione del pool di utenti configurata, il client deve eseguire queste operazioni: + Permettere all'utente di iscriversi al pool di utenti. + Permettere all'utente di accedere al pool di utenti. + Ottenere un [token di identità o di accesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) per l'utente che ha effettuato l'accesso dal pool di utenti. + Includere il token nell'intestazione `Authorization` (o in un'altra intestazione specificata durante la creazione dell'autorizzazione). È possibile utilizzare [AWS Amplify]() per eseguire queste attività. Per maggiori informazioni, consulta [Integrazione di Amazon Cognito con le app Web e per dispositivi mobili](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html). + Per Android, consulta [Nozioni di base su Amplify per Android](https://docs.amplify.aws/android/build-a-backend/auth/). + Per usare iOS, consulta [Nozioni di base su Amplify per iOS](https://docs.amplify.aws/swift/build-a-backend/auth/). + Per utilizzarlo JavaScript, consulta [Getting Started with Amplify for Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/). # Configurazione dell'autorizzazione Amazon Cognito tra account per un'API REST tramite la console API Gateway Ora puoi anche utilizzare un pool di utenti Amazon Cognito di un altro AWS account come autorizzatore API. Il pool di utenti di Amazon Cognito può utilizzare strategie di autenticazione con token portatori come OAuth o SAML. Ciò semplifica la gestione e la condivisione centralizzata di un autorizzatore del pool di utenti Amazon Cognito centrale su più API Gateway. APIs In questa sezione, viene illustrato come configurare un pool di utenti di Amazon Cognito tra account tramite la console Amazon API Gateway. Queste istruzioni presuppongono che tu abbia già un'API API Gateway in un AWS account e un pool di utenti Amazon Cognito in un altro account. ## Creazione di un sistema di autorizzazione di Amazon Cognito multi-account per una REST API Accedi alla console Gateway Amazon API con l'account contenente la tua API e quindi procedi come descritto di seguito: 1. Crea una nuova API oppure selezionane una esistente in API Gateway. 1. Nel riquadro di navigazione principale, scegli **Autorizzazioni**. 1. Scegli **Crea autorizzazioni**. 1. Per configurare la nuova autorizzazione per usare un pool di utenti, esegui queste operazioni: 1. In **Nome del provider di autorizzazioni**, immetti un nome. 1. In **Tipo di autorizzazione**, seleziona **Cognito**. 1. Per **Gruppo di utenti di Cognito**, copia e incolla l'ARN completo del pool di utenti nel secondo account. **Nota** Nella console Amazon Cognito, puoi trovare l'ARN del pool di utenti nel campo **Pool ARN (ARN pool)** del riquadro **General Settings (Impostazioni generali)**. 1. 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. 1. (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`. 1. Scegli **Crea autorizzazioni**. # Crea un autorizzatore Amazon Cognito per un'API REST utilizzando CloudFormation Puoi utilizzarlo CloudFormation per creare un pool di utenti Amazon Cognito e un autorizzatore Amazon Cognito. Il CloudFormation modello di esempio esegue le seguenti operazioni: + Crea un pool di utenti di Amazon Cognito. Il client deve prima far accedere l'utente al pool di utenti e ottenere [un'identità o un token di accesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Se stai usando token di accesso per autorizzare le chiamate di metodi API, assicurati di configurare l'integrazione dell'app con il pool di utenti per configurare gli ambiti personalizzati che desideri in un determinato server di risorse. + Crea un'API Gateway API con un metodo `GET`. + Crea un'autorizzazione Amazon Cognito che utilizza l'intestazione `Authorization` come origine del token. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: UserPool: Type: AWS::Cognito::UserPool Properties: AccountRecoverySetting: RecoveryMechanisms: - Name: verified_phone_number Priority: 1 - Name: verified_email Priority: 2 AdminCreateUserConfig: AllowAdminCreateUserOnly: true EmailVerificationMessage: The verification code to your new account is {####} EmailVerificationSubject: Verify your new account SmsVerificationMessage: The verification code to your new account is {####} VerificationMessageTemplate: DefaultEmailOption: CONFIRM_WITH_CODE EmailMessage: The verification code to your new account is {####} EmailSubject: Verify your new account SmsMessage: The verification code to your new account is {####} UpdateReplacePolicy: Retain DeletionPolicy: Retain CogAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: Name: CognitoAuthorizer RestApiId: Ref: Api Type: COGNITO_USER_POOLS IdentitySource: method.request.header.Authorization ProviderARNs: - Fn::GetAtt: - UserPool - Arn Api: Type: AWS::ApiGateway::RestApi Properties: Name: MyCogAuthApi ApiDeployment: Type: AWS::ApiGateway::Deployment Properties: RestApiId: Ref: Api DependsOn: - CogAuthorizer - ApiGET ApiDeploymentStageprod: Type: AWS::ApiGateway::Stage Properties: RestApiId: Ref: Api DeploymentId: Ref: ApiDeployment StageName: prod ApiGET: Type: AWS::ApiGateway::Method Properties: HttpMethod: GET ResourceId: Fn::GetAtt: - Api - RootResourceId RestApiId: Ref: Api AuthorizationType: COGNITO_USER_POOLS AuthorizerId: Ref: CogAuthorizer Integration: IntegrationHttpMethod: GET Type: HTTP_PROXY Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets Outputs: ApiEndpoint: Value: Fn::Join: - "" - - https:// - Ref: Api - .execute-api. - Ref: AWS::Region - "." - Ref: AWS::URLSuffix - / - Ref: ApiDeploymentStageprod - / ```