Migrazione all'API Service Account Credentials

L'API Service Account Credentials crea credenziali di breve durata per i service account Identity and Access Management (IAM). Puoi anche utilizzare questa API per firmare token web JSON (JWT), nonché blob di dati binari che contengono altri tipi di token.

L'API IAM contiene anche metodi per firmare JWT e blob binari. A partire dal 1° luglio 2020, questi metodi sono ritirati nell'API REST e in tutte le librerie client per l'API IAM. Inoltre, se utilizzi Google Cloud CLI per firmare i JWT, potresti dover aggiungere una nuova rivendicazione al set di rivendicazioni JWT. Puoi comunque utilizzare i metodi ritirati, ma non supportano funzionalità avanzate come il batching delle richieste HTTP. Ti invitiamo a eseguire la migrazione all'API Service Account Credentials.

Rispetto all'API IAM, l'API Service Account Credentials offre maggiore flessibilità per il tempo di scadenza dei JWT firmati. Inoltre, l'API Service Account Credentials aggiunge diversi nuovi metodi API per generare token di rappresentazione.

Questa pagina spiega come aggiornare il codice esistente per utilizzare l'API Service Account Credentials. Se hai un feedback su questa modifica, puoi compilare il modulo di feedback. Puoi anche utilizzare l'indirizzo email [e-mail] per richiedere assistenza e fornire feedback dettagliato.

Prima di iniziare

• Enable the Service Account Credentials API.

  Enable the API

Abilitazione degli audit log

Se vuoi ricevere audit log per le richieste di firma di JWT e blob, devi attivare gli audit log di accesso ai dati per l'API IAM. L'attivazione dei log di controllo dell'accesso ai dati per l'API IAM attiva questi log di controllo anche per l'API Service Account Credentials.

Esistono alcune differenze significative tra le voci di log generate da ciascuna API:

Differenze per le voci del log di controllo
Nome metodo	API IAM Il nome del metodo (protoPayload.methodName) è uno dei seguenti: google.iam.admin.v1.SignBlob google.iam.admin.v1.SignJwt API Service Account Credentials Il nome del metodo è uno dei seguenti: SignBlob SignJwt
Tipo di richiesta	API IAM Il tipo di richiesta (protoPayload.request.@type) è uno dei seguenti: type.googleapis.com/google.iam.admin.v1.SignBlobRequest type.googleapis.com/google.iam.admin.v1.SignJwtRequest API Service Account Credentials Il tipo di richiesta è uno dei seguenti: type.googleapis.com/google.iam.credentials.v1.SignBlobRequest type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
Nome servizio	API IAM Il nome del servizio (protoPayload.serviceName) è iam.googleapis.com. API Service Account Credentials Il nome del servizio è iamcredentials.googleapis.com.

Gli audit log degli accessi ai dati vengono conteggiati ai fini dell'allocazione mensile gratuita di inserimento dei dati di logging. Se superi questa quota, ti verrà addebitato l'inserimento dei log. Per informazioni dettagliate, consulta la pagina Prezzi di Google Cloud Observability.

Migrazione del codice per la firma dei JWT

Questa sezione descrive come eseguire la migrazione del codice che firma i JWT all'API Service Account Credentials.

Firma di JWT con l'API REST

La seguente tabella mostra le differenze tra la firma di un JWT con l'API REST IAM e la firma di un JWT con l'API Service Account Credentials. Aggiorna il codice in modo che rifletta queste differenze:

