Autorizzazione API con server di risorse e ambiti OAuth 2.0

Dopo aver configurato un dominio per il pool di utenti, Amazon Cognito effettua automaticamente il provisioning di un server di autorizzazione OAuth 2.0 e di un'interfaccia utente Web ospitata con pagine di registrazione e accesso mostrate dall'app agli utenti. Per ulteriori informazioni, consulta Aggiunta di un client dell'app e configurazione dell'interfaccia utente ospitata. Puoi scegliere gli ambiti che desideri che il server di autorizzazione aggiunga ai token di accesso. Gli ambiti autorizzano l'accesso ai server di risorse e ai dati degli utenti.

Un server di risorse è un server API OAuth 2.0. Per proteggere le risorse protette dall'accesso, verifica che i token di accesso del pool di utenti contengano gli ambiti che autorizzano il metodo e il percorso richiesti nell'API che protegge. Verifica l'emittente in base alla firma del token, la validità in base alla scadenza del token e il livello di accesso in base agli ambiti delle richieste di token. I pool di utenti presentano ambiti nell'ambito dei token di accesso claim. Per ulteriori informazioni sulle dichiarazioni nei token di accesso di Amazon Cognito, consulta Utilizzo del token di accesso.

Indipendentemente dal fatto che gli utenti appartengano al tuo pool di utenti o siano di terze parti e che eseguano l’autenticazione con l'interfaccia utente ospitata o nell'API dei pool di utenti di Amazon Cognito, il tuo profilo utente può generare token di accesso con ambiti che autorizzano l'app a funzionare con gli attributi utente.

Informazioni sugli ambiti

Un ambito è un livello di accesso che un'app può richiedere a una risorsa. In un token di accesso Amazon Cognito, l'ambito è supportato dal trust che configuri con il tuo pool di utenti: un emittente affidabile di token di accesso con una firma digitale nota. I pool di utenti possono generare token di accesso con scopi che dimostrano che il cliente è autorizzato a gestire alcuni o tutti i propri profili utente o a recuperare dati da un'API di back-end. I pool di utenti di Amazon Cognito emettono token di accesso con l'ambito API riservato del pool di utenti, gli ambiti personalizzati e gli ambiti standard.

L'ambito API riservato dei pool di utenti

L'ambito aws.cognito.signin.user.admin autorizza l'API dei pool di utenti Amazon Cognito. Autorizza il portatore di un token di accesso a eseguire query e aggiornare tutte le informazioni su un utente del pool di utenti con, ad esempio, le operazioni API GetUser e UpdateUserAttributes. Quando autentichi il tuo utente con l'API dei pool di utenti di Amazon Cognito, questo è l'unico ambito che ricevi nel token di accesso. È anche l'unico ambito di cui hai bisogno per leggere e scrivere gli attributi utente che il client dell'app è autorizzato a leggere e scrivere. Puoi anche richiedere questo ambito nelle richieste a Endpoint Authorize. Questo ambito da solo non è sufficiente per richiedere attributi utente da Endpoint UserInfo. Per i token di accesso che autorizzano l'API dei pool di utenti e le richieste userInfo per gli utenti, devi richiedere entrambi gli ambiti openid e aws.cognito.signin.user.admin in una richiesta /oauth2/authorize.

Ambiti personalizzati

Gli ambiti personalizzati autorizzano le richieste alle API esterne protette dai server di risorse. Puoi richiedere ambiti personalizzati con altri tipi di ambiti. Puoi trovare maggiori informazioni sugli ambiti personalizzati in questa pagina.

Ambiti standard

Quando autentichi gli utenti con il server di autorizzazione OAuth 2.0 del tuo pool di utenti, inclusa l'interfaccia utente ospitata, devi richiedere gli ambiti. Puoi autenticare gli utenti locali del pool di utenti e gli utenti federati di terze parti nel tuo server di autorizzazione Amazon Cognito. Gli ambiti OAuth 2.0 standard autorizzano l'app a leggere le informazioni utente da Endpoint UserInfo tuo pool di utenti. Il modello OAuth, in cui si interrogano gli attributi utente dall'endpoint userInfo, può ottimizzare l'app per un volume elevato di richieste di attributi utente. L'endpoint userInfo restituisce gli attributi a un livello di autorizzazione determinato dagli ambiti del token di accesso. Puoi autorizzare il client dell'app a emettere token di accesso con i seguenti ambiti OAuth 2.0 standard.

openid

L'ambito minimo per query OpenID Connect (OIDC). Autorizza il token ID, l'attestazione di identificazione univoca sub e la possibilità di richiedere altri ambiti.

Nota

Quando richiedi l'ambito openid e nessun altro, il token ID del pool di utenti e la risposta userInfo includono attestazioni per tutti gli attributi utente che il client dell'app è in grado di leggere. Quando richiedi openid e altri ambiti standard come profile, email e phone, il contenuto del token ID e della risposta userInfo è limitato ai vincoli degli ambiti aggiuntivi.

