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. Vous devez effectuer la migration vers l'API Service Account Credentials avant le 1er juillet 2021. Si vous utilisez l'outil de ligne de commande gcloud pour signer les jetons JWT, vous devrez peut-être ajouter une nouvelle revendication à l'ensemble de revendications JWT.

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 empêche de s'authentifier avec un jeton autosigné, puis d'obtenir un autre jeton autosigné. Par conséquent, si un pirate informatique obtient un jeton signé, il ne peut pas l'utiliser pour actualiser le jeton.

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 iam-sign-deprecation-public@google.com pour demander de l'aide et envoyer des commentaires détaillés.

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 section Tarifs de la suite des opérations Google Cloud.

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 1 heure 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Si vous n'utilisez plus la bibliothèque cliente Cloud IAM pour Python, 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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.

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 iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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

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

Contactez iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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

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

Contactez iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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 une autre bibliothèque cliente pour signer des blobs :

Contactez iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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 iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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 iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Si vous n'utilisez plus la bibliothèque cliente IAM pour Python, 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 iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

Non valide : nom avec l'ID du projet

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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 iam-sign-deprecation-public@google.com pour obtenir de l'aide.

Migrer du code utilisant l'outil gcloud

L'outil de ligne de commande gcloud fournit des commandes qui utilisent l'API Cloud IAM pour signer des jetons JWT et des blobs binaires, y compris :

À 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 l'outil 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.

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 Cloud Console, 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.

    Cloud Console 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.

Étapes suivantes