Differenze per la firma di un JWT
Endpoint HTTP	API IAM L'API IAM utilizza i seguenti metodi ed endpoint HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt In questo URL, project-id è l'ID progetto e sa-email è l'indirizzo email dell'account di servizio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt In questo URL, il carattere jolly - sostituisce l'ID progetto e sa-email è l'indirizzo email del account di servizio. API Service Account Credentials Utilizza il seguente metodo HTTP ed endpoint. Non sostituire il carattere jolly con l'ID progetto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt In questo URL, sa-email è l'indirizzo email del service account.
Corpo della richiesta	API IAM Il corpo della richiesta include un campo payload. Il suo valore è il payload JWT da firmare. Il payload deve essere un oggetto JSON, serializzato come stringa, che contiene un insieme di rivendicazioni JWT. Se fornisci un'attestazione del tempo di scadenza (exp), questo non deve superare 12 ore in futuro. Se ometti la rivendicazione exp, questa viene aggiunta automaticamente e impostata su 1 ora nel futuro. API Service Account Credentials Il corpo della richiesta include un campo payload identico a quello dell'API IAM, ad eccezione del comportamento dell'attestazione relativa alla data di scadenza (exp): Se fornisci la rivendicazione exp, questa non deve essere più di 12 ore in futuro. Se ometti l'attributo exp, questo non viene aggiunto automaticamente. Devi fornire questa rivendicazione se utilizzi il JWT firmato per l'autenticazione con le API di Google o con un'altra API che richiede la rivendicazione exp.
Corpo della risposta	Entrambe le API utilizzano gli stessi campi nel corpo della risposta.

Firma dei JWT con una libreria client

Le librerie client per l'API Service Account Credentials sono separate da quelle per l'API IAM.

Per utilizzare l'API Service Account Credentials, aggiungi la relativa libreria client alla tua applicazione e aggiorna il codice per utilizzare la nuova libreria client:

C#

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per C#. Utilizza il metodo SignJwt() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per C#, puoi rimuoverla dalla tua applicazione.

Go

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per Go. Utilizza IamCredentialsClient.SignJwt() function per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Go, puoi rimuoverla dalla tua applicazione.

Java

Aggiungi la libreria client delle credenziali del service account per Java alla tua applicazione. Utilizza il metodo IamCredentialsClient#signJwt() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Java, puoi rimuoverla dalla tua applicazione.

Node.js

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per Node.js. Utilizza il metodo signJwt() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Node.js, puoi rimuoverla dalla tua applicazione.

PHP

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per PHP. Utilizza il metodo signJwt() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per PHP, puoi rimuoverla dalla tua applicazione.

Python

Aggiungi la libreria client delle credenziali del service account per Python alla tua applicazione. Utilizza il metodo sign_jwt() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la iam_credentials libreria client, puoi rimuoverla dalla tua applicazione.

Ruby

Aggiungi alla tua applicazione la libreria client delle credenziali dell'account di servizio per Ruby. Utilizza il metodo sign_service_account_jwt() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Ruby, puoi rimuoverla dalla tua applicazione.

Migrazione del codice per la firma di blob binari

Questa sezione descrive come eseguire la migrazione del codice che firma i blob binari all'API Service Account Credentials.

Firma di blob binari con l'API REST

La tabella seguente mostra le differenze tra la firma di un blob binario con l'API REST IAM e la firma di un blob binario con l'API Service Account Credentials. Aggiorna il codice in modo che rifletta queste differenze:

Differenze per la firma di un blob binario
Endpoint HTTP	API IAM L'API IAM utilizza i seguenti metodi ed endpoint HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob In questo URL, project-id è l'ID progetto e sa-email è l'indirizzo email dell'account di servizio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob In questo URL, il carattere jolly - sostituisce l'ID progetto e sa-email è l'indirizzo email del account di servizio. API Service Account Credentials Utilizza il seguente metodo HTTP ed endpoint. Non sostituire il carattere jolly con l'ID progetto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob In questo URL, sa-email è l'indirizzo email del service account.
Corpo della richiesta	API IAM Il corpo della richiesta include un campo bytesToSign. Il suo valore è una stringa codificata in base64 che rappresenta il blob binario da firmare. API Service Account Credentials Il corpo della richiesta include un campo payload con lo stesso valore del campo bytesToSign nell'API IAM.
Corpo della risposta	API IAM Il corpo della risposta contiene un campo keyId, che identifica la chiave utilizzata per firmare il blob, e un campo signature, che contiene una stringa con codifica Base64 che rappresenta la firma. API Service Account Credentials Il corpo della risposta contiene un campo keyId identico al campo keyId dell'API IAM, nonché un campo signedBlob identico al campo signature dell'API IAM. Nota: il campo signedBlob contiene solo la firma, non il blob originale.

