S'authentifier en tant que projet Apps Script à l'aide de comptes de service

Ce guide explique comment s'authentifier avec un compte de service lorsque vous appelez des API dans Apps Script.

Un compte de service est un type de compte spécial utilisé par une application, et non par une personne. Vous pouvez utiliser un compte de service pour accéder aux données ou effectuer des actions par le compte robot, ou pour accéder aux données au nom des utilisateurs Google Workspace ou Cloud Identity. Pour en savoir plus, consultez la page Comprendre les comptes de service.

Pour obtenir une présentation de l'authentification pour les API Google Workspace, consultez Créer des identifiants d'accès.

Quand utiliser des comptes de service dans Apps Script

Voici quelques raisons pour lesquelles vous pouvez envisager d'utiliser l'authentification par compte de service au lieu d'autres méthodes d'authentification telles que ScriptApp.getOAuthToken() :

• Amélioration des performances avec les API et services Google Cloud : de nombreuses API Google Cloud sont conçues pour l'authentification par compte de service. Les comptes de service peuvent également fournir un moyen plus intégré, fiable et sécurisé d'interagir avec la plupart des API.
• Autorisations dissociées : les comptes de service disposent de leurs propres autorisations, distinctes de celles des utilisateurs. La méthode d'authentification ScriptApp.getOAuthToken() peut échouer lorsque vous partagez le projet Apps Script avec d'autres utilisateurs. En utilisant des comptes de service, vous pouvez partager des scripts et les publier en tant que modules complémentaires Google Workspace.
• Scripts automatisés et tâches de longue durée : les comptes de service vous permettent d'exécuter des scripts automatisés, des processus par lot ou des tâches en arrière-plan sans intervention de l'utilisateur.
• Sécurité renforcée et principe du moindre privilège : vous pouvez accorder des autorisations spécifiques aux comptes de service, en leur donnant accès uniquement aux ressources dont ils ont besoin. Cela suit le principe du moindre privilège, qui réduit les risques de sécurité. L'utilisation de ScriptApp.getOAuthToken() accorde souvent à un script toutes les autorisations utilisateur, ce qui peut être trop large.
• Gestion centralisée des accès : les comptes de service sont gérés à l'aide d'Identity and Access Management (IAM) de Google Cloud. IAM peut aider les organisations Google Workspace à gérer l'accès aux services authentifiés dans les projets Apps Script.

Prérequis

• un projet Google Cloud ;
• Dans votre projet Cloud, activez les API avec lesquelles vous souhaitez vous authentifier à l'aide des identifiants du compte de service.
• Pour attribuer des rôles à des comptes de service, vous devez disposer des droits super-administrateur.

Créer un compte de service

Dans votre projet Cloud, créez un compte de service :

Console Google Cloud

1. Dans la console Google Cloud, accédez au menu  > IAM et administration > Comptes de service.

   Accéder à la page "Comptes de service"

2. Cliquez sur Créer un compte de service.
3. Renseignez les informations du compte de service, puis cliquez sur Créer et continuer.
   Remarque : Par défaut, Google crée un ID de compte de service unique. Si vous souhaitez modifier l'ID, modifiez-le dans le champ "ID du compte de service".
4. Facultatif : Attribuez des rôles à votre compte de service pour lui accorder l'accès aux ressources de votre projet Google Cloud. Pour en savoir plus, consultez Accorder, modifier et révoquer les accès à des ressources.
5. Cliquez sur Continuer.
6. Facultatif : Saisissez les utilisateurs ou les groupes qui peuvent gérer ce compte de service et effectuer des actions avec. Pour en savoir plus, consultez Gérer l'emprunt d'identité d'un compte de service.
7. Cliquez sur OK. Notez l'adresse e-mail du compte de service.

CLI gcloud

1. Créez le compte de service :

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Facultatif : Attribuez des rôles à votre compte de service pour lui accorder l'accès aux ressources de votre projet Google Cloud. Pour en savoir plus, consultez Accorder, modifier et révoquer les accès à des ressources.

Attribuer un rôle au compte de service

Vous devez attribuer un rôle prédéfini ou personnalisé à un compte de service à l'aide d'un compte super-administrateur.

1. Dans la console d'administration Google, accédez à Menu > Compte > Rôles d'administrateur.

   Accéder à "Rôles d'administrateur"

