Detaillierte Berechtigungen

Übersicht

Mit detaillierten Berechtigungen erhalten Nutzer mehr Kontrolle darüber, welche Kontodaten sie mit den einzelnen Apps teilen möchten. Sie bieten sowohl Nutzern als auch Entwicklern mehr Kontrolle, Transparenz und Sicherheit. In diesem Leitfaden werden die erforderlichen Änderungen und Schritte erläutert, die Sie ausführen müssen, um Ihre Anwendungen so zu aktualisieren, dass sie detaillierte Berechtigungen verarbeiten können.

Was ist eine detaillierte Berechtigung?

Angenommen, Sie entwickeln eine Produktivitäts-App, die sowohl E-Mail- als auch Kalenderbereiche anfordert. Ihre Nutzer möchten Ihre Anwendung möglicherweise nur für Google Kalender, aber nicht für Gmail verwenden. Mit detaillierten OAuth-Berechtigungen können Nutzer beispielsweise nur die Berechtigung für Google Kalender, aber nicht für Gmail erteilen. Wenn Nutzer den Zugriff auf bestimmte Daten gewähren, wird die Offenlegung von Daten minimiert, das Vertrauen gestärkt und Nutzern die datenschutzorientierte Kontrolle über ihr digitales Leben ermöglicht. Es ist wichtig, Ihre Anwendung so zu entwerfen, dass sie solche Szenarien verarbeiten kann.

Wenn mehr als ein Bereich angefordert wird, der nicht zur Anmeldung gehört

Anmelde- und Nicht-Anmeldebereiche

Bei Anwendungen, die sowohl Anmelde- als auch Nicht-Anmeldebereiche anfordern, sehen Nutzer zuerst die Einwilligungsseite für Anmeldebereiche (email, profile und openid). Nachdem Nutzer der Weitergabe ihrer grundlegenden Identitätsinformationen (Name, E-Mail-Adresse und Profilbild) zugestimmt haben, wird ihnen ein Bildschirm mit detaillierten Berechtigungen für die Nicht-Anmeldebereiche angezeigt. In diesem Fall muss die Anwendung prüfen, welche Bereiche von den Nutzern gewährt werden. Sie kann nicht davon ausgehen, dass Nutzer alle angeforderten Bereiche gewähren. Im folgenden Beispiel fordert die Webanwendung alle drei Log-in-Bereiche und einen Google Drive-Bereich an, der nicht für die Anmeldung verwendet wird. Nachdem Nutzer den Anmeldebereichen zugestimmt haben, wird ihnen der Zustimmungsbildschirm für die detaillierten Berechtigungen für die Google Drive-Berechtigung angezeigt:

Mehr als ein Bereich, der nicht für die Anmeldung bestimmt ist

Ein detaillierter Zustimmungsbildschirm für Berechtigungen wird Nutzern angezeigt, wenn Anwendungen mehr als einen Bereich anfordern, der nicht zur Anmeldung gehört. Nutzer können auswählen, welche Berechtigungen sie für die Freigabe für die Anwendung genehmigen möchten. Im Folgenden finden Sie ein Beispiel für einen Zustimmungsbildschirm für detaillierte Berechtigungen, auf dem Zugriff auf die Gmail-Nachrichten und Google Kalender-Daten des Nutzers angefordert wird:

Für Anwendungen, die nur Anmeldebereiche (email, profile und openid) anfordern, ist der Zustimmungsbildschirm für detaillierte Berechtigungen nicht relevant. Nutzer genehmigen oder lehnen die gesamte Anmeldeanfrage ab. Mit anderen Worten: Wenn Anwendungen nur Anmelde-Zugriffsbereiche (einen, zwei oder alle drei) anfordern, ist der Zustimmungsbildschirm für detaillierte Berechtigungen nicht zutreffend.

Bei Anwendungen, die nur einen Bereich anfordern, der nicht zur Anmeldung dient, ist der Einwilligungsbildschirm für detaillierte Berechtigungen nicht anwendbar. Nutzer können die gesamte Anfrage also entweder genehmigen oder ablehnen. Auf dem Zustimmungsbildschirm gibt es kein Kästchen. In der folgenden Tabelle wird zusammengefasst, wann der Zustimmungsbildschirm für detaillierte Berechtigungen angezeigt wird.

Prüfen, ob Ihre Anwendungen betroffen sind

