In questa pagina viene spiegato come utilizzare i limiti di accesso alle credenziali per downscope o limitare le autorizzazioni di Identity and Access Management (IAM) che possono essere utilizzate da una credenziale di breve durata.
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 all'account di servizio. Ad esempio, se uno dei tuoi clienti ha bisogno di accedere ai dati di Cloud Storage di cui hai il controllo, puoi:
- Creare un account di servizio in grado di accedere a tutti i bucket Cloud Storage di tua proprietà.
- Genera un token di accesso OAuth 2.0 per l'account di servizio.
- Applicare un confine di accesso alle credenziali che consenta l'accesso solo al bucket contenente i dati del cliente.
Come funzionano i limiti di accesso alle credenziali
Per limitare le autorizzazioni, definisci un limite di accesso alle credenziali che specifica a quali risorse può accedere la credenziale di breve durata, nonché un limite superiore per le autorizzazioni disponibili per ciascuna risorsa. Puoi quindi creare una credenziale di breve durata e quindi scambiarla con una nuova credenziale che rispetti il confine di accesso alle credenziali.
Se devi assegnare alle entità un insieme distinto di autorizzazioni per ogni sessione, l'uso dei limiti di accesso alle credenziali può essere più efficiente della creazione di molti account di servizio diversi e della concessione di un insieme di ruoli diverso a ciascun account di servizio.
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 scambia un token di accesso OAuth 2.0 con un token con ambito ridotto.
Limita le autorizzazioni per un bucket
L'esempio seguente mostra un semplice confine di accesso alle credenziali. Si applica al bucket Cloud Storage example-bucket
e imposta il limite superiore alle 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"
}
]
}
}
Limita le autorizzazioni per più bucket
L'esempio seguente mostra un limite di accesso alle credenziali che include regole per più bucket:
- Bucket Cloud Storage
example-bucket-1
: per questo bucket sono disponibili solo le autorizzazioni nel ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer
). - Bucket Cloud Storage
example-bucket-2
: per questo bucket sono disponibili solo le autorizzazioni nel ruolo Creatore oggetti Storage (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"
}
]
}
}
Limita le autorizzazioni per oggetti specifici
Puoi anche utilizzare le condizioni IAM per specificare a quali oggetti Cloud Storage può accedere un'entità. Ad esempio, puoi aggiungere una condizione che renda le autorizzazioni disponibili 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')" } } ] } }
Limita le autorizzazioni per elencare gli oggetti
Quando elenchi gli oggetti in un bucket Cloud Storage, stai chiamando un metodo su una risorsa bucket, non una risorsa oggetto. Di conseguenza, se una condizione viene valutata per una richiesta di elenco e la condizione si riferisce al nome risorsa, il nome della risorsa identifica il bucket, non un oggetto all'interno del bucket. Ad esempio, quando elenchi oggetti in example-bucket
, il nome della risorsa è projects/_/buckets/example-bucket
.
Questa convenzione di denominazione può portare a comportamenti imprevisti quando elenchi oggetti.
Ad esempio, supponi di volere un limite di accesso alle credenziali che consenta l'accesso in visualizzazione agli oggetti in example-bucket
con il prefisso customer-a/invoices/
.
Puoi provare a utilizzare la seguente condizione nel limite di accesso alle credenziali:
Incompleta: condizione che controlla 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 elencare gli 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 gli oggetti con quel prefisso, la condizione restituisce il valore
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
che è stato 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. Ti 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 confine 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 eseguire il downgrade delle autorizzazioni solo per Cloud Storage, non per altri servizi Google Cloud.
Se hai bisogno di limitare l'ambito delle autorizzazioni per altri servizi Google Cloud, puoi creare più account di servizio e concedere un insieme di ruoli diverso a ogni account di servizio.
Per l'autenticazione puoi utilizzare i token di accesso OAuth 2.0. Altri tipi di credenziali di breve durata non supportano i limiti di accesso alle credenziali.
Inoltre, devi abilitare le API richieste:
-
Abilita le API IAM and Security Token Service.
Creare una credenziale di breve durata con ambito limitato
Per creare un token di accesso OAuth 2.0 con autorizzazioni con ambito ridotto, procedi nel seguente modo:
- Concedi i ruoli IAM appropriati a un account utente o di servizio.
- Definisci un confine di accesso alle credenziali che imposti un limite superiore per le autorizzazioni disponibili per l'account utente o di servizio.
- Crea un token di accesso OAuth 2.0 per l'account utente o di servizio.
- Scambia il token di accesso OAuth 2.0 con un nuovo token che rispetti il confine 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 confine di accesso alle credenziali imposta un limite superiore sulle autorizzazioni disponibili per una risorsa. Può sottrarre autorizzazioni da un'entità, ma non può aggiungere autorizzazioni che non dispone già.
Di conseguenza, devi anche assegnare i ruoli all'entità che fornisce le autorizzazioni di cui ha bisogno, su un bucket Cloud Storage o su una risorsa di livello superiore, come il progetto.
Supponi ad esempio di dover creare una credenziale di breve durata con ambito limitato che consenta a un account di servizio di creare oggetti in un bucket:
- Come minimo, devi concedere all'account di servizio un ruolo che includa l'autorizzazione
storage.objects.create
, ad esempio il ruolo Creatore oggetti Storage, (roles/storage.objectCreator
). Il limite di accesso alle credenziali deve includere anche questa autorizzazione. - Puoi anche concedere un ruolo che include più autorizzazioni, ad esempio il ruolo Amministratore oggetti Storage (
roles/storage.objectAdmin
). L'account di servizio può utilizzare solo le autorizzazioni visualizzate sia nella concessione del ruolo sia nel limite di accesso alle credenziali.
Per saperne di più sui ruoli predefiniti per Cloud Storage, consulta Ruoli Cloud Storage.
Componenti di un confine di accesso alle credenziali
Un limite di accesso alle credenziali è un oggetto contenente un elenco di regole di confine degli accessi. Ogni regola contiene le seguenti informazioni:
- La risorsa a cui si applica la regola.
- Il limite superiore delle autorizzazioni disponibili per quella risorsa.
- (Facoltativo) Una condizione che limita ulteriormente le autorizzazioni. Una condizione include quanto segue:
- Un'espressione di condizione che restituisce
true
ofalse
. Se restituiscetrue
, l'accesso è consentito; in caso contrario viene negato. - (Facoltativo) Un titolo che identifica la condizione.
- Facoltativo: una descrizione con ulteriori informazioni sulla condizione.
- Un'espressione di condizione che restituisce
Se applichi un limite di accesso alle credenziali a una credenziale di breve durata, la credenziale può accedere solo alle risorse presenti nel limite di accesso alle credenziali. Non sono disponibili autorizzazioni per altre risorse.
Un confine di accesso alle credenziali può contenere fino a 10 regole dei limiti di accesso. Puoi applicare un solo confine di accesso alle credenziali a ogni credenziale di breve durata.
Quando è rappresentato come un oggetto JSON, un limite di accesso alle credenziali contiene i seguenti campi:
Campi | |
---|---|
accessBoundary |
Un wrapper per il confine di accesso alle credenziali. |
accessBoundary.accessBoundaryRules[] |
Un elenco di regole relative ai confini di accesso da applicare a una credenziale di breve durata. |
accessBoundary.accessBoundaryRules[].availablePermissions[] |
Un elenco che definisce il limite superiore delle autorizzazioni disponibili per la risorsa.
Ogni valore corrisponde all'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 |
Campo 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 della condizione che specifica gli oggetti Cloud Storage per i quali sono disponibili le autorizzazioni.
Per informazioni su come fare riferimento a oggetti specifici in un'espressione della condizione, consulta l'attributo |
accessBoundary.accessBoundaryRules[].availabilityCondition.title |
Campo facoltativo. Una breve stringa che identifica lo scopo della condizione. |
accessBoundary.accessBoundaryRules[].availabilityCondition.description |
Campo facoltativo. Dettagli sullo scopo della condizione. |
Per esempi in formato JSON, consulta Esempi di limiti di accesso alle credenziali in questa pagina.
Creare un token di accesso OAuth 2.0
Prima di creare una credenziale di breve durata con ambito limitato, devi creare un normale token di accesso OAuth 2.0. Puoi quindi scambiare le credenziali normali con una credenziale con ambito limitato. 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-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 Ottenere i token di accesso OAuth 2.0. Puoi anche utilizzare OAuth 2.0 Playground per creare un token di accesso per il tuo Account Google.
Scambiare il token di accesso OAuth 2.0
Dopo aver creato un token di accesso OAuth 2.0, puoi scambiare il token di accesso con un token con ambito ridotto che rispetta il limite di accesso alle credenziali. Questo processo in genere coinvolge un token broker e un token consumer:
Il token broker è responsabile della definizione del confine di accesso alle 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 token manualmente.
Il consumatore di token richiede un token di accesso con ambito ridotto al token broker, quindi utilizza il token di accesso con ambito limitato per eseguire un'altra azione.
Il consumer dei 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.
Scambia e aggiorna automaticamente il token di accesso
Se crei il token token e il token token con una delle seguenti lingue, puoi utilizzare la libreria di autenticazione di Google per scambiare e aggiornare automaticamente i token:
Go
Per Go, puoi scambiare e aggiornare automaticamente i token con la versione 00.0.0-20210819190943-2bc19b11175f o versioni successive del pacchetto golang.org/x/oauth2
.
Per controllare quale versione di questo pacchetto stai utilizzando, esegui il comando seguente nella directory della tua applicazione:
go list -m golang.org/x/oauth2
L'esempio seguente mostra in che modo un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra come un consumer di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente token con ambito ridotto:
Java
Per Java, puoi scambiare e aggiornare automaticamente i token con la versione 1.1.0 o successiva 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
L'esempio seguente mostra in che modo un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra come un consumer di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente token con ambito ridotto:
Node.js
Per Node.js, puoi scambiare e aggiornare automaticamente i token con la versione 7.9.0 o successive del pacchetto google-auth-library
.
Per controllare quale versione di questo pacchetto stai utilizzando, esegui il comando seguente nella directory della tua applicazione:
npm list google-auth-library
L'esempio seguente mostra in che modo un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra in che modo 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 automaticamente i token con la versione 2.0.0 o successiva del pacchetto google-auth
.
Per controllare quale versione del pacchetto stai utilizzando, esegui il comando seguente nell'ambiente in cui è installato il pacchetto:
pip show google-auth
L'esempio seguente mostra in che modo un broker di token può generare token con ambito ridotto:
L'esempio seguente mostra in che modo 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. Fornisce quindi il token con ambito ridotto al consumatore di un token.
Per scambiare il token di accesso, utilizza il seguente metodo e URL HTTP:
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 confine di accesso alle credenziali in formato JSON, codificato con la 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 limitato che rispetta il limite di accesso alle credenziali. |
expires_in |
Il periodo di tempo fino alla scadenza del token con ambito ridotto, in secondi. Questo campo è presente solo se il token di accesso originale rappresenta un account di servizio. In assenza di questo campo, il token con ambito giù 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 nel file
./access-boundary.json
è archiviato un confine di accesso alle credenziali in formato 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 all'esempio seguente:
{
"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 deve rispondere sia con il token con ambito ridotto sia con il numero di secondi fino alla 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 per l'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.
- Vedi le autorizzazioni in ciascun ruolo predefinito.
- Scopri di più sui ruoli personalizzati.