Firma di blob binari con una libreria client

Le librerie client per l'API Service Account Credentials sono separate da quelle per l'API IAM.

Per utilizzare l'API Service Account Credentials, aggiungi la relativa libreria client alla tua applicazione e aggiorna il codice per utilizzare la nuova libreria client:

C++

Se utilizzi la libreria client C++ di Cloud Storage per firmare blob,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 0.9.0 o successive di google-cloud-cpp.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

C#

Se utilizzi la libreria client IAM per C#, direttamente o come dipendenza di un'altra libreria client:

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per C#. Utilizza il metodo SignBlob() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per C#, puoi rimuoverla dalla tua applicazione.

Se utilizzi l'SDK Firebase Admin DotNet,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 1.17.1 o successive di firebase-admin-dotnet.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

Go

Se utilizzi la libreria client IAM per Go, direttamente o come dipendenza di un'altra libreria client:

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per Go. Utilizza IamCredentialsClient.SignBlob() function per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Go, puoi rimuoverla dalla tua applicazione.

Se utilizzi l'SDK Firebase Admin Go,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 4.1.0 o successive di firebase-admin-go.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

Java

Se utilizzi la libreria client IAM per Java, direttamente o come dipendenza di un'altra libreria client:

Aggiungi la libreria client delle credenziali del service account per Java alla tua applicazione. Utilizza il metodo IamCredentialsClient#signBlob() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Java, puoi rimuoverla dalla tua applicazione.

Se utilizzi la libreria Google Auth per Java,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 0.14.0 o successive di google-auth-library-java.

Se utilizzi l'SDK Firebase Admin Java,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 7.0.1 o successive di firebase-admin-java.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

Node.js

Se utilizzi la libreria client IAM per Node.js, direttamente o come dipendenza di un'altra libreria client:

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per Node.js. Utilizza il metodo signBlob() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Node.js, puoi rimuoverla dalla tua applicazione.

Se utilizzi la libreria Google Auth per Node.js,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 6.0.0 o successive di google-auth-library-nodejs.

Se utilizzi l'SDK Firebase Admin Node.js,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 8.13.0 o successive di firebase-admin-node.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

PHP

Se utilizzi la libreria client IAM per PHP, direttamente o come dipendenza di un'altra libreria client:

Aggiungi alla tua applicazione la libreria client delle credenziali del service account per PHP. Utilizza il metodo signBlob() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per PHP, puoi rimuoverla dalla tua applicazione.

Se utilizzi la libreria Google Auth per PHP,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 1.5.0 o successive di google-auth-library-php.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

Python

Se utilizzi la libreria client IAM per Python, direttamente o come dipendenza di un'altra libreria client:

Aggiungi la libreria client delle credenziali del service account per Python alla tua applicazione. Utilizza il metodo sign_blob() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la iam_credentials libreria client, puoi rimuoverla dalla tua applicazione.

Se utilizzi la libreria Google Auth per Python,direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 1.21.2 o successive di google-auth-library-python.

Se utilizzi il client Python per Cloud Storage, direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 1.30.0 o successive di python-storage.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

Ruby

Se utilizzi la libreria client IAM per Ruby, direttamente o come dipendenza di un'altra libreria client:

Aggiungi alla tua applicazione la libreria client delle credenziali dell'account di servizio per Ruby. Utilizza il metodo sign_service_account_blob() per generare una firma.

Il nome del account di servizio deve utilizzare il carattere jolly - per rappresentare l'ID progetto:

Valido: nome con carattere jolly

projects/-/serviceAccounts/[e-mail]

Non valido: nome con ID progetto

projects/my-project/serviceAccounts/[e-mail]

Se non utilizzi più la libreria client IAM per Ruby, puoi rimuoverla dalla tua applicazione.

