Migrer vers l'API Service Account Credentials

L'API Service Account Credentials permet de créer des identifiants éphémères pour les comptes de service Cloud IAM (Cloud Identity and Access Management). Vous pouvez également l'utiliser pour signer des jetons Web JSON (JWT), ainsi que des blobs de données binaires contenant d'autres types de jetons.

L'API Cloud IAM contient également des méthodes de signature de jetons JWT et de blobs binaires. Depuis le 1er juillet 2020, ces méthodes sont obsolètes dans l'API REST et dans toutes les bibliothèques clientes de l'API Cloud IAM. Si vous utilisez Google Cloud CLI pour signer les jetons JWT, vous devrez peut-être ajouter une nouvelle revendication à l'ensemble de revendications JWT. Vous pouvez toujours utiliser les méthodes obsolètes, mais elles ne sont pas compatibles avec les fonctionnalités avancées telles que le traitement par lot des requêtes HTTP. Nous vous encourageons plutôt à migrer vers l'API Service Account Credentials.

Par rapport à l'API Cloud IAM, l'API Service Account Credentials offre plus de flexibilité en ce qui concerne le délai d'expiration des jetons JWT signés. De plus, l'API Service Account Credentials ajoute plusieurs nouvelles méthodes d'API pour générer des jetons d'usurpation d'identité.

Cette page explique comment mettre à jour votre code existant pour utiliser l'API Service Account Credentials. Si vous avez des commentaires sur cette modification, nous vous invitons à remplir le formulaire de commentaires. Vous pouvez également contacter [e-mail] pour demander de l'aide et envoyer des commentaires détaillés.

Avant de commencer

• Enable the Service Account Credentials API.

  Enable the API

Activer les journaux d'audit

Si vous souhaitez recevoir les journaux d'audit associés aux requêtes de signature de jetons JWT et de blobs, vous devez activer les journaux d'audit d'accès aux données pour l'API Cloud IAM. L'activation des journaux d'audit d'accès aux données pour l'API Cloud IAM active également ces journaux d'audit pour l'API Service Account Credentials.

Il existe quelques différences notables entre les entrées de journal générées par chaque API :

Différences entre les entrées de journal d'audit
Nom de la méthode	API IAM Le nom de la méthode (protoPayload.methodName) est l'un des suivants : google.iam.admin.v1.SignBlob google.iam.admin.v1.SignJwt API Service Account Credentials Le nom de la méthode est l'un des suivants : SignBlob SignJwt
Type de demande	API IAM Le type de requête (protoPayload.request.@type) est l'un des suivants : type.googleapis.com/google.iam.admin.v1.SignBlobRequest type.googleapis.com/google.iam.admin.v1.SignJwtRequest API Service Account Credentials Le type de requête est l'un des suivants : type.googleapis.com/google.iam.credentials.v1.SignBlobRequest type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
Nom du service	API IAM Le nom du service (protoPayload.serviceName) est iam.googleapis.com. API Service Account Credentials Le nom du service est iamcredentials.googleapis.com.

Les journaux d'audit d'accès aux données sont comptabilisés dans votre quota mensuel gratuit d'ingestion de données de journalisation. Si vous dépassez ce quota, l'ingestion de journaux vous sera facturée. Pour en savoir plus, consultez la page Tarifs de Google Cloud Observability.

Migrer du code pour signer des jetons JWT

Cette section explique comment migrer le code qui signe les jetons JWT vers l'API Service Account Credentials.

Signer des jetons JWT avec l'API REST

Le tableau suivant montre les différences entre signer un jeton JWT avec l'API REST IAM et signer un jeton JWT avec l'API Service Account Credentials. Mettez à jour votre code pour refléter les différences suivantes :