Ad esempio, una richiesta a Endpoint Authorize con il parametro scope=openid+email restituisce un token ID con sub, email e email_verified. Il token di accesso di questa richiesta restituisce gli stessi attributi daEndpoint UserInfo. Una richiesta con parametro scope=openid restituisce tutti gli attributi leggibili dal client nel token ID e da userInfo.

profilo

Autorizza tutti gli attributi utente che il client dell'app è in grado di leggere.

e-mail

Autorizza gli attributi utente email e email_verified. Amazon Cognito restituisce email_verified se un valore è stato impostato in modo esplicito.

telefono

Autorizza gli attributi utente phone_number e phone_number_verified.

Informazioni sui server di risorse

Un'API del server di risorse potrebbe consentire l'accesso alle informazioni in un database o controllare le risorse IT. Un token di accesso di Amazon Cognito può autorizzare l'accesso alle API che supportano OAuth 2.0. Le REST API Gateway Amazon API sono caratterizzate dal supporto integrato per l'autorizzazione con i token di accesso di Amazon Cognito. L'app trasferisce il token d'accesso nella chiamata API ai server di risorse. Il server di risorse ispeziona il token d'accesso per determinare se gli accessi devono essere concessi.

Amazon Cognito potrebbe apportare future modifiche allo schema dei token di accesso del pool di utenti. Se la tua app analizza il contenuto del token di accesso prima di passarlo a un'API, devi progettare il codice per accettare gli aggiornamenti dello schema.

Gli ambiti personalizzati vengono definiti dall'utente ed estendono le funzionalità di autorizzazione di un pool di utenti per includere scopi non correlati all'interrogazione e alla modifica degli utenti e dei relativi attributi. Ad esempio, se hai un server di risorse per l'archiviazione di foto, questo potrebbe definire due ambiti, photos.read per l'accesso in lettura alle foto e photos.write per l'accesso in scrittura/eliminazione. Puoi configurare un'API per accettare i token di accesso per l'autorizzazione e la concessione di richieste HTTP GET per accedere ai token con photos.read nell'attestazione scope e richieste HTTP POST ai token con photos.write. Questi sono ambiti personalizzati.

Nota

Per elaborare una qualsiasi richiesta all'interno del token, il tuo server di risorse deve verificare la firma e la data di scadenza dei token d'accesso Per ulteriori informazioni sulla verifica dei token, consulta Verifica di un JSON Web Token. Per ulteriori informazioni sulla verifica e sull'utilizzo dei token del pool di utenti in Gateway Amazon API, consulta la sezione Integrazione dei pool di utenti Amazon Cognito con API Gateway. API Gateway è una buona soluzione per l'ispezione dei token d'accesso e la protezione delle risorse. Per ulteriori informazioni sulle autorizzazioni Lambda di API Gateway, consulta Uso di autorizzazioni Lambda di API Gateway.

Panoramica

Con Amazon Cognito, puoi creare server di risorse OAuth2.0 e associarvi ambiti personalizzati. Gli ambiti personalizzati in un token di accesso autorizzano azioni specifiche nell'API. Puoi autorizzare qualsiasi app del client nel pool di utenti a emettere ambiti personalizzati da uno qualsiasi dei server di risorse. Associa ambiti personalizzati a un client dell'app e richiedi questi ambiti nelle concessioni del codice di autorizzazione OAuth2.0, nelle concessioni implicite e nelle concessioni delle credenziali client dal Endpoint Token. Amazon Cognito aggiunge ambiti personalizzati nell'attestazione scope in un token di accesso. Un client può utilizzare il token d'accesso piuttosto che il suo server di risorse, facendo in modo che le decisioni legate all'autorizzazione siano basate sugli ambiti presenti nel token. Per ulteriori informazioni sui token d'accesso proposto, consulta Utilizzo dei token con i bacini d'utenza.

Per ottenere un token di accesso con ambiti personalizzati, l'app deve effettuare una richiesta all'Endpoint Token per riscattare un codice di autorizzazione o per richiedere la concessione delle credenziali del client. Nell'interfaccia utente ospitata, puoi anche richiedere ambiti personalizzati in un token di accesso da una concessione implicita.

Nota

Poiché sono progettati per l'autenticazione interattiva umana con il pool di utenti come IdP, le richieste InitiateAuth e AdminInitiateAuth producono solo un'attestazione scope nel token di accesso con il singolo valore aws.cognito.signin.user.admin.

Gestione del server di risorse e degli ambiti personalizzati

Durante la creazione di un server di risorse, è necessario fornire un nome per il server di risorse e un identificatore per il server di risorse. Per ogni ambito che crei nel server di risorse, è necessario fornire nome e descrizione.

• Nome del server di risorse: un nome intuitivo per il server di risorse, ad esempio Solar system object tracker o Photo API.