Prüfen Sie alle Bereiche Ihrer Anwendung, in denen Google OAuth 2.0-Autorisierungsendpunkte für Berechtigungsanfragen verwendet werden. Achten Sie auf diejenigen, die mehrere Bereiche anfordern, da sie detaillierte Zustimmungsbildschirme für Berechtigungen aktivieren, die Nutzern angezeigt werden. In solchen Fällen muss Ihr Code den Fall verarbeiten können, dass Nutzer nur einige der Bereiche autorisieren.

So ermitteln Sie, ob Ihre Anwendung mehrere Bereiche verwendet

Prüfen Sie Ihren App-Code oder den ausgehenden Netzwerkaufruf, um festzustellen, ob die von Ihrer App gestellten Google OAuth 2.0-Autorisierungsanfragen dazu führen, dass der Zustimmungsbildschirm für detaillierte Berechtigungen angezeigt wird.

Anwendungscode prüfen

Überprüfen Sie die Abschnitte Ihres Anwendungscodes, in denen Sie die Google OAuth-Autorisierungsendpunkte aufrufen, um die Berechtigung von Nutzern anzufordern. Wenn Sie eine der Google API-Clientbibliotheken verwenden, finden Sie die von Ihrer Anwendung angeforderten Bereiche häufig in den Schritten zur Clientinitialisierung. Im folgenden Abschnitt finden Sie einige Beispiele. In der Dokumentation der SDKs, die Ihre Anwendung für die Verarbeitung von Google OAuth 2.0 verwendet, können Sie nachsehen, ob Ihre Anwendung betroffen ist. Die folgenden Beispiele dienen als Referenz.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
  https://www.googleapis.com/auth/contacts.readonly',
  callback: (response) => {
    ...
  },
});

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are
# required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=[
        'https://www.googleapis.com/auth/calendar.readonly',
        'https://www.googleapis.com/auth/contacts.readonly'
    ])

const {google} = require('googleapis');

/**
  * To use OAuth2 authentication, we need access to a CLIENT_ID,
  * CLIENT_SECRET, AND REDIRECT_URI from the client_secret.json file. To get
  * these credentials for your application, visit
  * https://console.cloud.google.com/apis/credentials.
  */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Calendar and Contacts.
const scopes = [
  'https://www.googleapis.com/auth/calendar.readonly',
  'https://www.googleapis.com/auth/contacts.readonly']
];

// Generate a url that asks permissions
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined earlier.
    * Alternatively, if only one scope is needed, you can pass a scope URL
    * as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as best practices.
  include_granted_scopes: true
});

Ausgehenden Netzwerkaufruf prüfen

Die Methode zum Prüfen von Netzwerkaufrufen hängt vom Anwendungstyp ab.

• Webanwendung – Netzwerkaktivität in Chrome prüfen
• Android – Netzwerkverkehr mit dem Netzwerk-Inspector prüfen
• Chrome-Apps
  • Rufen Sie die Seite mit den Chrome-Erweiterungen auf.
  • Klicken Sie rechts oben auf der Seite „Erweiterungen“ das Kästchen Entwicklermodus an.
  • Wählen Sie die Erweiterung aus, die Sie beobachten möchten.
  • Klicken Sie auf der Seite der Erweiterung im Bereich Ansichten prüfen auf den Link Hintergrundseite.
  • Das Dialogfeld Entwicklertools wird geöffnet. Dort können Sie den Netzwerkverkehr auf dem Tab Netzwerk beobachten.
• iOS – HTTP-Traffic mit Instruments analysieren
• Desktop-Apps: Verwenden Sie ein Tool zur Netzwerkerfassung, das für das Betriebssystem verfügbar ist, für das die App entwickelt wurde.

Suchen Sie beim Prüfen von Netzwerkaufrufen nach Anfragen, die an die Google OAuth-Autorisierungsendpunkte gesendet werden, und prüfen Sie den Parameter scope.

Diese Werte führen dazu, dass der Zustimmungsbildschirm für detaillierte Berechtigungen angezeigt wird.

• Der Parameter scope enthält Bereiche für die Anmeldung und Bereiche, die nicht für die Anmeldung vorgesehen sind.

  Die folgende Beispielanfrage enthält alle drei Log-in-Bereiche und einen Bereich, der nicht für die Anmeldung vorgesehen ist, um die Metadaten der Google Drive-Dateien des Nutzers aufzurufen:

  https://accounts.google.com/o/oauth2/v2/auth?
  access_type=offline&
  scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20openid%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly&
  include_granted_scopes=true&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URL&
  client_id=YOUR_CLIENT_ID

