Detaillierte Berechtigungen

Übersicht

Mit detaillierten Berechtigungen können Nutzer genauer festlegen, welche Kontodaten sie für jede App freigeben möchten. Sie bieten sowohl Nutzern als auch Entwicklern mehr Kontrolle, Transparenz und Sicherheit. Dieser Leitfaden hilft Ihnen, die notwendigen Änderungen und Schritte, um Ihre Anwendungen so zu aktualisieren, dass sie detaillierte Berechtigungen verwalten 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. Ihre Nutzer möchten Sie Ihre Anwendung möglicherweise nur für Google Kalender verwenden, nicht aber für Google Mail. Mit detailliertem OAuth -Berechtigungen können Nutzer festlegen, dass sie nur die Berechtigung für Google Kalender und nicht für Gmail erteilen möchten. Dadurch, dass Nutzer Zugriff auf bestimmte Daten gewähren können, wird die Offenlegung von Daten minimiert, und gibt Nutzern datenschutzorientierte Kontrolle über ihr digitales Leben. Es ist wichtig, Ihre Anwendung so zu gestalten, dass sie mit solchen Szenarien umgehen kann.

Wenn mehr als ein Nicht-Anmeldebereich angefordert wird

Anmelde- und andere Bereiche

Bei Anwendungen, die Anmeldungen und andere Bereiche anfordern, sehen Nutzer zuerst die Einwilligung Seite für Anmeldebereiche (email, profile und openid) Nachdem Nutzer zugestimmt haben, grundlegende Identitätsinformationen (Name, E-Mail-Adresse und Profilbild) nicht zu ändern, sehen die Nutzer einen detaillierten Zustimmungsbildschirm für Berechtigungen für die Bereiche ohne Anmeldung. In diesem Fall hat die Anwendung muss prüfen, welche Bereiche von den Nutzern gewährt wurden, und kann nicht davon ausgehen, dass Nutzer alle angeforderten Berechtigungen gewähren Bereiche. Im folgenden Beispiel fordert die Webanwendung alle drei Anmeldebereiche und einen Google Drive ohne Anmeldung. Nachdem Nutzer den Anmeldebereichen zugestimmt haben, sehen sie die detaillierter Berechtigungen Zustimmungsbildschirm für die Google Drive-Berechtigung:

Mehrere Nicht-Anmeldungsbereiche

Nutzern wird ein detaillierter Zustimmungsbildschirm für Berechtigungen angezeigt, wenn Anwendungen mehr anfordern. als einen Nicht-Log-in-Bereich. Nutzer können auswählen, welche Berechtigungen sie freigeben möchten mit der Anwendung. Im Folgenden finden Sie ein Beispiel für einen Bildschirm mit detaillierter Einwilligung für Berechtigungen, auf dem der Zugriff auf die Gmail-Nachrichten und Google Kalender-Daten des Nutzers angefordert wird:

Bei Anwendungen, die nur Bereiche für die Anmeldung (email, profile und openid) anfordern, ist der Bildschirm für die Einwilligung in die detaillierten Berechtigungen nicht zu sehen. Nutzer genehmigen oder verweigern die gesamte Anmeldung Anders gesagt: Wenn Anwendungen nur Anmeldebereiche anfordern (ein, zwei oder alle 3), ist der detaillierte Zustimmungsbildschirm für die Berechtigung nicht anwendbar.

Für Anwendungen, die nur einen Bereich ohne Anmeldung anfordern, ist die detaillierte Zustimmungsbildschirm für die Berechtigung ist nicht zutreffend. Mit anderen Worten, Nutzende genehmigen die gesamte Anfrage ablehnen und auf dem Zustimmungsbildschirm kein Kästchen zu sehen ist. In der folgenden Tabelle wird zusammengefasst, wann der detaillierte Einwilligungsbildschirm für Berechtigungen angezeigt wird.

Ermitteln, ob Ihre Anwendungen betroffen sind

Führen Sie eine gründliche Prüfung aller Abschnitte in Ihrer Anwendung durch, in denen Für Berechtigungsanfragen werden Google OAuth 2.0-Autorisierungsendpunkte verwendet. Achten Sie auf Entwickler, die mehrere Bereiche anfordern, um detaillierte Einwilligungsbildschirme für Berechtigungen zu aktivieren die den Nutzenden präsentiert werden. Achten Sie in solchen Fällen darauf, dass Ihr Code den Fall abdeckt, dass Nutzer nur einige der Bereiche autorisieren.

So ermitteln Sie, ob Ihre Anwendung mehrere Bereiche verwendet