Différences de signature d'un jeton JWT
Points de terminaison HTTP	API IAM L'API Cloud IAM utilise les méthodes HTTP et les points de terminaison suivants : POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt Dans cette URL, project-id est l'ID du projet et sa-email est l'adresse e-mail du compte de service. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Dans cette URL, le caractère générique - remplace l'ID du projet, et sa-email est l'adresse e-mail du compte de service. API Service Account Credentials Utilisez la méthode HTTP et le point de terminaison suivants. Ne remplacez pas le caractère générique par l'ID du projet : POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Dans cette URL, sa-email est l'adresse e-mail du compte de service.
Corps de la requête	API IAM Le corps de la requête comprend un champ payload. Sa valeur correspond à la charge utile du jeton JWT à signer. La charge utile doit être un objet JSON, sérialisé en tant que chaîne, contenant un ensemble de revendications JWT. Si vous spécifiez une revendication de délai d'expiration (exp), elle ne doit pas dépasser 12 heures dans le futur. Si vous omettez la revendication exp, elle est ajoutée automatiquement et définie sur 1 heure dans le futur. API Service Account Credentials Le corps de la requête inclut un champ payload identique à l'API Cloud IAM, à l'exception du comportement de la revendication de délai d'expiration (exp) : Si vous envoyez la revendication exp, elle ne doit pas dépasser 12 heures dans le futur. Si vous omettez la revendication exp, elle n'est pas ajoutée automatiquement. Vous devez fournir cette revendication si vous utilisez le jeton JWT signé pour vous authentifier auprès des API Google ou d'une autre API nécessitant la revendication exp.
Corps de la réponse	Les deux API utilisent les mêmes champs dans le corps de la réponse.

Signer des jetons JWT avec une bibliothèque cliente

Les bibliothèques clientes de l'API Service Account Credentials sont distinctes de celles de l'API Cloud IAM.

Pour utiliser l'API Service Account Credentials, ajoutez sa bibliothèque cliente à votre application et mettez à jour votre code pour utiliser la nouvelle bibliothèque cliente :

C#

Ajoutez la bibliothèque cliente Service Account Credentials pour C# à votre application. Utilisez la méthode SignJwt() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour C#, vous pouvez la supprimer de votre application.

Go

Ajoutez la bibliothèque cliente Service Account Credentials pour Go à votre application. Utilisez IamCredentialsClient.SignJwt() function pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Go, vous pouvez la supprimer de votre application.

Java

Ajoutez la bibliothèque cliente Service Account Credentials pour Java à votre application. Utilisez la méthode IamCredentialsClient#signJwt() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Java, vous pouvez la supprimer de votre application.

Node.js

Ajoutez la bibliothèque cliente Service Account Credentials pour Node.js à votre application. Utilisez la méthode signJwt() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Node.js, vous pouvez la supprimer de votre application.

PHP

Ajoutez la bibliothèque cliente Service Account Credentials pour PHP à votre application. Utilisez la méthode signJwt() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour PHP, vous pouvez la supprimer de votre application.

Python

Ajoutez la bibliothèque cliente Service Account Credentials pour Python à votre application. Utilisez la méthode sign_jwt() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente iam_credentials, vous pouvez la supprimer de votre application.

Ruby

Ajoutez la bibliothèque cliente Service Account Credentials pour Ruby à votre application. Utilisez la méthode sign_service_account_jwt() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Ruby, vous pouvez la supprimer de votre application.

Migrer du code pour signer des blobs binaires

Cette section explique comment migrer le code qui signe des blobs binaires vers l'API Service Account Credentials.

Signer des blobs binaires avec l'API REST

Le tableau suivant montre les différences entre signer un blob binaire avec l'API Cloud IAM et signer un blob binaire avec l'API Service Account Credentials. Mettez à jour votre code pour refléter les différences suivantes :

Différences de signature d'un blob binaire
Points de terminaison HTTP	API IAM L'API Cloud IAM utilise les méthodes HTTP et les points de terminaison suivants : POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob Dans cette URL, project-id est l'ID du projet et sa-email est l'adresse e-mail du compte de service. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Dans cette URL, le caractère générique - remplace l'ID du projet, et sa-email est l'adresse e-mail du compte de service. API Service Account Credentials Utilisez la méthode HTTP et le point de terminaison suivants. Ne remplacez pas le caractère générique par l'ID du projet : POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Dans cette URL, sa-email est l'adresse e-mail du compte de service.
Corps de la requête	API IAM Le corps de la requête comprend un champ bytesToSign. Sa valeur est une chaîne encodée en base64 qui représente l'objet blob binaire à signer. API Service Account Credentials Le corps de la requête inclut un champ payload qui a la même valeur que le champ bytesToSign de l'API Cloud IAM.
Corps de la réponse	API IAM Le corps de la réponse contient un champ keyId qui identifie la clé utilisée pour signer l'objet blob, et un champ signature contenant une chaîne encodée en base64 qui représente la signature. API Service Account Credentials Le corps de la réponse contient un champ keyId identique au champ keyId de l'API Cloud IAM, ainsi qu'un champ signedBlob identique au champ signature de l'API Cloud IAM. Remarque : Le champ signedBlob contient uniquement la signature, et non l'objet blob d'origine.

