Detaillierte Berechtigungen

Überblick

Mit detaillierten Berechtigungen können Nutzer genauer steuern, welche Kontodaten sie für jede App freigeben. Von diesen Daten profitieren sowohl Nutzer als auch Entwickler, da sie mehr Kontrolle, Transparenz und Sicherheit bieten. In diesem Leitfaden werden die Änderungen und Schritte beschrieben, die erforderlich sind, um Ihre Anwendungen erfolgreich so zu aktualisieren, dass sie detaillierte Berechtigungen verarbeiten können.

Was ist eine detaillierte Berechtigung?

Stellen Sie sich vor, Sie entwickeln eine Produktivitäts-App, die sowohl E-Mail- als auch Kalenderbereiche anfordert. Möglicherweise möchten Ihre Nutzer Ihre Anwendung nur für Google Kalender, aber nicht für Gmail verwenden. Mit detaillierten OAuth-Berechtigungen können Nutzer festlegen, dass sie nur Google Kalender-Berechtigungen, aber nicht Gmail-Berechtigungen erteilen möchten. Indem Nutzer Zugriff auf bestimmte Daten gewähren können, wird die Offenlegung von Daten minimiert, das Vertrauen gestärkt und Nutzer haben eine datenschutzorientierte Kontrolle über ihr digitales Leben. Es ist wichtig, dass Sie Ihre Anwendung für solche Szenarien entwickeln.

Wenn mehrere Bereiche ohne Anmeldung angefordert werden

Anmelde- und Nicht-Anmeldungsbereiche

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 Freigabe ihrer grundlegenden Identitätsinformationen (Name, E-Mail-Adresse und Profilbild) zugestimmt haben, sehen Nutzer einen detaillierten Zustimmungsbildschirm für die Zustimmung zu Berechtigungen für die Bereiche ohne Anmeldung. In diesem Fall muss die Anwendung prüfen, welche Bereiche von den Nutzern gewährt werden, und darf nicht davon ausgehen, dass Nutzer alle angeforderten Bereiche gewähren. Im folgenden Beispiel fordert die Webanwendung alle drei Anmeldebereiche und einen Google Drive-Bereich ohne Anmeldung an. Nachdem Nutzer den Anmeldebereichen zugestimmt haben, wird ihnen der detaillierte Zustimmungsbildschirm für die Zustimmung zu den Berechtigungen für die Google Drive-Berechtigung angezeigt:

Mehrere Bereiche ohne Anmeldung

Nutzern wird ein detaillierter Zustimmungsbildschirm für die Berechtigung angezeigt, wenn Anwendungen mehr als einen Nicht-Anmeldebereich anfordern. Nutzer können auswählen, welche Berechtigungen sie für die Anwendung genehmigen möchten. Hier ist ein Beispiel für einen detaillierten Zustimmungsbildschirm für die Berechtigung zum Zugriff auf die Gmail-Nachrichten und Google Kalender-Daten eines Nutzers:

Für Anwendungen, die nur Anmeldebereiche anfordern (email, profile und openid), ist der Zustimmungsbildschirm für Berechtigungen #Inspect-your-application-codegranular nicht anwendbar. Nutzer genehmigen die gesamte Anmeldeanfrage oder lehnen sie ab. Wenn Anwendungen also nur Anmeldebereiche (einen, zwei oder alle drei Bereiche) anfordern, ist der detaillierte Zustimmungsbildschirm für Berechtigungen nicht anwendbar.

Für Anwendungen, die nur einen Nicht-Sign-in-Bereich anfordern, ist der detaillierte Zustimmungsbildschirm für die Berechtigung nicht anwendbar. Mit anderen Worten: Nutzer genehmigen oder lehnen die gesamte Anfrage entweder ab oder lehnen sie ab und es gibt kein Kästchen auf dem Zustimmungsbildschirm. In der folgenden Tabelle wird zusammengefasst, wann ein detaillierter Zustimmungsbildschirm für Berechtigungen angezeigt wird.

Ermitteln, ob Ihre Anwendungen betroffen sind

Prüfe alle Bereiche deiner Anwendung, in denen Autorisierungsendpunkte von Google OAuth 2.0 für Berechtigungsanfragen verwendet werden, gründlich. Achten Sie auf diejenigen, die mehrere Bereiche anfordern, da sie detaillierte Bildschirme für die Einwilligung zu Berechtigungen aktivieren, die Nutzern angezeigt werden. In solchen Fällen muss Ihr Code für den Fall geeignet sein, dass Nutzer nur einen Teil der Bereiche autorisieren.