Prüfen Sie den App-Code oder den ausgehenden Netzwerkanruf, um festzustellen, ob der OAuth 2.0 Von deiner App gestellte Autorisierungsanfragen führen zu einem detaillierten Zustimmungsbildschirm für Berechtigungen angezeigt werden soll.

Anwendungscode prüfen

Überprüfen Sie die Abschnitte Ihres Anwendungscodes, in denen Sie das Google OAuth-Protokoll aufrufen. Autorisierungsendpunkte, um Berechtigungen von Nutzern anzufordern. Wenn Sie eine der Google APIs verwenden Clientbibliotheken können Sie häufig ermitteln, welche Bereiche Ihre Anwendung im Client anfordert, Initialisierungsschritten. Im folgenden Abschnitt finden Sie einige Beispiele. Weitere Informationen finden Sie in der der SDKs, die Ihre Anwendung zur Verarbeitung von Google OAuth 2.0 verwendet, um festzustellen, Anwendung betroffen ist. Beachten Sie dabei die folgenden Beispiele. 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

Suchen Sie bei der Untersuchung der Netzwerkaufrufe nach Anfragen, die an die Google OAuth- Autorisierungsendpunkte und untersuchen Sie den Parameter scope.

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

• Der Parameter scope enthält Anmeldebereiche und andere Bereiche.

  Die folgende Beispielanfrage enthält alle drei Anmeldebereiche und einen Nicht-Anmeldebereich. So rufen Sie die Metadaten der Google Drive-Dateien des Nutzers auf:

  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 Nicht-Anmeldebereich.

  Eine folgende Beispielanfrage enthält zwei Bereiche ohne Anmeldung, um die Google Drive-Ablage des Nutzers Metadaten verwalten und bestimmte Google Drive-Dateien 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 für die Verarbeitung Wenn Sie detaillierte Berechtigungen erteilen möchten, sollten Sie Ihren Code aktualisieren, damit die Einwilligung für mehrere Bereiche. Alle Anwendungen sollten den folgenden Best Practices entsprechen:

1. Lesen Sie die Google API-Dienste: Richtlinie zu Nutzerdaten und achten Sie darauf, dass Sie diese einhalten.
2. Bestimmte Bereiche anfragen, die für eine Aufgabe benötigt werden. Ich der Google OAuth 2.0-Richtlinie entsprechen, Anfragebereiche stellen, erforderlich. Sie sollten nicht mehrfach Bereiche bei der Anmeldung, es sei denn, dies ist für die Hauptfunktion Ihrer App unbedingt erforderlich. Bündelung verschiedene Bereiche zu kombinieren, insbesondere für neue Nutzende, die mit Ihrem App-Funktionen kann es für sie schwierig sein, den Bedarf an diesen Berechtigungen. Dies kann einen Alarm auslösen und Nutzer davon abhalten, weiter mit deinem .
3. Begründen Sie die Nutzer, bevor Sie danach fragen. Autorisierungsanfrage. Erläutern Sie klar, warum Ihre Anwendung die angeforderte Berechtigung benötigt. was Sie mit den Daten des Nutzers tun und wie er von der Genehmigung der Anfrage profitiert. Unsere Untersuchungen haben ergeben, dass diese Erklärungen das Vertrauen und die Interaktion der Nutzer stärken.
4. Verwenden inkrementelle Autorisierung Wenn Ihre Anwendung Bereiche anfordert, um nicht mehrere Zugriffstokens verwalten zu müssen.
5. Überprüfen Sie, welche Bereiche Nutzer gewährt haben. Wenn Sie mehrere Bereiche gleichzeitig haben, gewähren Nutzer möglicherweise nicht alle Bereiche Ihrer Anwendungsanfragen. Ihre App sollte immer Prüfen Sie, welche Bereiche vom Nutzer gewährt wurden, und deaktivieren Sie relevante Bereiche, Funktionen. Die Google OAuth 2.0-Richtlinien auf die Einwilligung für mehrere Umfänge und fordern den Nutzer erst dann noch einmal zur Einwilligung auf, wenn er die Absicht, die Funktion zu verwenden, für die der Umfang erforderlich ist.

Anwendung für die Verarbeitung detaillierter Berechtigungen aktualisieren

Android-Anwendungen

Weitere Informationen finden Sie in der Dokumentation der SDKs, die Sie für die Interaktion mit Google OAuth 2.0 und Aktualisieren Sie Ihre Anwendung, um detaillierte Berechtigungen basierend auf Best Practices.

