Jak obsługiwać szczegółowe uprawnienia

Przegląd

Dzięki szczegółowym uprawnieniom konsumenci mają większą kontrolę nad tym, jakie dane konta chcą udostępniać poszczególnym aplikacjom. Zapewniają one użytkownikom i deweloperom większą kontrolę, przejrzystość i bezpieczeństwo. Ten przewodnik pomoże Ci zrozumieć niezbędne zmiany i kroki, które musisz wykonać, aby zaktualizować aplikacje i umożliwić im obsługę szczegółowych uprawnień.

Czym są szczegółowe uprawnienia?

Wyobraź sobie, że tworzysz aplikację zwiększającą produktywność, która wymaga dostępu do poczty e-mail i kalendarza. Użytkownicy mogą chcieć korzystać z Twojej aplikacji tylko w Kalendarzu Google, a nie w Gmailu. Dzięki szczegółowym uprawnieniom OAuth użytkownicy mogą przyznać uprawnienia tylko do Kalendarza Google, ale nie do Gmaila. Umożliwienie użytkownikom przyznawania dostępu do określonych danych minimalizuje ich narażenie, zwiększa zaufanie i daje użytkownikom kontrolę nad ich życiem cyfrowym z uwzględnieniem ochrony prywatności. Ważne jest, aby zaprojektować aplikację tak, aby radziła sobie w takich sytuacjach.

Gdy żądany jest więcej niż 1 zakres inny niż logowanie

Zakresy logowania i zakresy bez logowania

W przypadku aplikacji, które proszą o zakresy logowania i zakresy inne niż logowanie, użytkownicy najpierw widzą stronę zgody na zakresy logowania (email, profile i openid). Po wyrażeniu zgody na udostępnianie podstawowych informacji o tożsamości (imienia i nazwiska, adresu e-mail i zdjęcia profilowego) użytkownicy zobaczą ekran zgody na szczegółowe uprawnienia w zakresach 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 logowania do Dysku Google. Gdy użytkownicy wyrażą zgodę na zakresy logowania, zobaczą ekran zgody na szczegółowe uprawnienia do Dysku Google:

Więcej niż jeden zakres inny niż Sign-In

Gdy aplikacje będą prosić o więcej niż 1 zakres inny niż logowanie, użytkownikom będzie wyświetlany ekran zgody na szczegółowe uprawnienia. Użytkownicy mogą wybrać uprawnienia, które chcą przyznać aplikacji, aby udostępniać jej dane. Poniżej znajduje się przykład ekranu zgody na szczegółowe uprawnienia, który prosi o dostęp do wiadomości Gmaila i danych z Kalendarza Google użytkownika:

W przypadku aplikacji, które wymagają tylko zakresów logowania (email, profile i openid), ekran zgody na szczegółowe uprawnienia nie ma zastosowania. Użytkownicy zatwierdzają lub odrzucają całą prośbę o zalogowanie. Innymi słowy, jeśli aplikacje proszą tylko o zakresy logowania (jeden, dwa lub wszystkie trzy), ekran zgody na szczegółowe uprawnienia nie ma zastosowania.

W przypadku aplikacji, które proszą tylko o jeden zakres niewymagający logowania, szczegółowy ekran zgody na uprawnienia nie ma zastosowania. Innymi słowy, użytkownicy zatwierdzają lub odrzucają całą prośbę i na ekranie zgody nie ma pola wyboru. W tabeli poniżej znajdziesz podsumowanie sytuacji, w których wyświetla się ekran z prośbą o zgodę na wykorzystanie danych.

Sprawdzanie, czy zmiana ma wpływ na Twoje aplikacje

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

Jak sprawdzić, czy aplikacja korzysta z wielu zakresów

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

Sprawdzanie kodu aplikacji

Sprawdź te fragmenty kodu aplikacji, w których wywołujesz punkty końcowe autoryzacji Google OAuth, aby poprosić użytkowników o uprawnienia. Jeśli korzystasz z jednej z bibliotek klienta interfejsów API Google, zakresy, o które prosi Twoja aplikacja, znajdziesz zwykle w krokach inicjowania klienta. Przykłady znajdziesz w sekcji poniżej. Aby sprawdzić, czy problem dotyczy Twojej aplikacji, zapoznaj się z dokumentacją pakietów SDK, których używa Twoja aplikacja do obsługi protokołu Google OAuth 2.0. Skorzystaj z wskazówek podanych w przykładach poniżej.

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

Sprawdzanie wychodzącego połączenia sieciowego

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

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

• Parametr scope zawiera zakresy logowania i zakresy inne niż logowanie.

  Przykładowe żądanie zawiera wszystkie 3 zakresy logowania i 1 zakres inny niż logowanie do wyświetlania 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, który nie jest zakresem logowania.

  Przykładowe żądanie zawiera 2 zakresy inne niż logowanie, które umożliwiają wyświetlanie metadanych Dysku Google użytkownika i zarządzanie konkretnymi 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 obsługi szczegółowych uprawnień

