In questa pagina viene spiegato come utilizzare i limiti di accesso alle credenziali per limitare o limitare le autorizzazioni di Identity and Access Management (IAM) che possono essere utilizzate da una breve durata.
Come funzionano i limiti di accesso alle credenziali
Per definire le autorizzazioni discendenti, definisci un confine di accesso alle credenziali che specifica a quali risorse può accedere la credenziale di breve durata, nonché un limite superiore delle autorizzazioni disponibili su ciascuna risorsa. Puoi quindi creare una credenziale di breve durata, quindi scambiarla con una nuova credenziale che rispetti il confine di accesso alle credenziali.
Se devi concedere alle entità un insieme distinto di autorizzazioni per ogni sessione, l'uso dei limiti di accesso alle credenziali può essere più efficiente rispetto alla creazione di molti account di servizio diversi e alla concessione a ogni account di servizio di un insieme di ruoli diverso. Ad esempio, se uno dei tuoi clienti ha bisogno di accedere ai dati di Cloud Storage controllati da te, puoi creare un account di servizio in grado di accedere a tutti i bucket Cloud Storage di tua proprietà, quindi applicare un limite di accesso alle credenziali che consenta di accedere al bucket solo con i dati dei tuoi clienti.
Esempi di limiti di accesso alle credenziali
Le seguenti sezioni mostrano esempi di limiti di accesso alle credenziali per casi d'uso comuni. Il limite di accesso alle credenziali viene utilizzato quando scambi un token di accesso OAuth 2.0 con un token con ambito giù.
Limita le autorizzazioni per un bucket
Il seguente esempio mostra un semplice confine di accesso alle credenziali. Si applica al bucket Cloud Storage example-bucket
e imposta il limite superiore sulle 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 confine di accesso alle credenziali che include le 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 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 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')" } } ] } }
Limita le autorizzazioni quando si elencano gli oggetti
Quando elenchi gli oggetti in un bucket Cloud Storage, chiami il metodo in 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 della 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ò causare comportamenti imprevisti quando elenchi oggetti.
Ad esempio, supponiamo che tu voglia un confine 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 condizione seguente nel confine di accesso alle 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 elencare gli oggetti:
- Quando un'entità tenta di leggere un oggetto in
example-bucket
con il prefissocustomer-a/invoices/
, la condizione viene valutata intrue
. - Quando un'entità tenta di elencare gli oggetti con quel prefisso, la condizione restituisce un 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 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 faccia 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/
:
Completato: 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 limitare le autorizzazioni solo per Cloud Storage, non per altri servizi Google Cloud.
Se hai bisogno di limitare le autorizzazioni per altri servizi Google Cloud, puoi creare più account di servizio e concedere un insieme di ruoli diverso a ogni account di servizio.
Puoi utilizzare l'accesso uniforme a livello di bucket per gestire l'accesso alle risorse Cloud Storage.
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:
-
Abilita le API IAM and Security Token Service.
Crea una credenziale di breve durata con ambito limitato
Per creare un token di accesso OAuth 2.0 con autorizzazioni con ambito ridotto, segui questi passaggi:
- Concedi i ruoli IAM appropriati a un account utente o di servizio.
- Definisci un limite 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.
- Sostituisci 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 giù per autenticare le richieste a Cloud Storage.
Concedi ruoli IAM
Un limite di accesso alle credenziali imposta un limite superiore per le autorizzazioni disponibili per una risorsa. Può sottrarre autorizzazioni da un'entità, ma non può aggiungere autorizzazioni che non sono già presenti.
Di conseguenza, devi anche concedere ruoli all'entità che fornisce le autorizzazioni necessarie, 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 all'account di servizio di creare oggetti in un bucket:
- Devi concedere almeno un ruolo all'account di servizio 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 includa altre autorizzazioni, ad esempio il ruolo Amministratore Storage Storage (
roles/storage.objectAdmin
). L'account di servizio può utilizzare solo le autorizzazioni visualizzate sia nella concessione del ruolo che nel limite di accesso alle credenziali.
Per saperne di più sui ruoli predefiniti per Cloud Storage, consulta Ruoli Cloud Storage.
Componenti di un limite di accesso alle credenziali
Un confine di accesso alle credenziali è un oggetto che contiene un elenco di regole di accesso ai limiti. 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, altrimenti 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, quest'ultimo può accedere solo alle risorse del limite di accesso alle credenziali. Non sono disponibili autorizzazioni per altre risorse.
Un confine di accesso alle credenziali può contenere fino a 10 regole per i limiti di accesso. Puoi applicare un solo limite di accesso alle credenziali a ogni credenziale di breve durata.
Quando viene 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 di confine 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 |
Opzione facoltativa. 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 di un bucket Cloud Storage. |
accessBoundary.accessBoundaryRules[].availabilityCondition.expression |
Un'espressione della condizione che specifica gli oggetti Cloud Storage in cui sono disponibili le autorizzazioni.
Per informazioni su come fare riferimento a oggetti specifici in un'espressione di condizione, consulta l'attributo |
accessBoundary.accessBoundaryRules[].availabilityCondition.title |
Opzione facoltativa. Una breve stringa che identifica lo scopo della condizione. |
accessBoundary.accessBoundaryRules[].availabilityCondition.description |
Opzione facoltativa. 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 la credenziale normale con una credenziale con ambito giù. 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 scambiarlo con un token con ambito giù che rispetti il confine di accesso alle credenziali. Questo processo in genere coinvolge un token broker e un token consumer:
Il mediatore token è responsabile della definizione del confine di accesso alle credenziali e dello scambio di un token di accesso con un token con ambito giù.
Il broker di token può utilizzare una libreria di autenticazione supportata per scambiare token di accesso automaticamente oppure può chiamare Security Token Service per scambiare token manualmente.
Il consumatore di token richiede un token di accesso con ambito giù dal broker di token, quindi lo utilizza per eseguire un'altra azione.
Il consumer dei token può utilizzare una libreria di autenticazione supportata per aggiornare automaticamente i token di accesso prima che scadano. 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 broker di token e il consumer di 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 del pacchetto stai utilizzando, esegui questo comando 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 giù:
L'esempio seguente mostra in che modo il consumer dei token può utilizzare un gestore degli aggiornamenti per ottenere e aggiornare automaticamente i token con ambito giù:
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 questo comando Maven nella directory della tua 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 giù:
L'esempio seguente mostra in che modo il consumer dei token può utilizzare un gestore degli aggiornamenti per ottenere e aggiornare automaticamente i token con ambito giù:
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 del pacchetto stai utilizzando, esegui questo comando 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 giù:
L'esempio seguente mostra in che modo un consumer di token può fornire un gestore che aggiorna e ottiene automaticamente i token con ambito giù:
Python
Per Python, puoi scambiare e aggiornare automaticamente i token con la versione 2.0.0 o successive del pacchetto google-auth
.
Per controllare quale versione del pacchetto stai utilizzando, esegui questo comando 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 giù:
L'esempio seguente mostra in che modo un consumer di token può fornire un gestore che aggiorna e ottiene automaticamente i token con ambito giù:
Scambia e aggiorna 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 giù. Può quindi fornire il token con ambito giù a un consumer di token.
Per scambiare il token di accesso, utilizza il metodo e l'URL HTTP seguenti:
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 limite di accesso alle credenziali 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 confine di accesso alle credenziali. |
expires_in |
Il periodo di tempo fino alla scadenza del token con ambito, in secondi. Questo campo è presente solo se il token di accesso originale rappresenta un account di servizio. Se questo campo non è presente, il token con ambito giù ha la stessa data di scadenza del token di accesso originale. |
issued_token_type |
Contiene il valore |
token_type |
Contiene il valore |
Ad esempio, se un file 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 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 giù, il broker di token deve rispondere sia con il token con ambito limitato sia con il numero di secondi fino alla scadenza. Per aggiornare il token con ambito limitato, il consumatore può richiedere un token con ambito limitato all'intermediario prima della scadenza del token esistente.
Passaggi successivi
- Scopri di più sul controllo dell'accesso per Cloud Storage.
- Comprendi l'accesso uniforme a livello di bucket per Cloud Storage.
- Creare una credenziale di account di servizio di breve durata.
- Creare un token di accesso OAuth 2.0 per un account di servizio utilizzando il flusso OAuth 2.0 server-server o l'API Service Account Credentials.
- Creare un token di accesso OAuth 2.0 per un utente.
- Vedi le autorizzazioni in ogni ruolo predefinito.
- Scopri di più sui ruoli personalizzati.