Jak obsługiwać szczegółowe uprawnienia

Przegląd

Dzięki szczegółowym uprawnieniom konsumenci mają większą kontrolę nad tym, jakie dane na koncie chcą udostępniać poszczególnym aplikacjom. Zapewnia to korzyści zarówno użytkownikom, jak i deweloperom, ponieważ zwiększa kontrolę, przejrzystość i bezpieczeństwo. Z tego przewodnika dowiesz się, jakie zmiany i kroki są niezbędne, aby pomyślnie zaktualizować aplikacje pod kątem obsługi uprawnień szczegółowych.

Czym są szczegółowe uprawnienia?

Wyobraź sobie, że tworzysz aplikację zwiększającą produktywność, która żąda dostępu do zakresów poczty e-mail i kalendarza. Użytkownicy mogą chcieć używać Twojej aplikacji tylko w Kalendarzu Google, ale nie w Gmailu. Dzięki szczegółowym uprawnieniom OAuth użytkownicy mogą przyznać uprawnienia tylko do Kalendarza Google, ale nie do Gmaila. Dzięki temu, że użytkownicy mogą przyznawać dostęp do konkretnych danych, minimalizuje to ryzyko ich ujawnienia, zwiększa zaufanie i zapewnia użytkownikom kontrolę nad ich cyfrowym życiem skoncentrowaną na ochronie prywatności. Ważne jest, aby zaprojektować aplikację tak, aby obsługiwała takie scenariusze.

gdy wymagany jest więcej niż 1 zakres inny niż logowanie;

Zakresy logowania i zakresy inne niż logowanie

W przypadku aplikacji, które żądają zakresów logowania i zakresów innych niż logowanie, użytkownicy najpierw widzą stronę zgody na zakresy logowania (email, profile i openid). Gdy użytkownicy wyrażą zgodę na udostępnianie podstawowych informacji o tożsamości (imię i nazwisko, adres e-mail i zdjęcie profilowe), zobaczą ekran zgody na szczegółowe uprawnienia dotyczące zakresów innych niż logowanie. W takim przypadku aplikacja musi sprawdzić, jakie zakresy zostały przyznane przez użytkowników, i nie może zakładać, że użytkownicy przyznają wszystkie żądane zakresy. W poniższym przykładzie aplikacja internetowa żąda wszystkich 3 zakresów logowania i zakresu Dysku Google niezwiązanego z logowaniem. Gdy użytkownicy wyrażą zgodę na zakresy logowania, zobaczą ekran zgody na szczegółowe uprawnienia do Dysku Google:

Więcej niż 1 zakres inny niż logowanie

Ekran zgody na szczegółowe uprawnienia będzie wyświetlany użytkownikom, gdy aplikacje będą prosić o więcej niż 1 zakres inny niż logowanie. Użytkownicy mogą wybrać uprawnienia, które chcą zatwierdzić, aby udostępnić je aplikacji. Poniżej znajduje się przykładowy ekran zgody na szczegółowe uprawnienia, na którym użytkownik jest proszony o dostęp do wiadomości w Gmailu i danych z Kalendarza Google:

W przypadku aplikacji, które żądają tylko zakresów logowania (email, profile i openid), ekran zgody na uprawnienia szczegółowe nie ma zastosowania. Użytkownicy mogą zatwierdzić lub odrzucić całą prośbę o zalogowanie. Innymi słowy, jeśli aplikacje żądają tylko zakresów logowania (jednego, dwóch lub wszystkich trzech), ekran zgody na szczegółowe uprawnienia nie dotyczy.

W przypadku aplikacji, które żądają tylko jednego zakresu innego niż logowanie, ekran zgody na szczegółowe uprawnienia nie ma zastosowania. Innymi słowy, użytkownicy zatwierdzają lub odrzucają całą prośbę, a na ekranie zgody nie ma pola wyboru. Tabela poniżej zawiera podsumowanie sytuacji, w których wyświetlany jest ekran zgody na szczegółowe uprawnienia.

