Authentifizierung als Google Apps Script-Projekt mit Dienstkonten

In dieser Anleitung wird beschrieben, wie Sie sich mit einem Dienstkonto authentifizieren, wenn Sie APIs in Apps Script aufrufen.

Eine Übersicht über die Authentifizierung für Google Workspace APIs finden Sie unter Zugriffsanmeldedaten erstellen.

Wann sollten Dienstkonten in Apps Script verwendet werden?

Standardmäßig verwendet Apps Script die Anmeldedaten des Skriptnutzers, um APIs aufzurufen. Wenn Sie Google-APIs mit UrlFetchApp aufrufen, können Sie ein Zugriffstoken für den Scriptnutzer abrufen, indem Sie ScriptApp.getOAuthToken aufrufen.

Die Verwendung von Dienstkonten bietet jedoch in einigen Szenarien mehrere Vorteile gegenüber ScriptApp.getOAuthToken. Aus folgenden Gründen sollten Sie die Dienstkonto-Authentifizierung in Betracht ziehen:

• Bessere Leistung mit Google Cloud APIs und ‑Diensten: Viele Google Cloud APIs sind für die Dienstkontoauthentifizierung konzipiert. Dienstkonten können auch eine integriertere, zuverlässigere und sicherere Möglichkeit bieten, mit den meisten APIs zu interagieren.
• Entkoppelte Berechtigungen: Dienstkonten haben eigene Berechtigungen, die unabhängig von den Berechtigungen eines Nutzers sind. Die Authentifizierungsmethode ScriptApp.getOAuthToken kann fehlschlagen, wenn Sie das Projekt mit anderen Nutzern teilen. Mit Dienstkonten können Sie Skripts freigeben und als Google Workspace-Add-ons veröffentlichen.
• Automatisierte Skripts und zeitaufwendige Aufgaben: Mit Dienstkonten können Sie automatisierte Skripts, Batchprozesse oder Hintergrundaufgaben ohne Nutzereingabe ausführen.
• Erhöhte Sicherheit und Prinzip der geringsten Berechtigung: Gewähren Sie Dienstkonten bestimmte Berechtigungen, sodass sie nur auf die Ressourcen zugreifen können, die sie benötigen. Dies entspricht dem Prinzip der geringsten Berechtigung, wodurch Sicherheitsrisiken verringert werden. Wenn Sie ScriptApp.getOAuthToken verwenden, erhält ein Script oft alle Nutzerberechtigungen, was zu weit gefasst sein kann.
• Zentrale Zugriffsverwaltung: Dienstkonten werden über Identity and Access Management (IAM) von Google Cloud verwaltet. Mit IAM können Google Workspace-Organisationen den Zugriff auf authentifizierte Dienste in Apps Script-Projekten verwalten.

Vorbereitung

• Ein Google Cloud-Projekt
• Aktivieren Sie in Ihrem Cloud-Projekt alle APIs, für die Sie sich mit Dienstkontoanmeldedaten authentifizieren möchten.
• Um Dienstkonten Rollen zuzuweisen, benötigen Sie Super Admin-Berechtigungen.

Dienstkonto erstellen

Erstellen Sie in Ihrem Cloud-Projekt ein Dienstkonto:

Dienstkonto eine Rolle zuweisen

Sie müssen einem Dienstkonto über ein Super Admin-Konto eine vordefinierte oder benutzerdefinierte Rolle zuweisen.

1. Gehen Sie in der Admin-Konsole zu „Menü“ menu> Konto > Administratorrollen.

   Zu Administratorrollen

2. Bewegen Sie den Mauszeiger auf die Rolle, die Sie zuweisen möchten, und klicken Sie dann auf Administrator zuweisen.

3. Klicken Sie auf Dienstkonten zuweisen.

4. Geben Sie die E‑Mail-Adresse des Dienstkontos ein.

5. Klicken Sie auf Hinzufügen > Rolle zuweisen.

Anmeldedaten für ein Dienstkonto erstellen

So rufen Sie Anmeldedaten für Ihr Dienstkonto ab:

1. Rufen Sie in der Google Cloud Console das Menü menu > IAM & Verwaltung > Dienstkonten auf.

   Zur Seite „Dienstkonten“

