Detaillierte Berechtigungen

Übersicht

Mit detaillierten Berechtigungen erhalten Nutzer mehr Kontrolle darüber, welche Kontodaten sie mit den einzelnen Apps teilen. Das bietet sowohl Nutzern als auch Entwicklern mehr Kontrolle, Transparenz und Sicherheit. In diesem Leitfaden erfahren Sie, welche Änderungen und Schritte erforderlich sind, um Ihre Anwendungen für die Verarbeitung detaillierter Berechtigungen zu aktualisieren.

Was sind detaillierte Berechtigungen?

Stellen Sie sich vor, Sie entwickeln eine Produktivitäts-App, für die sowohl E-Mail- als auch Kalenderberechtigungen erforderlich sind. Ihre Nutzer möchten Ihre Anwendung möglicherweise nur für Google Kalender, nicht aber für Gmail verwenden. Mit detaillierten OAuth-Berechtigungen können Nutzer beispielsweise nur die Berechtigung für Google Kalender, nicht aber für Gmail erteilen. Wenn Nutzer den Zugriff auf bestimmte Daten gewähren können, wird die Offenlegung von Daten minimiert, das Vertrauen gestärkt und Nutzer erhalten die Kontrolle über ihr digitales Leben. Es ist wichtig, dass Sie Ihre Anwendung so konzipieren, dass sie mit solchen Szenarien umgehen kann.

Wenn mehr als ein Bereich ohne Anmeldung angefordert wird

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, sehen sie einen detaillierten Einwilligungsbildschirm für die Nicht-Anmeldebereiche. 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 Anmeldebereiche und einen Google Drive-Bereich ohne Anmeldung an. Nachdem Nutzer den Anmeldebereichen zugestimmt haben, sehen sie den Einwilligungsbildschirm für die detaillierten Berechtigungen für die Google Drive-Berechtigung:

Mehr als ein Bereich ohne Anmeldung

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

Für Anwendungen, die nur Log‑in-Bereiche (email, profile und openid) anfordern, ist der Einwilligungsbildschirm für detaillierte Berechtigungen nicht relevant. Nutzer genehmigen oder lehnen die gesamte Anmeldeanfrage ab. Wenn Anwendungen nur Anmeldebereiche (einen, zwei oder alle drei) anfordern, ist der Einwilligungsbildschirm für detaillierte Berechtigungen nicht anwendbar.

Für Anwendungen, die nur einen Bereich ohne Anmeldung anfordern, ist der granulare Zustimmungsbildschirm für Berechtigungen nicht anwendbar. Das bedeutet, dass Nutzer die gesamte Anfrage entweder genehmigen oder ablehnen. Auf dem Einwilligungsbildschirm gibt es kein Kästchen. In der folgenden Tabelle wird zusammengefasst, wann der Einwilligungsbildschirm für detaillierte Berechtigungen angezeigt wird.

Prüfen, ob Ihre Anwendungen betroffen sind

Überprüfen Sie alle Abschnitte Ihrer Anwendung, in denen Google OAuth 2.0-Autorisierungsendpunkte für Berechtigungsanfragen verwendet werden. Achten Sie auf Apps, 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 abfangen können, in dem Nutzer nur einige der Bereiche autorisieren.

Herausfinden, ob Ihre Anwendung mehrere Bereiche verwendet

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

Anwendungscode prüfen

Sehen Sie sich die Abschnitte Ihres Anwendungscodes an, in denen Sie die Google OAuth-Autorisierungsendpunkte aufrufen, um Berechtigungen von Nutzern anzufordern. Wenn Sie eine der Google API-Clientbibliotheken verwenden, können Sie die von Ihrer Anwendung angeforderten Bereiche oft in den Clientinitialisierungsschritten finden. Im folgenden Abschnitt finden Sie einige Beispiele. Anhand der Dokumentation der SDKs, die Ihre Anwendung verwendet, um Google OAuth 2.0 zu verarbeiten, können Sie feststellen, 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 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
});

Ausgehenden Netzwerkanruf prüfen

Achten Sie bei der Überprüfung von Netzwerkanrufen auf Anfragen, die an die Google OAuth-Autorisierungsendpunkte gesendet werden, und untersuchen Sie den Parameter scope.

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

• Der Parameter scope enthält Anmeldebereiche und Bereiche, die nicht für die Anmeldung verwendet werden.

  Die folgende Beispielanfrage enthält alle drei Anmeldebereiche und einen Bereich, der nicht für die Anmeldung verwendet wird, 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 verwendet wird.

  Die folgende Beispielanfrage enthält zwei Bereiche, die nicht für die Anmeldung verwendet werden, 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 Änderungen an Ihrem Code vornehmen, um die Einwilligung für mehrere Bereiche ordnungsgemäß zu verarbeiten. Alle Anwendungen sollten die folgenden Best Practices einhalten:

1. Lesen Sie sich die Nutzerdatenrichtlinie 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, die besagt, dass Sie nur die Bereiche anfordern dürfen, die Sie benötigen. Sie sollten bei der Anmeldung nicht nach mehreren Bereichen fragen, es sei denn, dies ist für die Hauptfunktionen Ihrer App unbedingt erforderlich. Wenn Sie mehrere Bereiche zusammenfassen, insbesondere für Erstnutzer, die mit den Funktionen Ihrer Anwendung nicht vertraut sind, kann es für sie 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ünden Sie die Autorisierungsanfrage für Nutzer, bevor Sie sie stellen. Erklären Sie deutlich, 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 haben ergeben, dass diese Erklärungen das Vertrauen der Nutzer und die Nutzerinteraktionen steigern.
4. Verwenden Sie 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 der Nutzer gewährt hat, und die Verweigerung von Bereichen durch Deaktivieren der entsprechenden Funktionen berücksichtigen. Halten Sie sich an die Google OAuth 2.0-Richtlinien zum Einholen der Einwilligung für mehrere Bereiche und fordern Sie die Einwilligung des Nutzers erst dann wieder an, wenn er eindeutig die Absicht geäußert hat, die Funktion zu verwenden, für die der Bereich erforderlich ist.

App für die Verarbeitung detaillierter Berechtigungen aktualisieren

Android-Anwendungen

Sehen Sie in der Dokumentation der SDKs nach, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung, damit sie detaillierte Berechtigungen gemäß den Best Practices verarbeitet.

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

Chrome-Erweiterungsanwendungen

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

Im folgenden Beispiel wird gezeigt, wie differenzierte Berechtigungen richtig gehandhabt werden.

manifest.json

In der Beispielmanifestdatei werden zwei Bereiche ohne Anmeldung für die Chrome-Erweiterungsanwendung deklariert.

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

Sehen Sie in der Dokumentation der SDKs nach, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung, damit sie detaillierte Berechtigungen gemäß den Best Practices verarbeitet.

Wenn Sie die Google-Anmeldung für iOS und macOS-Bibliothek verwenden, um mit Google OAuth 2.0 zu interagieren, sollten Sie die Dokumentation zur Verarbeitung von detaillierten Berechtigungen lesen.

Webanwendungen

Sehen Sie in der Dokumentation der SDKs nach, die Sie für die Interaktion mit Google OAuth 2.0 verwenden, und aktualisieren Sie Ihre Anwendung, damit sie detaillierte Berechtigungen gemäß den Best Practices verarbeitet.

Serverseitiger (Offline-)Zugriff

Das folgende Code-Snippet zeigt ein NodeJS-Beispiel, in dem zwei Bereiche angefordert werden, die nicht für die Anmeldung erforderlich sind. Nutzer sehen den detaillierten Zustimmungsbildschirm für Berechtigungen.

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

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

Im Leitfaden für serverseitige Webanwendungen erfahren Sie, wie Sie von serverbasierten Anwendungen aus auf Google-APIs zugreifen.

Nur clientseitiger Zugriff

• Wenn Ihre Anwendung die Google Identity Services-JavaScript-Bibliothek verwendet, um mit Google OAuth 2.0 zu interagieren, sollten Sie sich diese Dokumentation zum Umgang mit detaillierten Berechtigungen ansehen.
• Wenn Ihre Anwendungen direkt mit JavaScript Google OAuth 2.0-Autorisierungsendpunkte aufrufen, sollten Sie sich diese Dokumentation zum Umgang mit detaillierten Berechtigungen ansehen.

Aktualisierte App für die Verarbeitung detaillierter Berechtigungen testen

1. Beschreiben Sie alle Fälle, in denen Nutzer auf Berechtigungsanfragen reagieren können, und 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 aktivierter detaillierter Berechtigung. Es gibt zwei Möglichkeiten, detaillierte Berechtigungen zu aktivieren:
   1. Prüfen Sie die OAuth 2.0-Zustimmungsbildschirme Ihrer Anwendung, um festzustellen, ob detaillierte Berechtigungen bereits für Ihre Anwendung aktiviert sind. Sie können auch eine neue Google OAuth 2.0-Client-ID für Web, Android oder iOS über die Google Cloud Console für Testzwecke erstellen, da für diese immer die granulare Berechtigung aktiviert ist.
   2. Legen Sie den Parameter enable_granular_consent beim Aufrufen der Google OAuth-Autorisierungsendpunkte auf true fest. Einige SDKs unterstützen diesen Parameter explizit. Bei anderen müssen Sie in der Dokumentation nachsehen, 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 über die Google Cloud Console eine neue Google OAuth 2.0-Client-ID für Web, Android oder iOS erstellen, die nur für Testzwecke verwendet werden darf (siehe vorheriger Punkt).
3. Verwenden Sie beim Testen Ihrer aktualisierten Anwendung ein privates Google-Konto (@gmail.com) anstelle eines Workspace-Kontos. Das liegt daran, dass Workspace Enterprise-Apps mit domain-wide delegation of authority (domainweite Delegierung von Berechtigungen) oder die als Trusted (vertrauenswürdig) gekennzeichnet sind, derzeit nicht von den Änderungen an den detaillierten Berechtigungen betroffen sind. Wenn Sie also mit einem Workspace-Konto Ihrer Organisation testen, wird der neue detaillierte Einwilligungsbildschirm möglicherweise nicht wie vorgesehen angezeigt.