Sprawdzanie, czy problem dotyczy Twoich aplikacji

Dokładnie sprawdź wszystkie sekcje aplikacji, w których punkty końcowe autoryzacji Google OAuth 2.0 są używane do wysyłania próśb o uprawnienia. Zwróć uwagę na te, które żądają wielu zakresów, ponieważ aktywują one ekrany zgody na szczegółowe uprawnienia wyświetlane użytkownikom. W takich przypadkach upewnij się, że Twój kod może obsłużyć sytuację, w której użytkownicy autoryzują tylko niektóre zakresy.

Jak sprawdzić, czy aplikacja używa wielu zakresów

Sprawdź kod aplikacji lub wychodzące połączenie sieciowe, aby ustalić, czy żądania autoryzacji Google OAuth 2.0 wysyłane przez Twoją aplikację spowodują wyświetlenie ekranu zgody na uprawnienia szczegółowe.

Sprawdzanie kodu aplikacji

Przejrzyj sekcje kodu aplikacji, w których wywołujesz punkty końcowe autoryzacji Google OAuth, aby poprosić użytkowników o uprawnienia. Jeśli używasz jednej z bibliotek klienta interfejsów API Google, zakresy, o które prosi aplikacja, możesz często znaleźć w krokach inicjowania klienta. W następnej sekcji znajdziesz kilka przykładów. Aby sprawdzić, czy problem dotyczy Twojej aplikacji, zapoznaj się z dokumentacją pakietów SDK, których aplikacja używa do obsługi Google OAuth 2.0. Jako punktu odniesienia użyj wskazówek podanych w poniższych przykładach.

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

Sprawdzanie wychodzącego wywołania sieciowego

Sposób sprawdzania wywołań sieciowych zależy od typu aplikacji.

• Aplikacja internetowa – sprawdzanie aktywności sieciowej w Chrome
• Android – sprawdzanie ruchu w sieci za pomocą Network Inspectora
• Aplikacje Chrome
  • Otwórz stronę rozszerzeń do Chrome.
  • W prawym górnym rogu strony rozszerzenia zaznacz pole wyboru Tryb programisty.
  • Wybierz rozszerzenie, które chcesz monitorować.
  • W sekcji Sprawdź widoki na stronie rozszerzenia kliknij link strona w tle.
  • Otworzy się okno Narzędzia dla programistów, w którym możesz monitorować ruch w sieci na karcie Sieć.
• iOS – analizowanie ruchu HTTP za pomocą narzędzi
• Aplikacje komputerowe – użyj narzędzia do przechwytywania ruchu sieciowego dostępnego dla systemu operacyjnego, na który została opracowana aplikacja.

Podczas sprawdzania wywołań sieciowych poszukaj żądań wysyłanych do punktów końcowych autoryzacji Google OAuth i sprawdź parametr scope.

Te wartości powodują wyświetlenie ekranu zgody na szczegółowe uprawnienia.

• Parametr scope zawiera zakresy logowania i zakresy nielogowania.

  Przykładowe żądanie poniżej zawiera wszystkie 3 zakresy logowania i 1 zakres niezwiązany z logowaniem, który umożliwia wyświetlanie metadanych plików użytkownika na Dysku Google:

  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

• Parametr scope zawiera więcej niż 1 zakres inny niż logowanie.

  Przykładowe żądanie poniżej zawiera 2 zakresy niezwiązane z logowaniem, które umożliwiają wyświetlanie metadanych Dysku Google użytkownika i zarządzanie określonymi plikami na Dysku Google:

  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

Sprawdzone metody dotyczące uprawnień szczegółowych

Jeśli ustalisz, że Twoja aplikacja musi zostać zaktualizowana, aby obsługiwać uprawnienia szczegółowe, wprowadź niezbędne zmiany w kodzie, aby prawidłowo obsługiwać zgodę na wiele zakresów. Wszystkie aplikacje powinny być zgodne z tymi sprawdzonymi metodami:

1. Zapoznaj się z zasadami dotyczącymi danych użytkownika w usługach interfejsu API Google i upewnij się, że ich przestrzegasz.
2. Poproś o konkretne zakresy, które są potrzebne do wykonania zadania. Musisz przestrzegać zasady dotyczącej protokołu Google OAuth 2.0, która mówi, że możesz prosić tylko o te zakresy, których potrzebujesz. Unikaj proszenia o dostęp do wielu zakresów podczas logowania, chyba że jest to niezbędne do działania głównej funkcjonalności aplikacji. Łączenie kilku zakresów, zwłaszcza w przypadku nowych użytkowników, którzy nie znają funkcji aplikacji, może utrudnić im zrozumienie, dlaczego te uprawnienia są potrzebne. Może to wzbudzić niepokój i zniechęcić użytkowników do dalszego korzystania z aplikacji.
3. Przed wysłaniem prośby o autoryzację podaj użytkownikom uzasadnienie. Jasno wyjaśnij, dlaczego Twoja aplikacja potrzebuje żądanego uprawnienia, co zrobisz z danymi użytkownika i jakie korzyści przyniesie użytkownikowi zatwierdzenie prośby. Z naszych badań wynika, że takie wyjaśnienia zwiększają zaufanie i zaangażowanie użytkowników.
4. Używaj autoryzacji przyrostowej za każdym razem, gdy aplikacja żąda zakresów, aby uniknąć konieczności zarządzania wieloma tokenami dostępu.
5. Sprawdź, które zakresy przyznali użytkownicy. Jeśli poprosisz o kilka zakresów naraz, użytkownicy mogą nie przyznać wszystkich zakresów, o które prosi aplikacja. Aplikacja powinna zawsze sprawdzać, które zakresy zostały przyznane przez użytkownika, i obsługiwać odmowę dostępu do zakresów przez wyłączenie odpowiednich funkcji. Postępuj zgodnie z zasadami Google OAuth 2.0 dotyczącymi obsługi zgody na wiele zakresów i ponownie poproś użytkownika o zgodę dopiero wtedy, gdy wyraźnie wskaże on zamiar korzystania z konkretnej funkcji, która wymaga danego zakresu.

Aktualizowanie aplikacji pod kątem obsługi uprawnień szczegółowych

Aplikacje na Androida

Zapoznaj się z dokumentacją pakietów SDK, których używasz do interakcji z Google OAuth 2.0, i zaktualizuj aplikację, aby obsługiwała uprawnienia szczegółowe zgodnie ze sprawdzonymi metodami.

Jeśli używasz pakietu SDK auth.api.signin z Usług Google Play do interakcji z Google OAuth 2.0, możesz użyć funkcji requestPermissions, aby poprosić o najmniejszy potrzebny zestaw zakresów, oraz funkcji hasPermissions, aby sprawdzić, które zakresy użytkownik przyznał podczas prośby o uprawnienia szczegółowe.

Aplikacje rozszerzeń do Chrome

Aby korzystać z protokołu Google OAuth 2.0, używaj interfejsu Chrome Identity API zgodnie ze sprawdzonymi metodami.

Poniższy przykład pokazuje, jak prawidłowo obsługiwać uprawnienia szczegółowe.

manifest.json

Przykładowy plik manifestu deklaruje 2 zakresy niezwiązane z logowaniem dla aplikacji rozszerzenia do Chrome.

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

Nieprawidłowe podejście

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

Correct Approach

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

aplikacje na iOS, iPadOS i macOS;

Zapoznaj się z dokumentacją pakietów SDK, których używasz do interakcji z Google OAuth 2.0, i zaktualizuj aplikację, aby obsługiwała uprawnienia szczegółowe zgodnie ze sprawdzonymi metodami.