• Identificatore del server di risorse: un identificatore univoco per il server di risorse. L'identificatore è qualsiasi nome che desideri associare alla tua API, ad esempio solar-system-data. Puoi configurare identificatori più lunghi, ad esempio https://solar-system-data-api.example.com come riferimento più diretto ai percorsi URI delle API, ma stringhe più lunghe aumentano la dimensione dei token di accesso.

• Nome ambito: il valore che desideri nell'attestazione scope. Ad esempio, sunproximity.read.

• Descrizione: una descrizione intuitiva dell'ambito. Ad esempio, Check current proximity to sun.

Amazon Cognito può includere ambiti personalizzati nei token di accesso per qualsiasi utente, locale nel pool di utenti o federato, con un provider di identità di terze parti. Puoi scegliere gli ambiti per i token di accesso degli utenti durante i flussi di autenticazione con il server di autorizzazione OAuth 2.0 che include l'interfaccia utente ospitata. L'autenticazione dell'utente deve iniziare in corrispondenza di Endpoint Authorize con scope come uno dei parametri della richiesta. Di seguito è riportato un formato consigliato per i server di risorse. Per un identificatore, usa un nome intuitivo per le API. Per un ambito personalizzato, usa l'azione che autorizzano.

resourceServerIdentifier/scopeName

Ad esempio, hai scoperto un nuovo asteroide nella fascia di Kuiper e desideri registrarlo tramite la tua API solar-system-data. L'ambito che autorizza le operazioni di scrittura nel database degli asteroidi è asteroids.add. Quando richiedi il token di accesso che ti autorizzerà a registrare la tua scoperta, formatta il parametro di richiesta HTTPS scope come scope=solar-system-data/asteroids.add.

L'eliminazione di un ambito dal server di risorse non elimina la relativa associazione con tutti i client. Invece, l'ambito è contrassegnato come inattivo. Amazon Cognito non aggiunge ambiti inattivi ai token di accesso, ma per il resto procede normalmente se l'app ne richiede uno. Se aggiungi nuovamente l'ambito al tuo server di risorse in un secondo momento, Amazon Cognito lo scrive nuovamente nel token di accesso. Se richiedi un ambito che non hai associato all'app del client, a prescindere che venga eliminato dal server di risorse del pool di utenti, l'autenticazione non va a buon fine.

È possibile utilizzare la AWS Management Console, l' API o la CLI per definire i server di risorse e gli ambiti per il tuo bacino d'utenza.

Definizione di un server di risorse per il tuo bacino d'utenza (AWS Management Console)

È possibile utilizzare la AWS Management Console per definire un server di risorse per il tuo bacino d'utenza.

Definizione di un server di risorse

1. Accedi alla console Amazon Cognito.

2. Nel riquadro di navigazione, seleziona User Pools (bacini d'utenza) e seleziona i bacini d'utenza che intendi modificare.

3. Seleziona la scheda App integration (integrazione app) e individua l'opzione Resource servers (server di risorse).

4. Seleziona Create a resource server (Crea un server di risorse).

5. Inserisci un nome del server di risorse. Ad esempio, Photo Server.

6. Inserisci un Resource server identifier (identificatore del server di risorse). Ad esempio, com.example.photos.

7. Inserisci gli Custom scopes (ambiti personalizzati) per le risorse, come read e write.

8. Per ogni Scope name (nome ambito), inserisci una Description (descrizione), come view your photos e update your photos.

9. Seleziona Crea.

I tuoi ambiti personalizzati possono essere esaminati nella scheda Integrazione app alla voce Resource servers (Server di risorse), nella colonna Custom scopes (ambiti personalizzati). Gli ambiti personalizzati possono essere abilitati per i client app dalla scheda Integrazione app (App integration) alla voce App clients (client dell'App). Seleziona un client dell'App, individua l'opzione Hosted UI settings (impostazioni dell'interfaccia utente ospitata) e seleziona Edit (modifica). Aggiungi degli Custom scopes (ambiti personalizzati) e seleziona Save changes (salva modifiche).

Definizione di un server di risorse per il tuo bacino d'utenza (AWS CLI e API AWS)

Usa i seguenti comandi per specificare le impostazioni dei server di risorse per il tuo bacino d'utenza.

Creazione di un server di risorse

• AWS CLI: aws cognito-idp create-resource-server

• API AWS: CreateResourceServer

Ottenimento di informazioni sulle impostazioni dei tuoi server di risorse

• AWS CLI: aws cognito-idp describe-resource-server

• API AWS: DescribeResourceServer

Creazione di liste di informazioni su tutti i server di risorse per il tuo bacino d'utenza

• AWS CLI: aws cognito-idp list-resource-servers

• API AWS: ListResourceServers

Eliminazione di un server di risorse

• AWS CLI: aws cognito-idp delete-resource-server

• API AWS: DeleteResourceServer

Aggiornamento delle impostazioni per un server di risorse

• AWS CLI: aws cognito-idp update-resource-server

• API AWS: UpdateResourceServer