2. Pointez sur le rôle que vous souhaitez attribuer, puis cliquez sur Attribuer un rôle Administrateur.

3. Cliquez sur Attribuer des comptes de service.

4. Saisissez l'adresse e-mail du compte de service.

5. Cliquez sur Ajouter > Attribuer un rôle.

Créer des identifiants pour un compte de service

Vous devez obtenir des identifiants sous la forme d'une paire de clés publique/privée. Ces identifiants sont utilisés par votre code pour autoriser les actions du compte de service dans votre application.

Pour obtenir les identifiants de votre compte de service :

1. Dans la console Google Cloud, accédez au menu  > IAM et administration > Comptes de service.

   Accéder à la page "Comptes de service"

2. Sélectionnez votre compte de service.
3. Cliquez sur Clés > Ajouter une clé > Créer une clé.
4. Sélectionnez JSON, puis cliquez sur Créer.

   La nouvelle paire de clés publique/privée est générée et téléchargée sur votre ordinateur sous la forme d'un nouveau fichier. Enregistrez le fichier JSON téléchargé sous le nom credentials.json dans votre répertoire de travail. Ce fichier est la seule copie de cette clé. Pour savoir comment stocker votre clé de manière sécurisée, consultez Gérer les clés de compte de service.

5. Cliquez sur Fermer.

Copier le numéro du projet Cloud

1. Dans la console Google Cloud, accédez à Menu  > IAM et administration > Paramètres.

   Accéder à la page Paramètres de la section IAM et administration

2. Dans le champ Numéro du projet, copiez la valeur.

Configurer l'authentification par compte de service dans votre projet Apps Script

Cette section explique comment ajouter les identifiants de votre compte de service depuis votre projet Cloud à un projet Apps Script.

Définir votre projet Cloud dans Apps Script

1. Accédez à Apps Script pour ouvrir ou créer un projet :

   
   Ouvrir Apps Script

2. Dans votre projet Apps Script, cliquez sur Paramètres du projet .

3. Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.

4. Dans Numéro de projet GCP, collez le numéro du projet Google Cloud.

5. Cliquez sur Définir un projet.

Enregistrer les identifiants en tant que propriété de script

Stockez de manière sécurisée les identifiants de votre compte de service en les enregistrant en tant que propriété de script dans les paramètres de votre projet Apps Script :

1. Copiez le contenu du fichier JSON de votre compte de service (credentials.json) que vous avez créé dans la section précédente.
2. Dans votre projet Apps Script, accédez à Paramètres du projet .
3. Sur la page Paramètres du projet, accédez à Propriétés du script, cliquez sur Ajouter une propriété de script, puis saisissez les informations suivantes :
   • Dans le champ Propriété, saisissez SERVICE_ACCOUNT_KEY.
   • Dans le champ Valeur, collez le contenu de votre fichier de clé JSON.
4. Cliquez sur Enregistrer les propriétés du script.

Ajouter la bibliothèque OAuth2

Pour gérer le flux d'authentification OAuth2, vous pouvez utiliser la bibliothèque Apps Script apps-script-oauth2.

Pour ajouter la bibliothèque à votre projet Apps Script :

1. Dans l'éditeur Apps Script, à gauche, à côté de Bibliothèques, cliquez sur Ajouter une bibliothèque .
2. Dans le champ ID du script, saisissez 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Cliquez sur Rechercher.
4. Sélectionnez la dernière version, puis cliquez sur Ajouter.

Appeler une API à l'aide d'identifiants de compte de service

Pour utiliser les identifiants du compte de service de votre projet Apps Script, vous pouvez utiliser la fonction getServiceAccountService() suivante :

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

Remplacez SCOPE par le champ d'application de l'autorisation dont vous avez besoin pour appeler l'API. Le script utilise les identifiants du compte de service que vous avez enregistrés en tant que propriété de script SERVICE_ACCOUNT_KEY à l'étape précédente.

Vous pouvez ensuite utiliser ces identifiants pour appeler une API, comme illustré dans l'exemple suivant avec le service UrlFetch :

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

Remplacez API_URL par le point de terminaison HTTP que vous appelez.

Articles associés

• Créer des identifiants d'accès
• S'authentifier en tant qu'application Google Chat