Questa pagina spiega come utilizzare i limiti di accesso alle credenziali per downscope o limitare le autorizzazioni Identity and Access Management (IAM) che una credenziale di breve durata può utilizzare.
Puoi utilizzare i limiti di accesso alle credenziali per generare token di accesso OAuth 2.0 che rappresentano un account di servizio, ma hanno meno autorizzazioni rispetto al service account. Ad esempio, se uno dei tuoi clienti deve accedere ai dati di Cloud Storage che controlli, puoi procedere nel seguente modo:
- Crea un account di servizio che possa accedere a ogni bucket Cloud Storage di tua proprietà.
- Genera un token di accesso OAuth 2.0 per il account di servizio.
- Applica un limite di accesso alle credenziali che consenta l'accesso solo al bucket che contiene i dati del cliente.
Come funzionano i confini per l'accesso con credenziali
Per ridurre l'ambito delle autorizzazioni, definisci un confine per l'accesso con credenziali che specifica a quali risorse può accedere la credenziale di breve durata, nonché un limite superiore per le autorizzazioni disponibili su ciascuna risorsa. Puoi quindi creare una credenziale di breve durata e scambiarla con una nuova credenziale che rispetti il limite di accesso alle credenziali.
Se devi concedere ai principal un insieme distinto di autorizzazioni per ogni sessione, l'utilizzo dei limiti di accesso alle credenziali può essere più efficiente rispetto alla creazione di molti account di servizio diversi e alla concessione a ciascun account di servizio di un insieme diverso di ruoli.
Componenti di un limite di accesso alle credenziali
Un limite di accesso alle credenziali è un oggetto che contiene un elenco di regole relative ai limiti di accesso. Ogni regola contiene le seguenti informazioni:
- La risorsa a cui si applica la regola.
- Il limite superiore delle autorizzazioni disponibili per la risorsa.
- (Facoltativo) Una condizione che limita ulteriormente le autorizzazioni. Una condizione include
quanto segue:
- Un'espressione di condizione che restituisce
true
ofalse
. Se il risultato ètrue
, l'accesso è consentito; in caso contrario, l'accesso è negato. - (Facoltativo) Un titolo che identifica la condizione.
- (Facoltativo) Una descrizione con maggiori informazioni sulla condizione.
- Un'espressione di condizione che restituisce
Se applichi un limite di accesso alle credenziali a una credenziale temporanea, la credenziale può accedere solo alle risorse nel limite di accesso alle credenziali. Nessuna autorizzazione è disponibile su altre risorse.
Un limite di accesso alle credenziali può contenere fino a 10 regole relative ai limiti di accesso. Puoi applicare un solo limite di accesso alle credenziali a ogni credenziale temporanea.
Se rappresentato come oggetto JSON, un Credential Access Boundary contiene i seguenti campi:
Campi | |
---|---|
accessBoundary |
Un wrapper per il limite di accesso alle credenziali. |
accessBoundary.accessBoundaryRules[] |
Un elenco di regole relative ai limiti di accesso da applicare a una credenziale temporanea. |
accessBoundary.accessBoundaryRules[].availablePermissions[] |
Un elenco che definisce il limite superiore delle autorizzazioni disponibili per la risorsa.
Ogni valore è l'identificatore di un ruolo predefinito o di un ruolo personalizzato IAM, con il prefisso |
accessBoundary.accessBoundaryRules[].availableResource |
Il nome completo della risorsa del bucket Cloud Storage a cui si applica la regola. Utilizza il formato
|
accessBoundary.accessBoundaryRules[].availabilityCondition |
Facoltativo. Una condizione che limita la disponibilità delle autorizzazioni a oggetti Cloud Storage specifici. Utilizza questo campo se vuoi rendere disponibili le autorizzazioni per oggetti specifici anziché per tutti gli oggetti in un bucket Cloud Storage. |
accessBoundary.accessBoundaryRules[].availabilityCondition.expression |
Un'espressione di condizione che specifica gli oggetti Cloud Storage in cui sono disponibili le autorizzazioni.
Per scoprire come fare riferimento a oggetti specifici in un'espressione di condizione, consulta gli attributi
|
accessBoundary.accessBoundaryRules[].availabilityCondition.title |
Facoltativo. Una stringa breve che identifica lo scopo della condizione. |
accessBoundary.accessBoundaryRules[].availabilityCondition.description |
Facoltativo. Dettagli sullo scopo della condizione. |
Per esempi in formato JSON, consulta la sezione Esempi di limiti di accesso alle credenziali in questa pagina.
Esempi di limiti di accesso alle credenziali
Le seguenti sezioni mostrano esempi di limiti di accesso alle credenziali per casi d'uso comuni. Utilizzi il limite di accesso alle credenziali quando scambi un token di accesso OAuth 2.0 con un token con ambito ridotto.
Limitare le autorizzazioni per un bucket
L'esempio seguente mostra un semplice limite di accesso alle credenziali. Si applica al bucket Cloud Storage example-bucket
e imposta il limite superiore per le autorizzazioni incluse nel ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer
):
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket"
}
]
}
}
Limitare le autorizzazioni per più bucket
L'esempio seguente mostra un Credential Access Boundary che include regole per più bucket:
- Il bucket Cloud Storage
example-bucket-1
: per questo bucket sono disponibili solo le autorizzazioni nel ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer
). - Il bucket Cloud Storage
example-bucket-2
: per questo bucket sono disponibili solo le autorizzazioni nel ruolo Storage Object Creator (roles/storage.objectCreator
).
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-1"
},
{
"availablePermissions": [
"inRole:roles/storage.objectCreator"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-2"
}
]
}
}
Limitare le autorizzazioni per oggetti specifici
Puoi anche utilizzare le condizioni IAM per specificare a quali oggetti Cloud Storage un'entità può accedere. Ad esempio, puoi
aggiungere una condizione che rende disponibili le autorizzazioni per gli oggetti il cui nome inizia
con customer-a
:
{ "accessBoundary": { "accessBoundaryRules": [ { "availablePermissions": [ "inRole:roles/storage.objectViewer" ], "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket", "availabilityCondition": { "expression" : "resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')" } } ] } }
Limitare le autorizzazioni durante l'elenco degli oggetti
Quando elenco gli oggetti in un bucket Cloud Storage, chiami un metodo su una risorsa bucket, non su una risorsa oggetto. Di conseguenza,
se una condizione viene valutata per una richiesta di elenco e la condizione fa riferimento al
nome della risorsa, il nome della risorsa identifica il bucket,
non un oggetto all'interno del bucket. Ad esempio, quando elenchi gli oggetti in
example-bucket
, il nome della risorsa è projects/_/buckets/example-bucket
.
Questa convenzione di denominazione può causare un comportamento imprevisto quando elenchi gli oggetti.
Ad esempio, supponiamo di voler creare un limite di accesso alle credenziali che consenta l'accesso
in visualizzazione agli oggetti in example-bucket
con il prefisso customer-a/invoices/
.
Potresti provare a utilizzare la seguente condizione nel limite all'accesso con credenziali:
Incompleta: condizione che verifica solo il nome della risorsa
resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/')
Questa condizione funziona per la lettura degli oggetti, ma non per l'elenco degli oggetti:
- Quando un'entità tenta di leggere un oggetto in
example-bucket
con il prefissocustomer-a/invoices/
, la condizione restituiscetrue
. - Quando un'entità tenta di elencare oggetti con quel prefisso, la condizione
restituisce
false
. Il valore diresource.name
èprojects/_/buckets/example-bucket
, che non inizia conprojects/_/buckets/example-bucket/objects/customer-a/invoices/
.
Per evitare questo problema, oltre a utilizzare resource.name.startsWith()
, la tua
condizione può controllare un attributo API denominato
storage.googleapis.com/objectListPrefix
. Questo attributo contiene il valore del
parametro prefix
utilizzato per filtrare l'elenco di oggetti. Di conseguenza,
puoi scrivere una condizione che fa riferimento al valore del parametro prefix
.
L'esempio seguente mostra come utilizzare l'attributo API in una condizione. Consente di leggere e elencare gli oggetti in example-bucket
con il prefisso
customer-a/invoices/
:
Completa: condizione che controlla il nome della risorsa e il prefisso
resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '') .startsWith('customer-a/invoices/')
Ora puoi utilizzare questa condizione in un limite di accesso alle credenziali:
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket",
"availabilityCondition": {
"expression":
"resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '').startsWith('customer-a/invoices/')"
}
}
]
}
}
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.
Crea una credenziale di breve durata con ambito ridotto
Per creare un token di accesso OAuth 2.0 con autorizzazioni con ambito ridotto, segui questi 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 account di servizio.
- Crea un token di accesso OAuth 2.0 per l'utente o il account di servizio.
- 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.
Concedi ruoli IAM
Un limite all'accesso con 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, ad esempio 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 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.
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 server-to-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 rispetta 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 dei confini per l'accesso con 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 Security Token Service ogni volta che cambia una regola del perimetro di accesso con 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 ai 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 quale versione di questo artefatto stai utilizzando, 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:
Il seguente esempio mostra come un consumatore di token può utilizzare un gestore dell'aggiornamento per ottenere e aggiornare automaticamente i token con ambito ridotto:
Scambio di token lato server
Le sezioni seguenti descrivono i metodi per scambiare token tramite l'approccio lato servizio.
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 verificare quale versione di questo pacchetto stai utilizzando, 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:
Il seguente esempio mostra come un consumatore di token può utilizzare un gestore dell'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 quale versione di questo artefatto stai utilizzando, 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:
Il seguente esempio mostra come un consumatore di token può utilizzare un gestore dell'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 verificare quale versione di questo pacchetto stai utilizzando, 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 consumer 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 verificare quale versione di questo pacchetto stai utilizzando, esegui il seguente 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 consumer 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 in formato 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 contenente 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 è presente solo se il token di accesso originale rappresenta un account di serviziot. Quando questo campo non è presente, 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 con credenziali in formato JSON è memorizzato 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 consumatore di token richiede un token con ambito ridotto, il broker di token deve rispondere con il token con ambito ridotto e il numero di secondi prima della scadenza. 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 utilizzando il flusso OAuth 2.0 da server a server o l'API Service Account Credentials.
- Crea un token di accesso OAuth 2.0 per un utente.
- Visualizza le autorizzazioni in ogni ruolo predefinito.
- Scopri di più sui ruoli personalizzati.