Jeśli do interakcji z Google OAuth 2.0 używasz biblioteki Logowanie przez Google na iOS i macOS, zapoznaj się z dokumentacją dotyczącą obsługi uprawnień szczegółowych.

Aplikacje internetowe

Zapoznaj się z dokumentacją pakietów SDK, których używasz do interakcji z Google OAuth 2.0, i zaktualizuj aplikację, aby obsługiwała uprawnienia szczegółowe zgodnie ze sprawdzonymi metodami.

Dostęp po stronie serwera (offline)

Tryb dostępu po stronie serwera (offline) wymaga wykonania tych czynności:

• Skonfiguruj serwer i zdefiniuj publicznie dostępny punkt końcowy, który będzie odbierać kod autoryzacji.
• Skonfiguruj identyfikator URI przekierowania publicznego punktu końcowego na stronie Klienci w konsoli Google Cloud.

Poniższy fragment kodu NodeJS pokazuje, jak poprosić o 2 zakresy niezwiązane z logowaniem. Użytkownicy zobaczą ekran zgody na szczegółowe uprawnienia.

Nieprawidłowe podejście

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

Correct Approach

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

Zapoznaj się z przewodnikiem po aplikacji internetowej po stronie serwera, aby dowiedzieć się, jak uzyskać dostęp do interfejsów API Google z aplikacji działających na serwerze.

Dostęp tylko po stronie klienta

• W przypadku aplikacji, które używają biblioteki JavaScript Google Identity Services do interakcji z Google OAuth 2.0, zapoznaj się z tą dokumentacją dotyczącą obsługi uprawnień szczegółowych.
• W przypadku aplikacji, które bezpośrednio wywołują punkty końcowe autoryzacji Google OAuth 2.0 za pomocą JavaScriptu, zapoznaj się z tą dokumentacją dotyczącą obsługi uprawnień szczegółowych.

Przetestuj zaktualizowaną aplikację pod kątem obsługi uprawnień szczegółowych

1. Opisz wszystkie przypadki, w których użytkownicy mogą odpowiadać na prośby o uprawnienia, oraz oczekiwane działanie aplikacji. Jeśli na przykład użytkownik autoryzuje tylko 2 z 3 żądanych zakresów, aplikacja powinna odpowiednio się zachować.

2. Przetestuj aplikację z włączonymi uprawnieniami szczegółowymi. Szczegółowe uprawnienia można włączyć na 2 sposoby:

   1. Sprawdź ekrany zgody OAuth 2.0 aplikacji, aby zobaczyć, czy uprawnienia szczegółowe są już w niej włączone. W celach testowych możesz też utworzyć w konsoli Google Cloud nowy identyfikator klienta Google OAuth 2.0 dla aplikacji internetowej, na Androida lub na iOS, ponieważ uprawnienia szczegółowe są zawsze włączone w przypadku tych identyfikatorów.

   2. Podczas wywoływania punktów końcowych autoryzacji Google OAuth ustaw parametr enable_granular_consent na true. Niektóre pakiety SDK obsługują ten parametr. W przypadku innych platform sprawdź w dokumentacji, jak ręcznie dodać ten parametr i jego wartość. Jeśli Twoja implementacja nie obsługuje dodawania parametru, możesz utworzyć nowy identyfikator klienta Google OAuth 2.0 dla aplikacji internetowej, aplikacji na Androida lub aplikacji na iOS w konsoli Google Cloud wyłącznie do celów testowych, jak opisano w poprzednim punkcie.

3. Podczas testowania zaktualizowanej aplikacji używaj osobistego konta Google (@gmail.com), a nie konta Workspace. Wynika to z tego, że zmiany w uprawnieniach szczegółowych nie mają obecnie wpływu na aplikacje Workspace Enterprise z przekazywaniem dostępu w całej domenie lub oznaczone jako zaufane. Dlatego testowanie za pomocą konta Workspace z Twojej organizacji może nie wyświetlać nowego ekranu zgody na szczegółowy dostęp zgodnie z oczekiwaniami.