Jeśli ustalisz, że Twoja aplikacja wymaga aktualizacji, aby obsługiwać szczegółowe uprawnienia, wprowadź niezbędne zmiany w kodzie, aby prawidłowo obsługiwać zgodę użytkowników 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 określone zakresy, które są potrzebne do wykonania zadania. Musisz przestrzegać zasad Google dotyczących protokołu OAuth 2.0, które mówią, że możesz prosić tylko o zakresy, których potrzebujesz. Unikaj proszenia o wiele zakresów podczas logowania, chyba że jest to niezbędne do działania podstawowych funkcji 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. Uzasadnij użytkownikom, dlaczego prosisz o autoryzację. Wyraźnie 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 te wyjaśnienia zwiększają zaufanie i zaangażowanie użytkowników.
4. Używaj autoryzacji przyrostowej, gdy aplikacja wysyła żądania zakresów, aby uniknąć zarządzania wieloma tokenami dostępu.
5. Sprawdź, które zakresy zostały przyznane przez użytkowników. Gdy użytkownicy proszą o wiele zakresów naraz, mogą nie przyznać wszystkich zakresów, o które prosi Twoja aplikacja. Aplikacja powinna zawsze sprawdzać, które zakresy zostały przyznane przez użytkownika, i obsługiwać odmowę przyznania zakresów przez wyłączanie odpowiednich funkcji. Postępuj zgodnie z zasadami Google dotyczącymi OAuth 2.0 w zakresie obsługi zgody na wiele zakresów i ponownie proś użytkownika o zgodę tylko wtedy, gdy wyraźnie wskaże on zamiar użycia konkretnej funkcji, która wymaga danego zakresu.

Aktualizowanie aplikacji w celu obsługi szczegółowych uprawnień

Aplikacje na Androida

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

Jeśli do interakcji z Google OAuth 2.0 używasz pakietu SDK auth.api.signin z Usług Play, możesz użyć funkcji requestPermissions do żądania najmniejszego zestawu potrzebnych zakresów oraz funkcji hasPermissions do sprawdzania, które zakresy użytkownik przyznał podczas żądania szczegółowych uprawnień.

Aplikacje rozszerzeń do Chrome

Do pracy z Google OAuth 2.0 opartej na sprawdzonych metodach należy używać interfejsu Chrome Identity API.

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

manifest.json

Przykładowy plik manifestu deklaruje 2 zakresy inne niż logowanie w przypadku 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.
            ...
          }
      });
});

Prawidłowe podejście

...
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 protokołem OAuth 2.0 Google, i zaktualizuj aplikację, aby obsługiwała szczegółowe uprawnienia zgodnie z najlepszymi praktykami.

Jeśli do interakcji z Google OAuth 2.0 używasz biblioteki Google Sign-In for iOS and macOS, zapoznaj się z dokumentacją dotyczącą obsługi szczegółowych uprawnień.

Aplikacje internetowe

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

Dostęp po stronie serwera (offline)

Ten fragment kodu pokazuje przykład w NodeJS, w którym wysyłane są 2 zakresy niepowią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 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);
}

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

Zapoznaj się z  przewodnikiem po aplikacjach internetowych po stronie serwera, aby dowiedzieć się, jak uzyskiwać 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 do interakcji z protokołem Google OAuth 2.0 używają biblioteki JavaScript Google Identity Services, zapoznaj się z tą dokumentacją dotyczącą obsługi szczegółowych uprawnień.
• W przypadku aplikacji, które bezpośrednio wywołują punkty końcowe autoryzacji OAuth 2.0 Google za pomocą JavaScriptu, zapoznaj się z tą dokumentacją dotyczącą obsługi szczegółowych uprawnień.

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

1. Opisz wszystkie przypadki, w których użytkownicy mogą odpowiadać na prośby o przyznanie uprawnień, oraz oczekiwane działanie aplikacji. Jeśli na przykład użytkownik autoryzuje tylko 2 z 3 zakresów, Twoja aplikacja powinna odpowiednio się zachować.
2. Przetestuj aplikację z włączonymi szczegółowymi uprawnieniami. Uprawnienia szczegółowe można włączyć na 2 sposoby:
   1. Sprawdź ekrany zgody OAuth 2.0 w swojej aplikacji, aby dowiedzieć się, czy szczegółowe uprawnienia są już włączone w Twojej aplikacji. W celach testowych możesz też utworzyć nowy identyfikator klienta OAuth 2.0 Google dla aplikacji internetowej, na Androida lub iOS w konsoli Google Cloud, ponieważ w jego przypadku zawsze włączone są szczegółowe uprawnienia.
   2. Podczas wywoływania punktów końcowych autoryzacji interfejsu 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 OAuth 2.0 Google dla aplikacji internetowych, na Androida lub iOS w Google Cloud Console tylko na potrzeby testów, jak podano w poprzednim punkcie.
3. Podczas testowania zaktualizowanej aplikacji używaj osobistego konta Google (@gmail.com), a nie konta Workspace. Wynika to z faktu, że aplikacje Workspace Enterprise z delegowaniem uprawnień w całej domenie lub oznaczone jako zaufane nie podlegają obecnie zmianom w zakresie szczegółowych uprawnień. Dlatego testowanie za pomocą konta Workspace w Twojej organizacji może nie wyświetlać nowego ekranu szczegółowej zgody zgodnie z zamierzeniami.