• Der Parameter scope enthält mehr als einen Bereich, der nicht für die Anmeldung vorgesehen ist.

  Die folgende Beispielanfrage enthält zwei Bereiche, die nicht zur Anmeldung gehören, um die Google Drive-Metadaten des Nutzers aufzurufen und bestimmte Google Drive-Dateien zu verwalten:

  https://accounts.google.com/o/oauth2/v2/auth?
  access_type=offline&
  scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file&
  include_granted_scopes=true&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URL&
  client_id=YOUR_CLIENT_ID

Best Practices für den Umgang mit detaillierten Berechtigungen

Wenn Sie feststellen, dass Ihre Anwendung aktualisiert werden muss, um detaillierte Berechtigungen zu verarbeiten, sollten Sie die erforderlichen Aktualisierungen an Ihrem Code vornehmen, um die Einwilligung für mehrere Bereiche ordnungsgemäß zu verarbeiten. Alle Anwendungen sollten den folgenden Best Practices entsprechen:

1. Lesen Sie sich die Richtlinie zu Nutzerdaten für Google API-Dienste durch und achten Sie darauf, dass Sie sie einhalten.
2. Fordern Sie bestimmte Bereiche an, die für eine Aufgabe erforderlich sind. Sie müssen die Google OAuth 2.0-Richtlinie einhalten, nach der Sie nur die Bereiche anfordern dürfen, die Sie benötigen. Sie sollten vermeiden, bei der Anmeldung mehrere Bereiche anzufordern, es sei denn, dies ist für die Hauptfunktion Ihrer App erforderlich. Wenn Sie mehrere Bereiche bündeln, kann es für Nutzer, die mit den Funktionen Ihrer Anwendung nicht vertraut sind, schwierig sein, die Notwendigkeit dieser Berechtigungen zu verstehen. Dies kann zu Warnungen führen und Nutzer davon abhalten, Ihre Anwendung weiter zu verwenden.
3. Begründe die Anfrage gegenüber den Nutzern, bevor du sie stellst. Erklären Sie genau, warum Ihre Anwendung die angeforderte Berechtigung benötigt, was Sie mit den Daten des Nutzers tun und wie der Nutzer von der Genehmigung der Anfrage profitiert. Unsere Untersuchungen zeigen, dass diese Erklärungen das Vertrauen und die Interaktion der Nutzer erhöhen.
4. Verwenden Sie die inkrementelle Autorisierung, wenn Ihre Anwendung Bereiche anfordert, um die Verwaltung mehrerer Zugriffstokens zu vermeiden.
5. Prüfen Sie, welche Bereiche Nutzer gewährt haben. Wenn Sie mehrere Bereiche gleichzeitig anfordern, gewähren Nutzer möglicherweise nicht alle von Ihrer App angeforderten Bereiche. Ihre App sollte immer prüfen, welche Bereiche vom Nutzer gewährt wurden, und alle Ablehnungen von Bereichen durch Deaktivieren der entsprechenden Funktionen verarbeiten. Beachten Sie die Google OAuth 2.0-Richtlinien zum Umgang mit Einwilligungen für mehrere Bereiche und fordern Sie den Nutzer erst dann wieder zur Einwilligung auf, wenn er eindeutig die Absicht bekundet hat, die spezifische Funktion zu verwenden, für die der Bereich erforderlich ist.

Anwendung aktualisieren, um detaillierte Berechtigungen zu verarbeiten

Android-Apps

Lesen Sie die Dokumentation der SDKs, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung, um detaillierte Berechtigungen gemäß den Best Practices zu verarbeiten.

Wenn Sie das SDK auth.api.signin von Google Play-Diensten verwenden, um mit Google OAuth 2.0 zu interagieren, können Sie die Funktion requestPermissions verwenden, um die kleinstmögliche Anzahl von Bereichen anzufordern, und die Funktion hasPermissions, um zu prüfen, welche Bereiche der Nutzer beim Anfordern detaillierter Berechtigungen gewährt hat.

Chrome-Erweiterungen

Sie sollten die Chrome Identity API verwenden, um mit Google OAuth 2.0 gemäß den Best Practices zu arbeiten.