So ermitteln Sie, ob Ihre Anwendung mehrere Bereiche verwendet

Prüfe deinen App-Code oder den ausgehenden Netzwerkaufruf, um festzustellen, ob die von deiner App gesendeten Autorisierungsanfragen für Google OAuth 2.0 dazu führen, dass der detaillierte Zustimmungsbildschirm für Berechtigungen angezeigt wird.

Anwendungscode prüfen

Überprüfen Sie die Abschnitte Ihres Anwendungscodes, in denen Sie Aufrufe an die OAuth-Autorisierungsendpunkte von Google senden, um Berechtigungen von Nutzern anzufordern. Wenn Sie eine der Google API-Clientbibliotheken verwenden, können Sie häufig in den Initialisierungsschritten des Clients herausfinden, welche Bereiche Ihre Anwendung anfordert. Einige Beispiele finden Sie im folgenden Abschnitt. Ob deine Anwendung betroffen ist, erfährst du in der Dokumentation der SDKs, die deine Anwendung zur Verarbeitung von Google OAuth 2.0 verwendet. Orientiere dich dabei an den Anleitungen in den folgenden Beispielen.

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

Ausgehende Netzwerkanrufe prüfen

Suchen Sie bei der Prüfung von Netzwerkaufrufen nach Anfragen, die an die Autorisierungsendpunkte von Google OAuth gesendet wurden, und prüfen Sie den Parameter scope.

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

• Der Parameter scope enthält Bereiche mit und ohne Anmeldung.

  Die folgende Beispielanfrage enthält alle drei Anmeldebereiche und einen Nicht-Anmeldebereich, um die Metadaten der Google Drive-Dateien des Nutzers anzusehen:

  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 mehrere Bereiche ohne Anmeldung.

  Die folgende Beispielanfrage enthält zwei Bereiche, die nicht zur Anmeldung gehören, um die Google Drive-Metadaten des Nutzers anzusehen 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 detaillierte Berechtigungen

Wenn Sie determine, dass Ihre Anwendung aktualisiert werden muss, um detaillierte Berechtigungen zu verarbeiten, sollten Sie den Code entsprechend aktualisieren, um die Einwilligung für mehrere Bereiche korrekt zu verarbeiten. Bei allen Anwendungen sollten die folgenden Best Practices eingehalten werden:

1. Lesen Sie die Nutzerdatenrichtlinie der Google API-Dienste und halten Sie sie ein.
2. Fordern Sie bestimmte Bereiche an, die für eine Aufgabe benötigt werden. Sie müssen die Google OAuth 2.0-Richtlinie einhalten, sodass Sie nur benötigte Bereiche anfordern. Sie sollten bei der Anmeldung nicht nach mehreren Bereichen fragen, es sei denn, dies ist für die Hauptfunktion Ihrer Anwendung unerlässlich. Wenn Sie mehrere Bereiche zusammenfassen, insbesondere für neue Nutzer, die mit den Funktionen Ihrer Anwendung nicht vertraut sind, kann es für sie schwierig werden, die Notwendigkeit dieser Berechtigungen nachzuvollziehen. Dies kann Alarme auslösen und Nutzer davon abhalten, weiter mit Ihrer Anwendung zu interagieren.
3. Begründen Sie den Nutzer, bevor Sie die Autorisierungsanfrage stellen. Erläutern Sie klar, 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 profitieren kann. Unsere Untersuchungen haben ergeben, dass diese Erklärungen das Vertrauen der Nutzer stärken und die Interaktion fördern.
4. Verwenden Sie inkrementelle Autorisierung, wenn Ihre Anwendung Bereiche anfordert, um nicht mehrere Zugriffstokens verwalten zu müssen.
5. Prüfen Sie, welche Bereiche Nutzer gewährt haben. Wenn Nutzer mehrere Bereiche gleichzeitig anfordern, gewähren Nutzer möglicherweise nicht alle Bereiche, die von Ihrer Anwendung angefordert werden. Ihre Anwendung sollte immer prüfen, welche Bereiche vom Nutzer gewährt wurden, und bei Ablehnungen von Bereichen vorgehen, indem die entsprechenden Features deaktiviert werden. Halte dich an die Google OAuth 2.0-Richtlinien zum Umgang mit der Einwilligung für mehrere Bereiche. Fordern Sie den Nutzer erst dann noch einmal zur Einwilligung auf, wenn er klar angibt, dass die Funktion verwendet werden soll, die den Umfang erfordert.