Signer des blobs binaires avec une bibliothèque cliente

Les bibliothèques clientes de l'API Service Account Credentials sont distinctes de celles de l'API Cloud IAM.

Pour utiliser l'API Service Account Credentials, ajoutez sa bibliothèque cliente à votre application et mettez à jour votre code pour utiliser la nouvelle bibliothèque cliente :

C++

Si vous utilisez la bibliothèque cliente C++ de Cloud Storage pour signer des blobsdirectement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 0.9.0 ou une version ultérieure de google-cloud-cpp.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

C#

Si vous utilisez la bibliothèque cliente IAM pour C# directement ou en tant que dépendance d'une autre bibliothèque cliente :

Ajoutez la bibliothèque cliente Service Account Credentials pour C# à votre application. Utilisez la méthode SignBlob() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour C#, vous pouvez la supprimer de votre application.

Si vous utilisez le SDK Firebase Admin DotNet, directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 1.17.1 ou une version ultérieure de firebase-admin-dotnet.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

Go

Si vous utilisez la bibliothèque cliente Cloud IAM pour Go directement ou en tant que dépendance d'une autre bibliothèque cliente :

Ajoutez la bibliothèque cliente Service Account Credentials pour Go à votre application. Utilisez IamCredentialsClient.SignBlob() function pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Go, vous pouvez la supprimer de votre application.

Si vous utilisez le SDK Firebase Admin Go, directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 4.1.0 ou une version ultérieure de firebase-admin-go.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

Java

Si vous utilisez la bibliothèque cliente IAM pour Java directement ou en tant que dépendance d'une autre bibliothèque cliente :

Ajoutez la bibliothèque cliente Service Account Credentials pour Java à votre application. Utilisez la méthode IamCredentialsClient#signBlob() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Java, vous pouvez la supprimer de votre application.

Si vous utilisez la bibliothèque Google Auth pour Java directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 0.14.0 ou une version ultérieure de google-auth-library-java.

Si vous utilisez le SDK Firebase Admin Java, directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 7.0.1 ou une version ultérieure de firebase-admin-java.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

Node.js

Si vous utilisez la bibliothèque cliente Cloud IAM pour Node.js directement ou en tant que dépendance d'une autre bibliothèque cliente :

Ajoutez la bibliothèque cliente Service Account Credentials pour Node.js à votre application. Utilisez la méthode signBlob() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Node.js, vous pouvez la supprimer de votre application.

Si vous utilisez la bibliothèque Google Auth pour Node.js directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 6.0.0 ou une version ultérieure de google-auth-library-nodejs.

Si vous utilisez le SDK Firebase Admin Node.js directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 8.13.0 ou une version ultérieure de firebase-admin-node.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

PHP

Si vous utilisez la bibliothèque cliente IAM pour PHP directement ou en tant que dépendance d'une autre bibliothèque cliente :

Ajoutez la bibliothèque cliente Service Account Credentials pour PHP à votre application. Utilisez la méthode signBlob() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour PHP, vous pouvez la supprimer de votre application.

Si vous utilisez la bibliothèque Google Auth pour PHP directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 1.5.0 ou une version ultérieure de google-auth-library-php.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

Python

Si vous utilisez la bibliothèque cliente IAM pour Python directement ou en tant que dépendance d'une autre bibliothèque cliente :

Ajoutez la bibliothèque cliente Service Account Credentials pour Python à votre application. Utilisez la méthode sign_blob() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente iam_credentials, vous pouvez la supprimer de votre application.

Si vous utilisez la bibliothèque Google Auth pour Python directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 1.21.2 ou une version ultérieure de google-auth-library-python.

Si vous utilisez le client Python pour Cloud Storage directement ou en tant que dépendance d'une autre bibliothèque cliente :

Effectuez une mise à niveau vers la version 1.30.0 ou une version ultérieure de python-storage.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

Ruby

Si vous utilisez la bibliothèque cliente Cloud IAM pour Ruby directement ou en tant que dépendance d'une autre bibliothèque cliente :

Ajoutez la bibliothèque cliente Service Account Credentials pour Ruby à votre application. Utilisez la méthode sign_service_account_blob() pour générer une signature.