Wenn Sie auth.api.signin SDK von Play-Diensten für die Interaktion mit Google OAuth 2.0 verwenden, können Sie requestPermissions um den kleinsten Satz von Bereichen anzufordern, und die hasPermissions können Sie überprüfen, welche Bereiche der Nutzer detaillierte Berechtigungen anfordern.

Chrome-Erweiterungsanwendungen

Sie sollten Google Chrome Identity API für Google OAuth 2.0 basierend auf Best Practices.

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

manifest.json

In der Beispielmanifestdatei werden zwei nicht angemeldete Umfänge für die Chrome-Erweiterung 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"]
  }
}

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

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

Weitere Informationen finden Sie in der Dokumentation der SDKs, die Sie für die Interaktion mit Google OAuth 2.0 und Aktualisieren Sie Ihre Anwendung, um detaillierte Berechtigungen basierend auf Best Practices.

Wenn Sie die Google Sign-In for iOS and macOS-Bibliothek verwenden, um mit Google OAuth 2.0 zu interagieren, sollten Sie sich die Dokumentation zum Umgang mit detaillierten Berechtigungen ansehen.

Webanwendungen

Weitere Informationen finden Sie in der Dokumentation der SDKs, die Sie für die Interaktion mit Google OAuth 2.0 und Aktualisieren Sie Ihre Anwendung, um detaillierte Berechtigungen basierend auf Best Practices.

Serverseitiger (Offline-)Zugriff

Das folgende Code-Snippet zeigt ein NodeJS-Beispiel, mit dem zwei Nicht-Anmeldebereiche angefordert werden. Die Nutzenden um den detaillierten Zustimmungsbildschirm für Berechtigungen anzuzeigen.

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 für serverseitige Webanwendungen erfahren Sie, wie Sie von serverbasierten Anwendungen auf Google APIs zugreifen.

Nur clientseitiger Zugriff

• Für Anwendungen, die Google Identity Services verwenden JavaScript-Bibliothek für die Interaktion mit Google OAuth 2.0, finden Sie hier Dokumentation zum Umgang mit detaillierten Berechtigungen.
• Für Anwendungen, die direkte Aufrufe über JavaScript an Google OAuth 2.0-Autorisierung senden Endpunkten, sollten Sie diese Dokumentation zum Umgang mit detaillierten Berechtigungen.

Aktualisierte Anwendung im Umgang mit detaillierten Berechtigungen testen

1. Beschreiben Sie alle Fälle, in denen Nutzer auf Berechtigungsanfragen antworten können, sowie die von Ihrer Anwendung zu erwarten. Wenn der Nutzer beispielsweise nur zwei von drei angeforderten Bereichen haben, sollte sich Ihre Anwendung entsprechend verhalten.
2. Testen Sie Ihre Anwendung mit aktivierten detaillierten Berechtigungen. Es gibt zwei Möglichkeiten, detaillierte Berechtigungen:
   1. Prüfen Sie die OAuth 2.0-Zustimmungsbildschirme Ihrer Anwendung, um festzustellen, ob für Ihre Anwendung bereits detaillierte Berechtigungen aktiviert sind. Sie können auch eine neue Google OAuth 2.0-Client-ID für das Web, Android oder iOS zu Testzwecken über die Google Cloud Console erstellen, da für diese immer detaillierte Berechtigungen aktiviert sind.
   2. Parameter festlegen enable_granular_consent auf true, wenn das Google OAuth aufgerufen wird Autorisierungsendpunkte. Einige SDKs unterstützen dies explizit . In der Dokumentation erfahren Sie, wie Sie diesen Parameter hinzufügen und manuell einen Wert eingeben. Wenn Ihre Implementierung das Hinzufügen des Parameters nicht unterstützt, können Sie ein neues Web-, Google OAuth 2.0-Client-ID für Android oder iOS über die Google Cloud Console zu Testzwecken die im vorigen Punkt genannt wurden.
3. Verwenden Sie beim Testen Ihrer aktualisierten Anwendung ein privates Google-Konto (@gmail.com) anstelle eines ein Workspace-Konto. Das liegt daran, dass Workspace Enterprise-Apps domainweite Übertragung von Befugnissen oder die Kennzeichnung Vertrauenswürdig sind derzeit nicht von den Änderungen an den detaillierten Berechtigungen betroffen. Das Testen mit einem Arbeitsbereich im Konto Ihrer Organisation wird der neue detaillierte Zustimmungsbildschirm möglicherweise nicht wie beabsichtigt angezeigt.