Das folgende Beispiel zeigt, wie Sie detaillierte Berechtigungen richtig verarbeiten.

manifest.json

In der Beispiel-Manifestdatei werden zwei Bereiche für die Chrome-Erweiterung deklariert, die nicht für die Anmeldung verwendet werden.

{
  "name": "Example Chrome extension application",
  ...
  "permissions": [
      "identity"
    ],
  "oauth2" : {
      "client_id": "YOUR_CLIENT_ID",
      "scopes":[
        "https://www.googleapis.com/auth/calendar.readonly",
        "https://www.googleapis.com/auth/contacts.readonly"
      ]
  }
}

Falscher Ansatz

...
document.querySelector('button').addEventListener('click', function () {
  chrome.identity.getAuthToken({ interactive: true },
      function (token) {
          if (token === undefined) {
            // User didn't authorize both scopes.
            // Updating the UX and application accordingly
            ...
          } else {
            // User authorized both or one of the scopes.
            // It neglects to check which scopes users granted and assumes
            // users granted all scopes.

            // Calling the APIs, etc.
            ...
          }
      });
});

Richtiger Ansatz

...
document.querySelector('button').addEventListener('click', function () {
  chrome.identity.getAuthToken(
      { interactive: true, enableGranularPermissions: true },
      function (token, grantedScopes) {
          if (token === undefined) {
            // User didn't authorize any scope.
            // Updating the UX and application accordingly
            ...
          } else {
            // User authorized the request. Now, check which scopes were
            // granted.
            if (grantedScopes.includes(
                'https://www.googleapis.com/auth/calendar.readonly'))
            {
              // User authorized Calendar read permission.
              // Calling the APIs, etc.
              ...
            }
            else
            {
              // User didn't authorize Calendar read permission.
              // Update UX and application accordingly
              ...
            }

            if (grantedScopes.includes(
                'https://www.googleapis.com/auth/contacts.readonly'))
            {
              // User authorized Contacts read permission.
              // Calling the APIs, etc.
              ...
            }
            else
            {
              // User didn't authorize Contacts read permission.
              // Update UX and application accordingly
              ...
            }
          }
      });
});

iOS-, iPadOS- und macOS-Anwendungen

Lesen Sie die Dokumentation der SDKs, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung, um detaillierte Berechtigungen gemäß den Best Practices zu verarbeiten.

Wenn Sie die Bibliothek Google Log-in für iOS und macOS verwenden, um mit Google OAuth 2.0 zu interagieren, sollten Sie die Dokumentation zum Umgang mit detaillierten Berechtigungen lesen.

Webanwendungen

Lesen Sie die Dokumentation der SDKs, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung, um detaillierte Berechtigungen gemäß den Best Practices zu verarbeiten.

Serverseitiger (Offline-)Zugriff

Für den serverseitigen (Offline-)Zugriffsmodus müssen Sie Folgendes tun:

• Richten Sie einen Server ein und definieren Sie einen öffentlich zugänglichen Endpunkt, um den Autorisierungscode zu empfangen.
• Konfigurieren Sie den Weiterleitungs-URI Ihres öffentlichen Endpunkts auf der Seite „Clients“ der Google Cloud Console.

Das folgende Code-Snippet zeigt ein NodeJS-Beispiel, in dem zwei Bereiche angefordert werden, die nicht zur Anmeldung gehören. Nutzern wird der Bildschirm für die detaillierte Einwilligung angezeigt.

Falscher Ansatz

...
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes - Google Calendar and Contacts
const scopes = [
  'https://www.googleapis.com/auth/contacts.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a url that asks permissions for the Google Calendar and Contacts
// scopes
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  // Pass in the scopes array defined earlier
  scope: scopes,
  // Enable incremental authorization. Recommended as best practices.
  include_granted_scopes: true
});

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization server response
      let q = url.parse(req.url, true).query;

      if (q.error) {
        // User didn't authorize both scopes.
        // Updating the UX and application accordingly
        ...
      } else {
        // User authorized both or one of the scopes.
        // It neglects to check which scopes users granted and assumes users
        // granted all scopes.

        // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        // Calling the APIs, etc.
        ...
      }
    }
    res.end();
  }).listen(80);
}

Richtiger Ansatz

