Migrazione all'API Service Account Credentials

L'API Service Account Credentials crea credenziali di breve durata per gli account di servizio Identity and Access Management (IAM). Puoi anche usano questa API per firmare token web JSON (JWT) e BLOB di dati binari che contengono altri tipi di token.

L'API IAM contiene anche metodi per la firma di JWT e blob binari. A partire dal 1° luglio 2020, questi metodi sono deprecate nell'API REST e in tutte le librerie client per l'API IAM. Inoltre, se utilizzi Google Cloud CLI per JWT, potrebbe essere necessario aggiungere una nuova rivendicazione al set di rivendicazioni JWT. Puoi ancora utilizzano i metodi deprecati, ma non supportano funzionalità avanzate come HTTP richiedere il raggruppamento in batch. Ti invitiamo a eseguire la migrazione l'API Service Account Credentials.

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

In questa pagina viene spiegato come aggiornare il codice esistente per utilizzare l'account di servizio API Credentials. Se hai feedback in merito a questa modifica, puoi compila il modulo di feedback. Puoi anche utilizzare l'indirizzo email [e-mail] per richiedere assistenza e fornire feedback dettagliati.

Prima di iniziare

• Enable the Service Account Credentials API.

  Enable the API

Abilitazione degli audit log

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

Esistono alcune differenze significative tra le voci di log specificate in ogni API genera:

Differenze per le voci di audit log
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 di le 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 di accesso ai dati vengono conteggiati ai fini dell'allocazione mensile gratuita di dati di logging per l'importazione. Se superi questa allocazione, ti verrà addebitato un costo per l'importazione dei log. Per maggiori dettagli, vedi Prezzi per Google Cloud Observability.

Migrazione del codice per la firma dei JWT

Questa sezione descrive come eseguire la migrazione del codice che firma i JWT al servizio API Account Credentials.

Firma di JWT con l'API REST

La tabella seguente mostra le differenze tra la firma di un JWT con l'API REST IAM. firmare un JWT con l'API Service Account Credentials. Aggiorna il tuo codice per riflettere queste differenze:

Differenze per la firma di un JWT
Endpoint HTTP	API IAM L'API IAM utilizza i seguenti metodi e 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 l'account di servizio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt In questo URL, il carattere jolly - sostituisce dell'ID progetto, mentre sa-email è per l'account di servizio. API Service Account Credentials Utilizza il seguente metodo e endpoint HTTP. 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 dell'account di servizio.
Corpo della richiesta	API IAM Il corpo della richiesta include un campo payload. Il suo valore è il payload JWT . Il payload deve essere un oggetto JSON, serializzato come stringa, che contiene un insieme di attestazioni JWT. Se fornisci una rivendicazione relativa alla data di scadenza (exp), questa non deve essere superiore a 12 ore nel futuro. Se ometti la rivendicazione exp, viene aggiunta automaticamente ed è impostata su 1 ora nel futuro. API Service Account Credentials Il corpo della richiesta include un campo payload identico al API IAM, ad eccezione del comportamento della scadenza Rivendicazione (exp): Se fornisci la rivendicazione exp, la sua durata non deve essere superiore a 12 ore nel futuro. Se ometti la rivendicazione exp, questa non viene aggiunta automaticamente. Devi fornire questa dichiarazione 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 di JWT con una libreria client

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

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

C#

Aggiungi la libreria client delle credenziali dell'account di servizio per C# alla tua applicazione. Utilizza la Metodo SignJwt() per generare una firma.

Il nome dell'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 la libreria client delle credenziali dell'account di servizio per Go alla tua applicazione. Utilizza la IamCredentialsClient.SignJwt() function per generare una firma.

Il nome dell'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 rimuoverlo dall'applicazione.

Java

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

Il nome dell'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 rimuoverlo dalla tua applicazione.

Node.js

Aggiungi la libreria client delle credenziali dell'account di servizio per Node.js alla tua applicazione. Utilizza la Metodo signJwt() per generare una firma.

Il nome dell'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 rimuoverlo dall'applicazione.

PHP

Aggiungi la libreria client delle credenziali dell'account di servizio per PHP alla tua applicazione. Utilizza la Metodo signJwt() per generare una firma.

Il nome dell'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 rimuoverlo dall'applicazione.

Python

Aggiungi la libreria client delle credenziali dell'account di servizio per Python alla tua applicazione. Utilizza la Metodo sign_jwt() per generare una firma.

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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ù iam_credentials libreria client, puoi rimuoverla dall'applicazione.

Ruby

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

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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 dall'applicazione.

Migrazione del codice per la firma dei 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 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 per riflettere queste differenze:

Differenze per la firma di un blob binario
Endpoint HTTP	API IAM L'API IAM utilizza i seguenti metodi e 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 l'account di servizio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob In questo URL, il carattere jolly - sostituisce dell'ID progetto, mentre sa-email è per l'account di servizio. API Service Account Credentials Utilizza il seguente metodo e endpoint HTTP. 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 dell'account di servizio.
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 che ha lo stesso valore del bytesToSign nell'API IAM.
Corpo della risposta	API IAM Il corpo della risposta contiene un campo keyId, che identifica la chiave utilizzato per firmare il blob e un campo signature, che contiene una codifica base64 stringa 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 Credenziali account di servizio sono separate dalle librerie client per l'API IAM.

Per utilizzare l'API Service Account Credentials, aggiungi la relativa libreria client al tuo 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 altro client libreria:

Esegui l'upgrade alla versione 0.9.0 o successiva 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 la libreria client delle credenziali dell'account di servizio per C# alla tua applicazione. Utilizza la Metodo SignBlob() per generare una firma.

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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 rimuoverlo dall'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 successiva 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 in un'altra libreria client:

Aggiungi la libreria client delle credenziali dell'account di servizio per Go alla tua applicazione. Utilizza la IamCredentialsClient.SignBlob() function per generare una firma.

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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 rimuoverlo dall'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 successiva 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 in un'altra libreria client:

Aggiungi la libreria client delle credenziali dell'account di servizio per Java alla tua applicazione. Utilizza la Metodo IamCredentialsClient#signBlob() per generare una firma.

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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 rimuoverlo dalla tua applicazione.

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

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

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

Esegui l'upgrade alla versione 7.0.1 o successiva 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 in un'altra libreria client:

Aggiungi la libreria client delle credenziali dell'account di servizio per Node.js alla tua applicazione. Utilizza la Metodo signBlob() per generare una firma.

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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 rimuoverlo dall'applicazione.

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

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

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

Esegui l'upgrade alla versione 8.13.0 o successiva 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 in un'altra libreria client:

Aggiungi la libreria client Credenziali dell'account di servizio per PHP alla tua applicazione. Utilizza la Metodo signBlob() per generare una firma.

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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 di autenticazione di Google per PHP, direttamente o come dipendenza di un'altra libreria client:

Esegui l'upgrade alla versione 1.5.0 o successiva 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 in un'altra libreria client:

Aggiungi la libreria client delle credenziali dell'account di servizio per Python alla tua applicazione. Utilizza la Metodo sign_blob() per generare una firma.

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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ù iam_credentials libreria client, puoi rimuoverla dall'applicazione.

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

Esegui l'upgrade alla versione 1.21.2 o successiva 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 successiva 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 in un'altra libreria client:

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

Il nome dell'account di servizio deve utilizzare il carattere jolly - per rappresentare 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 dall'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 creare segni di 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 in modo che utilizzare l'API Service Account Credentials. Questa modifica non influirà sui comandi o firmare blob.

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

1. Controlla se includi la rivendicazione relativa alla data di scadenza (exp) nelle rivendicazioni JWT partenza,

   Se includi già questa rivendicazione, non è necessario apportare modifiche. Tu puoi saltare i passaggi rimanenti.

   Se non includi questa dichiarazione, vai al passaggio successivo.

2. Controlla se utilizzi il JWT firmato per l'autenticazione con le API di Google. con un'altra API che richiede la rivendicazione exp.

   Se ometti questa dichiarazione, l'API IAM la imposta automaticamente a un'ora nel futuro. Nel al contrario, l'API Service Account Credentials non imposta questo campo automaticamente.

   Se hai la certezza di non avere bisogno della rivendicazione exp, non è necessario apportare modifiche. Puoi saltare i passaggi rimanenti.

   Se hai bisogno di una rivendicazione di exp o hai dubbi, continua al passaggio successivo.

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

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

Controllo 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 dover richiedere un aumento anche per l'API Credentials Service Account.

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

Per visualizzare la tua quota e l'utilizzo effettivo per entrambe le API e per richiedere una quota aumenta se necessario:

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 e 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, poi seleziona il valore visualizzato.

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

6. Confronta le quote per ogni riga della tabella e assicurati che la tua quota l'API Service Account Credentials è superiore all'utilizzo di picco negli ultimi 7 giorni l'API IAM.

7. (Facoltativo) Se la quota per l'API Credenziali account di servizio è troppo bassa, seleziona la casella di controllo per l'API Credenziali account di servizio, 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 IAM. API per firmare JWT e BLOB.

Passaggi successivi

• Scopri come creare un JWT firmato. crea un BLOB binario firmato con l'account di servizio API REST Credentials.
• Ottieni dettagli su API REST per l'API Service Account Credentials.
• Scopri di più su quote e limiti per IAM.