Anwendung aktualisieren, um detaillierte Berechtigungen zu verarbeiten

Android-Anwendungen

Sehen Sie sich die Dokumentation der SDKs an, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung so, dass detaillierte Berechtigungen gemäß den Best Practices gehandhabt werden.

Wenn Sie das auth.api.signin SDK der Play-Dienste verwenden, um mit Google OAuth 2.0 zu interagieren, können Sie mit der Funktion requestPermissions den kleinsten erforderlichen Bereich anfordern und mit der Funktion hasPermissions prüfen, welche Bereiche der Nutzer beim Anfordern detaillierter Berechtigungen erteilt hat.

Chrome-Erweiterungsanwendungen

Gemäß Best Practices solltest du für die Arbeit mit Google OAuth 2.0 die Chrome Identity API verwenden.

Das folgende Beispiel zeigt, wie detaillierte Berechtigungen richtig verarbeitet werden.

manifest.json

Die Beispielmanifestdatei deklariert zwei Bereiche, die keine Anmeldung sind, für die Anwendung mit der Chrome-Erweiterung.

{
  "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"]
  }
}

Falsche Vorgehensweise

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

Richtige Vorgehensweise

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

Apps für iOS, iPadOS und macOS

Sehen Sie sich die Dokumentation der SDKs an, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung so, dass detaillierte Berechtigungen gemäß den Best Practices gehandhabt werden.

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

Sehen Sie sich die Dokumentation der SDKs an, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung so, dass detaillierte Berechtigungen gemäß den Best Practices gehandhabt werden.

Serverseitiger (Offline-)Zugriff

Das folgende Code-Snippet zeigt ein NodeJS-Beispiel, das zwei Bereiche ohne Anmeldung anfordert. Nutzer sehen dann den detaillierten Zustimmungsbildschirm für die Berechtigung.

Falsche Vorgehensweise

...
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 above
  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 Google OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from Google OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google OAuth 2.0 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);
}

Richtige Vorgehensweise

...
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 above
  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 Google OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from Google OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google OAuth 2.0 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);
}

In der Anleitung zu serverseitigen Webanwendungen wird beschrieben, wie Sie über serverbasierte Anwendungen auf Google APIs zugreifen.

Nur clientseitiger Zugriff

• Für Anwendungen, die die JavaScript-Bibliothek der Google Identity Services verwenden, um mit Google OAuth 2.0 zu interagieren, solltest du diese Dokumentation zum Umgang mit detaillierten Berechtigungen lesen.
• Für Anwendungen, die mithilfe von JavaScript direkt Aufrufe an Autorisierungsendpunkte von Google OAuth 2.0 senden, solltest du diese Dokumentation zum Umgang mit detaillierten Berechtigungen lesen.

Aktualisierte Anwendung hinsichtlich der Handhabung detaillierter Berechtigungen testen

1. Beschreiben Sie alle Fälle, in denen Nutzer auf Berechtigungsanfragen antworten können, sowie das erwartete Verhalten Ihrer Anwendung. Wenn der Nutzer beispielsweise nur zwei von drei angeforderten Bereichen autorisiert, sollte sich Ihre Anwendung entsprechend verhalten.
2. Testen Sie Ihre Anwendung mit aktivierten detaillierten Berechtigungen. Es gibt zwei Möglichkeiten, detaillierte Berechtigungen zu aktivieren:
   1. Prüfen Sie auf den OAuth 2.0-Zustimmungsbildschirmen Ihrer Anwendung, ob für Ihre Anwendung bereits detaillierte Berechtigungen aktiviert sind. Sie können auch zu Testzwecken eine neue Web-, Android- oder iOS-Client-ID für Google OAuth 2.0 über die Google Cloud Console erstellen, da für sie immer detaillierte Berechtigungen aktiviert sind.
   2. Lege den Parameter enable_granular_consent beim Aufrufen der Autorisierungsendpunkte von Google OAuth auf true fest. Einige SDKs unterstützen diesen Parameter explizit. Lesen Sie bei anderen Anbietern in der Dokumentation nach, wie Sie diesen Parameter und seinen Wert manuell hinzufügen können. Wenn das Hinzufügen des Parameters in Ihrer Implementierung nicht unterstützt wird, können Sie wie oben beschrieben über die Google Cloud Console eine neue Web-, Android- oder iOS-Client-ID für Google OAuth 2.0 erstellen.