...
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes - Google Calendar and Contacts
const scopes = [
  'https://www.googleapis.com/auth/contacts.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a url that asks permissions for the Google Calendar and Contacts
// scopes
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  // Pass in the scopes array defined earlier
  scope: scopes,
  // Enable incremental authorization. Recommended as best practices.
  include_granted_scopes: true,
  // Set to true to enable more granular permissions for Google OAuth 2.0
  // client IDs created before 2019. No effect for newer Google OAuth 2.0
  // client IDs, since more granular permissions is always enabled for them.
  enable_granular_consent: true
});

async function main() {
  const server = http.createServer(async function (req, res) {
    // Redirect users to the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization server response
      let q = url.parse(req.url, true).query;

      if (q.error) {
        // User didn't authorize both scopes.
        // Updating the UX and application accordingly
        ...
      } else {
        // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        // User authorized the request. Now, check which scopes were
        // granted.
        if (tokens.scope.includes(
            'https://www.googleapis.com/auth/calendar.readonly'))
        {
          // User authorized Calendar read permission.
          // Calling the APIs, etc.
          ...
        }
        else
        {
          // User didn't authorize Calendar read permission.
          // Calling the APIs, etc.
          ...
        }

        // Check which scopes user granted the permission to application
        if (tokens.scope.includes(
            'https://www.googleapis.com/auth/contacts.readonly'))
        {
          // User authorized Contacts read permission.
          // Calling the APIs, etc.
          ...
        }
        else
        {
          // User didn't authorize Contacts read permission.
          // Update UX and application accordingly
          ...
        }
      }
    }
    res.end();
  }).listen(80);
}

Informationen zum Zugriff auf Google APIs über serverbasierte Anwendungen finden Sie im Leitfaden für serverseitige Webanwendungen.

Nur clientseitiger Zugriff

• Für Anwendungen, die die JavaScript-Bibliothek Google Identity Services für die Interaktion mit Google OAuth 2.0 verwenden, sollten Sie sich diese Dokumentation zum Umgang mit detaillierten Berechtigungen ansehen.
• Wenn Sie Anwendungen haben, die mit JavaScript direkt Aufrufe an Google OAuth 2.0-Autorisierungsendpunkte senden, sollten Sie sich diese Dokumentation zum Umgang mit detaillierten Berechtigungen ansehen.

Aktualisierte App auf die Verarbeitung detaillierter Berechtigungen testen

1. Beschreibe alle Fälle, in denen Nutzer auf Berechtigungsanfragen reagieren können, und das erwartete Verhalten deiner App. Wenn der Nutzer beispielsweise nur zwei von drei angeforderten Bereichen autorisiert, sollte sich Ihre Anwendung entsprechend verhalten.

2. Testen Sie Ihre Anwendung mit aktivierter detaillierter Berechtigung. Es gibt zwei Möglichkeiten, detaillierte Berechtigungen zu aktivieren:

   1. Prüfen Sie auf den OAuth 2.0-Zustimmungsbildschirmen Ihrer Anwendung, ob differenzierte Berechtigungen bereits für Ihre Anwendung aktiviert sind. Sie können zu Testzwecken auch eine neue Google OAuth 2.0-Client-ID für Web, Android oder iOS über die Google Cloud Console erstellen, da für diese immer die detaillierte Berechtigung aktiviert ist.

   2. Setzen Sie beim Aufrufen der Autorisierungsendpunkte von Google OAuth den Parameter enable_granular_consent auf true. Einige SDKs unterstützen diesen Parameter explizit. Bei anderen finden Sie in der Dokumentation Informationen dazu, wie Sie diesen Parameter und seinen Wert manuell hinzufügen können. Wenn Ihre Implementierung das Hinzufügen des Parameters nicht unterstützt, können Sie wie im vorherigen Punkt beschrieben eine neue Google OAuth 2.0-Client-ID für Web, Android oder iOS über die Google Cloud Console erstellen, die nur zu Testzwecken dient.

3. Verwenden Sie zum Testen Ihrer aktualisierten Anwendung ein privates Google-Konto (@gmail.com) anstelle eines Workspace-Kontos. Das liegt daran, dass Workspace Enterprise-Anwendungen mit domainweiter Delegation von Berechtigungen oder als Vertrauenswürdig gekennzeichnete Anwendungen derzeit nicht von den Änderungen an den detaillierten Berechtigungen betroffen sind. Daher wird der neue detaillierte Zustimmungsbildschirm beim Testen mit einem Workspace-Konto Ihrer Organisation möglicherweise nicht wie vorgesehen angezeigt.