Questa pagina spiega come utilizzare i limiti di accesso alle credenziali per creare un token di accesso OAuth 2.0 con autorizzazioni Cloud Storage con ambito ridotto.
La procedura per creare un token con autorizzazioni con ambito ridotto include i seguenti passaggi:
- Concedi i ruoli IAM appropriati a un utente o a un account di servizio.
- Definisci un limite di accesso alle credenziali che imposta un limite superiore per le autorizzazioni disponibili per l'utente o l'account di servizio.
- Crea un token di accesso OAuth 2.0 per l'utente o ilaccount di serviziot.
- Scambia il token di accesso OAuth 2.0 con un nuovo token che rispetti il limite di accesso alle credenziali.
Puoi quindi utilizzare il nuovo token di accesso OAuth 2.0 con ambito ridotto per autenticare le richieste a Cloud Storage.
Prima di iniziare
Prima di utilizzare i limiti di accesso alle credenziali, assicurati di soddisfare i seguenti requisiti:
Devi ridurre l'ambito delle autorizzazioni solo per Cloud Storage, non per altri serviziGoogle Cloud .
Se devi ridurre l'ambito delle autorizzazioni per altri servizi Google Cloud, puoi creare più service account e concedere un insieme diverso di ruoli a ogni account di servizio.
Puoi utilizzare i token di accesso OAuth 2.0 per l'autenticazione. Altri tipi di credenziali di breve durata non supportano i limiti di accesso alle credenziali.
Inoltre, devi abilitare le API richieste:
-
Enable the IAM and Security Token Service APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles.
Concedi ruoli IAM
Un limite di accesso delle credenziali imposta un limite superiore alle autorizzazioni disponibili per una risorsa. Può sottrarre autorizzazioni a un'entità, ma non può aggiungere autorizzazioni che l'entità non ha già.
Di conseguenza, devi anche concedere ruoli all'entità che forniscono le autorizzazioni necessarie, su un bucket Cloud Storage o su una risorsa di livello superiore, come il progetto.
Ad esempio, supponiamo di dover creare una credenziale di breve durata con ambito ridotto che consenta a unaccount di serviziot di creare oggetti in un bucket:
- Come minimo, devi concedere un ruolo al account di servizio che includa l'autorizzazione
storage.objects.create
, ad esempio il ruolo Creatore oggetti Storage (roles/storage.objectCreator
). Anche il perimetro di accesso con controllo delle credenziali deve includere questa autorizzazione. - Puoi anche concedere un ruolo che include più autorizzazioni, ad esempio il ruolo Amministratore oggetti Storage (
roles/storage.objectAdmin
). Il account di servizio può utilizzare solo le autorizzazioni che compaiono sia nella concessione del ruolo sia nel perimetro di accesso delle credenziali.
Per scoprire di più sui ruoli predefiniti per Cloud Storage, consulta la pagina Ruoli Cloud Storage.
Definisci il limite di accesso alle credenziali
Un limite di accesso alle credenziali è un oggetto che contiene un elenco di regole relative ai limiti di accesso. Le regole sono costituite da parametri che specificano il limite superiore delle autorizzazioni disponibili per l'utente o il account di servizio. Per definire un limite all'accesso con credenziali, crea un oggetto JSON che elenca le regole del limite all'accesso e i relativi parametri.
Di seguito è riportato un esempio di limite all'accesso con credenziali:
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:ROLE_ID"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
"availabilityCondition": {
"expression" : "CONDITION"
}
]
}
}
Sostituisci quanto segue:
ROLE_ID
: l'ID di un ruolo predefinito o personalizzato che definisce il limite superiore delle autorizzazioni disponibili per la risorsa. Ad esempio,roles/storage.objectViewer
. Per specificare più ruoli, aggiungi una nuova riga con un prefissoinRole:
seguito dall'ID ruolo. Saranno disponibili solo le autorizzazioni nei ruoli specificati.BUCKET_NAME
: il nome del bucket Cloud Storage a cui si applica la regola.CONDITION
: (Facoltativo) Un'espressione di condizione che specifica gli oggetti Cloud Storage per i quali sono disponibili le autorizzazioni. Ad esempio, la seguente condizione rende disponibili le autorizzazioni per gli oggetti il cui nome inizia concustomer-a
:resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')
Per scoprire di più su come creare e personalizzare i limiti di accesso delle credenziali, consulta Componenti di un limite di accesso delle credenziali.
Per esempi di potenziali casi d'uso per i limiti di accesso alle credenziali, vedi Esempi di limiti di accesso alle credenziali.
Crea un token di accesso OAuth 2.0
Prima di creare una credenziale di breve durata con ambito ridotto, devi creare un normale
token di accesso OAuth 2.0. Puoi quindi scambiare le credenziali normali con
credenziali con ambito ridotto. Quando crei il token di accesso, utilizza l'ambito OAuth 2.0
https://www.googleapis.com/auth/cloud-platform
.
Per creare un token di accesso per un account di servizio, puoi completare il flusso OAuth 2.0 da server a server oppure utilizzare l'API Service Account Credentials per generare un token di accesso OAuth 2.0.
Per creare un token di accesso per un utente, consulta la sezione Ottenere token di accesso OAuth 2.0. Puoi anche utilizzare OAuth 2.0 Playground per creare un token di accesso per il tuo Account Google.
Scambia il token di accesso OAuth 2.0
Dopo aver creato un token di accesso OAuth 2.0, puoi scambiarlo con un token con ambito ridotto che rispetti il limite di accesso delle credenziali. Questo processo in genere coinvolge un broker di token e un consumer di token:
Il broker di token è responsabile della definizione del confine per l'accesso con credenziali e dello scambio di un token di accesso con un token con ambito ridotto.
Il broker di token può utilizzare una libreria di autenticazione supportata per scambiare automaticamente i token di accesso oppure può chiamare il servizio token di sicurezza per scambiare i token manualmente.
Il consumer di token richiede un token di accesso con ambito ridotto al broker di token, quindi utilizza il token di accesso con ambito ridotto per eseguire un'altra azione.
Il consumer di token può utilizzare una libreria di autenticazione supportata per aggiornare automaticamente i token di accesso prima della scadenza. In alternativa, può aggiornare i token manualmente o consentire la scadenza dei token senza aggiornarli.
Esistono due modi per scambiare il token di accesso con un token con ambito ridotto:
Scambio di token lato client (consigliato): i client ottengono materiali crittografici dal server API Security Token Service. I materiali crittografici consentono ai client di generare token con ambito ridotto con regole di limiti di accesso delle credenziali variabili in modo indipendente sul lato client per una durata prestabilita (ad esempio, 1 ora). Questo approccio riduce la latenza e migliora l'efficienza, soprattutto per i client che richiedono aggiornamenti frequenti delle regole del perimetro di accesso alle credenziali. Inoltre, è più efficiente per le applicazioni che devono generare molti token con ambito ridotto unici. Questo è l'approccio consigliato perché offre prestazioni migliori, scalabilità e compatibilità con le funzionalità future.
Scambio di token lato server: i client richiedono un nuovo token con ambito ridotto dal server API del servizio token di sicurezza ogni volta che cambia una regola del limite di accesso alle credenziali. Questo approccio è semplice, ma richiede un round trip al server API Security Token Service per ogni richiesta di token con ambito ridotto. Questo approccio è consigliato solo per i clienti che richiedono una libreria client che non supporta lo scambio di token lato client, a causa dell'andata e ritorno all'API Security Token Service per ogni richiesta di token con ambito ridotto.
Scambio di token lato client
Se crei il broker di token e il consumer di token con il seguente linguaggio, puoi utilizzare la libreria di autenticazione di Google per scambiare e aggiornare i token automaticamente tramite l'approccio lato client.
Java
Per Java, puoi scambiare e aggiornare i token automaticamente con la versione 1.32.1
o successive dell'artefatto
com.google.auth:google-auth-library-cab-token-generator
.
Per controllare la versione dell'artefatto, esegui il seguente comando Maven nella directory dell'applicazione:
mvn dependency:list -DincludeArtifactIds=google-auth-library-cab-token-generator
Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra come un consumatore di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente i token con ambito ridotto:
Scambio di token lato server
Questa sezione descrive i seguenti metodi che puoi utilizzare per scambiare token tramite l'approccio lato servizio:
- Scambiare e aggiornare automaticamente il token di accesso
- Scambiare e aggiornare manualmente il token di accesso
Scambiare e aggiornare automaticamente il token di accesso utilizzando l'approccio lato server
Se crei il broker di token e il consumer di token con uno dei seguenti linguaggi, puoi utilizzare la libreria di autenticazione di Google per scambiare e aggiornare automaticamente i token utilizzando l'approccio di generazione dei token lato server:
Go
Per Go, puoi scambiare e aggiornare automaticamente i token con la versione
v0.0.0-20210819190943-2bc19b11175f o successive del
pacchetto golang.org/x/oauth2
.
Per controllare la versione del pacchetto, esegui il seguente comando nella directory dell'applicazione:
go list -m golang.org/x/oauth2
Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra come un consumatore di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente i token con ambito ridotto:
Java
Per Java, puoi scambiare e aggiornare automaticamente i token con la versione 1.1.0
o successive dell'artefatto
com.google.auth:google-auth-library-oauth2-http
.
Per controllare la versione dell'artefatto, esegui il seguente comando Maven nella directory dell'applicazione:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra come un consumatore di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente i token con ambito ridotto:
Node.js
Per Node.js, puoi scambiare e aggiornare i token automaticamente con la versione
7.9.0 o successive del pacchetto google-auth-library
.
Per controllare la versione del pacchetto, esegui il seguente comando nella directory dell'applicazione:
npm list google-auth-library
Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra come un consumatore di token può fornire un gestore di aggiornamento che ottiene e aggiorna automaticamente i token con ambito ridotto:
Python
Per Python, puoi scambiare e aggiornare i token automaticamente con la versione 2.0.0
o successive del pacchetto google-auth
.
Per controllare la versione del pacchetto, esegui questo comando nell'ambiente in cui è installato il pacchetto:
pip show google-auth
Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra come un consumatore di token può fornire un gestore di aggiornamento che ottiene e aggiorna automaticamente i token con ambito ridotto:
Scambiare e aggiornare manualmente il token di accesso
Un broker di token può utilizzare l'API Security Token Service per scambiare un token di accesso con un token di accesso con ambito ridotto. Può quindi fornire il token con ambito ridotto a un consumatore di token.
Per scambiare il token di accesso, utilizza il seguente metodo HTTP e URL:
POST https://sts.googleapis.com/v1/token
Imposta l'intestazione Content-Type
nella richiesta su
application/x-www-form-urlencoded
. Includi i seguenti campi nel corpo della richiesta:
Campi | |
---|---|
grant_type |
Utilizza il valore
|
options |
Un Credential Access Boundary formattato in JSON, codificato con codifica percentuale. |
requested_token_type |
Utilizza il valore
|
subject_token |
Il token di accesso OAuth 2.0 che vuoi scambiare. |
subject_token_type |
Utilizza il valore
|
La risposta è un oggetto JSON che contiene i seguenti campi:
Campi | |
---|---|
access_token |
Un token di accesso OAuth 2.0 con ambito ridotto che rispetta il limite all'accesso con credenziali. |
expires_in |
La quantità di tempo che trascorre prima della scadenza del token con ambito ridotto, in secondi. Questo campo viene incluso solo se il token di accesso originale rappresenta un account di servizio. Se questo campo non è incluso, il token con ambito ridotto ha lo stesso tempo di scadenza del token di accesso originale. |
issued_token_type |
Contiene il valore
|
token_type |
Contiene il valore |
Ad esempio, se un limite di accesso alle credenziali in formato JSON è archiviato nel file
./access-boundary.json
, puoi utilizzare il seguente comando
curl
per scambiare il token di accesso. Sostituisci
original-token
con il token di accesso originale:
curl -H "Content-Type:application/x-www-form-urlencoded" \ -X POST \ https://sts.googleapis.com/v1/token \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token_type=urn:ietf:params:oauth:token-type:access_token&requested_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=original-token" \ --data-urlencode "options=$(cat ./access-boundary.json)"
La risposta è simile al seguente esempio:
{
"access_token": "ya29.dr.AbCDeFg-123456...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600
}
Quando un consumer di token richiede un token con ambito ridotto, il broker di token risponde sia con il token con ambito ridotto sia con il numero di secondi fino alla scadenza. Se il token è scaduto, il server rifiuta la richiesta. Per aggiornare il token con ambito ridotto, il consumatore può richiedere un token con ambito ridotto al broker prima della scadenza del token esistente.
Passaggi successivi
- Scopri di più sul controllo dell'accesso per Cloud Storage.
- Crea una credenziale account di servizio di breve durata.
- Crea un token di accesso OAuth 2.0 per un account di servizio con uno dei seguenti metodi:
- Crea un token di accesso OAuth 2.0 per un utente.
- Visualizza le autorizzazioni in ogni ruolo predefinito.
- Scopri di più sui ruoli personalizzati.