Le nom du compte de service doit utiliser le caractère générique - pour représenter l'ID du projet :

Valide : nom avec caractère générique

projects/-/serviceAccounts/[e-mail]

Non valide : nom avec l'ID du projet

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

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Ruby, vous pouvez la supprimer de votre application.

Si vous utilisez une autre bibliothèque cliente pour signer des blobs :

Contactez [e-mail] pour obtenir de l'aide.

Migrer du code utilisant la CLI gcloud

Google Cloud CLI fournit des commandes qui utilisent l'API Cloud IAM pour signer des jetons JWT et des blobs binaires, y compris les suivants :

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

À compter du 1er juillet 2021, nous mettrons à jour ces commandes pour utiliser l'API Service Account Credentials. Cette modification n'affectera pas les commandes de signature d'objets blob.

Si vous utilisez la CLI gcloud pour signer des jetons JWT, vous devez suivre cette procédure avant le 1er juillet 2021 :

1. Vérifiez si la revendication de délai d'expiration (exp) est incluse dans l'ensemble de revendications JWT.

   Si vous incluez déjà cette revendication, vous n'avez pas de modifications à apporter. Vous pouvez ignorer les étapes restantes.

   Si vous n'incluez pas cette revendication, passez à l'étape suivante.

2. Vérifiez si vous utilisez le jeton JWT signé pour vous authentifier auprès des API Google ou d'une autre API nécessitant la revendication exp.

   Si vous omettez cette revendication, l'API Cloud IAM la définit automatiquement sur 1 heure dans le futur. En revanche, l'API Service Account Credentials ne définit pas ce champ automatiquement.

   Si vous êtes certain de ne pas avoir besoin de la revendication exp, vous n'avez pas de modifications à apporter. Vous pouvez ignorer les étapes restantes.

   Si vous avez besoin de la revendication exp ou si vous avez un doute, passez à l'étape suivante.

3. Mettez à jour votre code pour créer des jetons JWT afin d'ajouter la revendication exp à l'ensemble de revendications JWT.

   Vous pouvez définir la revendication exp jusqu'à 1 heure dans le futur.

Vérifier les quotas

Le quota de l'API Service Account Credentials est distinct de celui de l'API Cloud IAM. Si vous avez reçu une augmentation de quota pour signer des jetons JWT et des blobs avec l'API Cloud IAM, vous devrez peut-être en demander une également pour l'API Service Account Credentials.

Remarque : La plupart des clients Google Cloud utilisent le quota par défaut pour signer les jetons JWT et les blobs. Si vous utilisez le quota par défaut, vous pouvez ignorer cette section.

Pour afficher votre quota et votre utilisation réelle des deux API et pour demander une augmentation de quota si nécessaire, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page Quotas.

   Accéder à la page Quotas

2. Sélectionnez un projet. Vous pouvez cliquer sur un projet récent ou sur Sélectionner un projet pour effectuer une recherche dans tous vos projets.

3. Dans la zone de texte Filtrer le tableau au-dessus du tableau, saisissez Sign requests per minute, puis sélectionnez la valeur qui s'affiche.

4. Dans la zone de texte Filtrer le tableau, sélectionnez OU dans la liste déroulante.

5. Dans la zone de texte Filtrer le tableau, saisissez Generate credentials, puis sélectionnez la valeur qui s'affiche.

   La console Google Cloud affiche votre utilisation de la signature de jetons JWT et d'objets blob au cours de la dernière minute, votre pic d'utilisation par minute au cours des sept derniers jours et votre quota actuel, qui apparaît dans la colonne Limite.

6. Comparez les quotas pour chaque ligne du tableau et assurez-vous que votre quota pour l'API Service Account Credentials est supérieur à votre pic d'utilisation sur sept jours.

7. Facultatif : si votre quota pour l'API Service Account Credentials est trop faible, cochez la case correspondante, puis cliquez sur Modifier les quotas. Remplissez le formulaire pour demander une augmentation du quota.

8. Répétez ces étapes pour chaque projet dans lequel vous utilisez l'API Cloud IAM pour signer des jetons JWT et des objets blob.

Étape suivante

• Découvrez comment créer un jeton JWT signé ou créer un blob binaire signé avec l'API REST Service Account Credentials.
• Informez-vous en détail sur l'API REST pour l'API Service Account Credentials.
• Découvrez les quotas et les limites pour Cloud IAM.