Als Apps Script-Projekt mit Dienstkonten authentifizieren

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

Ein Dienstkonto ist eine spezielle Art von Konto, das von einer Anwendung und nicht von einer Person verwendet wird. Sie können ein Dienstkonto verwenden, um über das Roboter-Konto auf Daten zuzugreifen oder Aktionen auszuführen oder um im Namen von Google Workspace- oder Cloud Identity-Nutzern auf Daten zuzugreifen. Weitere Informationen finden Sie unter Details zu Dienstkonten.

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

Wann sollten Dienstkonten in Apps Script verwendet werden?

Hier sind einige Gründe, warum Sie die Dienstkontoauthentifizierung anstelle anderer Authentifizierungsmethoden wie ScriptApp.getOAuthToken() verwenden sollten:

• 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 von denen der Nutzer getrennt sind. Die Authentifizierungsmethode ScriptApp.getOAuthToken() kann fehlschlagen, wenn Sie das Apps Script-Projekt für andere Nutzer freigeben. Mit Dienstkonten können Sie Skripts freigeben und als Google Workspace-Add-ons veröffentlichen.
• Automatisierte Skripts und lang andauernde Aufgaben: Mit Dienstkonten können Sie automatisierte Skripts, Batchprozesse oder Hintergrundaufgaben ohne Nutzereingabe ausführen.
• Erhöhte Sicherheit und Prinzip der geringsten Berechtigung: Sie können Dienstkonten bestimmte Berechtigungen erteilen und so nur Zugriff auf die Ressourcen gewähren, die sie benötigen. Dies entspricht dem Prinzip der geringsten Berechtigung, wodurch Sicherheitsrisiken verringert werden. Wenn Sie ScriptApp.getOAuthToken() verwenden, werden einem Script oft alle Nutzerberechtigungen gewährt, was zu weit gefasst sein kann.
• Zentrale Zugriffsverwaltung: Dienstkonten werden über die Identitäts- und Zugriffsverwaltung (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:

Google Cloud Console

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

   Zur Seite „Dienstkonten“

2. Klicken Sie auf Dienstkonto erstellen.
3. Geben Sie die Dienstkontodetails ein und klicken Sie dann auf Erstellen und fortfahren.
   Hinweis: Standardmäßig erstellt Google eine eindeutige Dienstkonto-ID. Wenn Sie die ID ändern möchten, bearbeiten Sie sie im Feld „Dienstkonto-ID“.
4. Optional: Weisen Sie Ihrem Dienstkonto Rollen zu, um Zugriff auf die Ressourcen Ihres Google Cloud-Projekts zu gewähren. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.
5. Klicken Sie auf Weiter.
6. Optional: Geben Sie Nutzer oder Gruppen ein, die dieses Dienstkonto verwalten und Aktionen damit ausführen können. Weitere Informationen finden Sie unter Identitätswechsel von Dienstkonten verwalten.
7. Klicken Sie auf Fertig. Notieren Sie sich die E-Mail-Adresse des Dienstkontos.

gcloud-CLI

1. Erstellen Sie das Dienstkonto:

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

2. Optional: Weisen Sie Ihrem Dienstkonto Rollen zu, um Zugriff auf die Ressourcen Ihres Google Cloud-Projekts zu gewähren. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.

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 zum Menü > 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

Sie benötigen Anmeldedaten in Form eines Paars aus öffentlichem und privatem Schlüssel. Diese Anmeldedaten werden von Ihrem Code verwendet, um Dienstkontoaktionen in Ihrer App zu autorisieren.

So rufen Sie Anmeldedaten für Ihr Dienstkonto ab:

1. Rufen Sie in der Google Cloud Console das Menü  > 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ü  > 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 Platform-Projekt (GCP) auf Projekt wechseln.

4. Fügen Sie die Google Cloud-Projektnummer in das Feld GCP-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 Ihres Dienstkontos (credentials.json), die Sie im vorherigen Abschnitt erstellt haben.
2. Rufen Sie in Ihrem Apps Script-Projekt die Projekteinstellungen 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

Für den OAuth2-Authentifizierungsablauf können Sie die Apps Script-Bibliothek apps-script-oauth2 verwenden.

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 .
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 Dienstkontoanmeldedaten, 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