Se utilizzi un'altra libreria client per firmare i blob:

Contatta [e-mail] per ricevere assistenza.

Migrazione del codice che utilizza gcloud CLI

Google Cloud CLI fornisce comandi che utilizzano l'API IAM per firmare JWT e blob binari, tra cui:

• gcloud beta iam service-accounts sign-jwt
• gcloud iam service-accounts sign-blob

A partire dal 1° luglio 2021, aggiorneremo questi comandi per utilizzare l'API Service Account Credentials. Questa modifica non influirà sui comandi per firmare i blob.

Se utilizzi gcloud CLI per firmare i JWT, devi seguire questi passaggi prima del 1° luglio 2021:

1. Controlla di aver incluso l'attestazione del tempo di scadenza (exp) nel set di attestazioni JWT.

   Se hai già incluso questa dichiarazione, non devi apportare alcuna modifica. Puoi ignorare i passaggi rimanenti.

   Se non includi questa rivendicazione, vai al passaggio successivo.

2. Verifica se utilizzi il JWT firmato per l'autenticazione con le API di Google o con un'altra API che richiede l'attestazione exp.

   Se ometti questa rivendicazione, l'API IAM la imposta automaticamente su 1 ora in futuro. Al contrario, l'API Service Account Credentials non imposta automaticamente questo campo.

   Se hai la certezza di non aver bisogno della rivendicazione exp, non devi apportare alcuna modifica. Puoi ignorare i passaggi successivi.

   Se sai di aver bisogno della rivendicazione exp o se non ne hai la certezza, vai al passaggio successivo.

3. Aggiorna il codice per la creazione di JWT in modo che aggiunga l'attestazione exp al set di attestazioni JWT.

   Puoi impostare la richiesta exp fino a 1 ora nel futuro.

Verifica delle quote

La quota per l'API Service Account Credentials è separata dalla quota per l'API IAM. Se hai ricevuto un aumento della quota per firmare JWT e blob con l'API IAM, potresti anche dover richiedere un aumento per l'API Service Account Credentials.

Nota: la maggior parte Google Cloud dei clienti utilizza la quota predefinita per la firma di JWT e blob. Se utilizzi la quota predefinita, non è necessario leggere questa sezione.

Per visualizzare la quota e l'utilizzo effettivo per entrambe le API e per richiedere un aumento della quota, se necessario, procedi nel seguente modo:

1. Nella console Google Cloud , vai alla pagina Quote.

   Vai alla pagina Quote

2. Seleziona un progetto. Puoi fare clic su un progetto recente oppure su Seleziona progetto per cercare in tutti i tuoi progetti.

3. Nella casella di testo Filtra tabella sopra la tabella, inserisci Sign requests per minute, quindi seleziona il valore visualizzato.

4. Nella casella di testo Filtra tabella, seleziona OR dall'elenco a discesa.

5. Nella casella di testo Filtra tabella, inserisci Generate credentials, quindi seleziona il valore visualizzato.

   La console Google Cloud mostra l'utilizzo attuale per la firma di JWT e blob nell'ultimo minuto, l'utilizzo di picco al minuto negli ultimi 7 giorni e la quota attuale, che viene visualizzata nella colonna Limite.

6. Confronta le quote per ogni riga della tabella e assicurati che la quota per l'API Service Account Credentials sia superiore al picco di utilizzo di 7 giorni dell'API IAM.

7. (Facoltativo) Se la quota per l'API Service Account Credentials è troppo bassa, seleziona la casella di controllo per l'API Service Account Credentials, quindi fai clic su Modifica quote. Compila il modulo per richiedere un aumento della quota.

8. Ripeti questi passaggi per ogni progetto in cui utilizzi l'API IAM per firmare JWT e blob.

Passaggi successivi

• Scopri come creare un JWT firmato o creare un blob binario firmato con l'API REST Service Account Credentials.
• Scopri di più sull'API REST per l'API Service Account Credentials.
• Comprendere quote e limiti per IAM.