2. Wählen Sie Ihr Dienstkonto aus.
3. Klicken Sie auf Schlüssel > Schlüssel hinzufügen > Neuen Schlüssel erstellen.
4. Wählen Sie JSON aus und klicken Sie auf Erstellen.

   Ihr neues öffentliches/privates Schlüsselpaar wird generiert und als neue Datei auf Ihren Computer heruntergeladen. Speichern Sie die heruntergeladene JSON-Datei als credentials.json in Ihrem Arbeitsverzeichnis. Diese Datei ist die einzige Kopie dieses Schlüssels. Informationen dazu, wie Sie den Schlüssel sicher speichern, finden Sie unter Dienstkontoschlüssel verwalten.

5. Klicken Sie auf Schließen.

Cloud-Projektnummer kopieren

1. Klicken Sie in der Google Cloud Console auf das Menü menu > IAM und Verwaltung > Einstellungen.

   Weiter zur Seite „IAM & Verwaltung“

2. Kopieren Sie den Wert aus dem Feld Projektnummer.

Dienstkonto-Authentifizierung in Ihrem Apps Script-Projekt einrichten

In diesem Abschnitt wird beschrieben, wie Sie die Dienstkontoanmeldedaten aus Ihrem Cloud-Projekt in ein Apps Script-Projekt einfügen.

Cloud-Projekt in Apps Script festlegen

1. So öffnen oder erstellen Sie ein Projekt in Apps Script:

   
   Apps Script öffnen

2. Klicken Sie in Ihrem Apps Script-Projekt auf Projekteinstellungen .

3. Klicken Sie unter Google Cloud-Projekt auf Projekt wechseln.

4. Fügen Sie die Cloud-Projektnummer in das Feld Google Cloud-Projektnummer ein.

5. Klicken Sie auf Projekt festlegen.

Anmeldedaten als Skripteigenschaft speichern

Speichern Sie die Anmeldedaten Ihres Dienstkontos sicher, indem Sie sie als Skripteigenschaft in den Einstellungen Ihres Apps Script-Projekts speichern:

1. Kopieren Sie den Inhalt der JSON-Datei des Dienstkontos (credentials.json), die Sie im vorherigen Abschnitt erstellt haben.
2. Rufen Sie in Ihrem Apps Script-Projekt die Projekteinstellungen settings auf.
3. Rufen Sie auf der Seite Projekteinstellungen die Skripteigenschaften auf, klicken Sie auf Skripteigenschaft hinzufügen und geben Sie Folgendes ein:
   • Geben Sie im Feld Property (Property) den Wert SERVICE_ACCOUNT_KEY ein.
   • Fügen Sie im Feld Wert den Inhalt Ihrer JSON-Schlüsseldatei ein.
4. Klicken Sie auf Skripteigenschaften speichern.

OAuth2-Bibliothek hinzufügen

Verwenden Sie die Apps Script-Bibliothek apps-script-oauth2, um den OAuth2-Authentifizierungsablauf zu verarbeiten.

So fügen Sie die Bibliothek Ihrem Apps Script-Projekt hinzu:

1. Klicken Sie im Apps Script-Editor links neben Bibliotheken auf Bibliothek hinzufügen add.
2. Geben Sie im Feld Script-ID den Wert 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF ein.
3. Klicken Sie auf Suchen.
4. Wählen Sie die aktuelle Version aus und klicken Sie auf Hinzufügen.

API mit Dienstkontoanmeldedaten aufrufen

Wenn Sie die Anmeldedaten des Dienstkontos aus Ihrem Apps Script-Projekt verwenden möchten, können Sie die folgende Funktion getServiceAccountService() verwenden:

/**
 * 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);
}

Ersetzen Sie SCOPE durch den Autorisierungsbereich, den Sie zum Aufrufen der API benötigen. Das Script verwendet die Dienstkonto-Anmeldedaten, die Sie im vorherigen Schritt als SERVICE_ACCOUNT_KEY-Scripteigenschaft gespeichert haben.

Sie können diese Anmeldedaten dann verwenden, um eine API aufzurufen, wie im folgenden Beispiel mit dem Dienst UrlFetch gezeigt:

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;
}

Ersetzen Sie API_URL durch den HTTP-Endpunkt, den Sie aufrufen.

Weitere Informationen

• Zugangsdaten erstellen
• Als Google Chat-App authentifizieren