Jak obsługiwać szczegółowe uprawnienia

Przegląd

Dzięki szczegółowym uprawnieniom konsumenci mają ściślejszą kontrolę nad danymi konta, które chcą udostępniać każdej aplikacji. Korzystanie z nich jest korzystne zarówno dla użytkowników, jak i deweloperów, bo zapewnia większą kontrolę, przejrzystość i bezpieczeństwo. Ten przewodnik pomoże Ci zapoznać się ze zmianami i czynnościami, które należy wykonać, aby zaktualizować aplikacje tak, aby obsługiwały szczegółowe uprawnienia.

Czym są szczegółowe uprawnienia?

Wyobraź sobie, że tworzysz aplikację zwiększającą produktywność, która wymaga dostępu zarówno do poczty e-mail, jak i kalendarza. Użytkownicy mogą chcieć używać Twojej aplikacji tylko do obsługi Kalendarza Google, a nie Gmaila. Dzięki szczegółowym uprawnieniom dotyczącym protokołu OAuth użytkownicy mogą przyznawać uprawnienia tylko do Kalendarza Google, ale nie do Gmaila. Pozwalając użytkownikom na dostęp do określonych danych, minimalizuje to ich ekspozycję, zwiększa zaufanie i zapewnia użytkownikom kontrolę nad swoim cyfrowym życiem na pierwszym miejscu. Ważne jest, aby zaprojektować aplikację tak, aby obsługiwała takie scenariusze.

Gdy zażądano więcej niż 1 zakresu niewymagającego logowania

Zakresy logowania i inne niż logowanie

W przypadku aplikacji, które żądają zarówno zakresów logowania, jak i innych, użytkownicy najpierw widzą stronę z prośbą o zgodę na zakresy logowania (email, profile i openid). Gdy użytkownicy zgodzą się na udostępnienie podstawowych informacji o tożsamości (imię i nazwisko, adres e-mail oraz zdjęcie profilowe), zobaczą szczegółowy ekran zgody dla zakresów niewymagających logowania. W tym 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 oraz zakresu niewymagającego logowania z Dysku Google. Gdy użytkownicy wyrażą zgodę na zakresy logowania, zobaczą ekran z szczegółowymi uprawnieniami dotyczącymi uprawnień do Dysku Google:

Więcej niż 1 zakres niewymagający logowania

Gdy aplikacje żądają więcej niż jednego zakresu niewymagającego logowania, użytkownikom wyświetla się szczegółowy ekran zgody uprawnień. Użytkownicy mogą wybrać uprawnienia, które chcą udostępnić aplikacji. Poniżej znajdziesz przykładowy szczegółowy ekran zgody uprawnień, który prosi o dostęp do wiadomości z Gmaila i danych z Kalendarza Google użytkownika:

W przypadku aplikacji, które żądają tylko zakresów logowania (email, profile i openid), ekran zgody #inspect-your-application-codegranular nie ma zastosowania. Użytkownicy mogą zatwierdzić lub odrzucić całą prośbę o zalogowanie się. Inaczej mówiąc, jeśli aplikacje żądają tylko zakresów logowania (jeden, dwa lub wszystkie), szczegółowy ekran zgody nie ma zastosowania.

W przypadku aplikacji, które żądają tylko 1 zakresu niezwiązanego z logowaniem, szczegółowy ekran zgody nie ma zastosowania. Oznacza to, że użytkownicy muszą zatwierdzić lub odrzucić całą prośbę, a na ekranie zgody nie będzie żadnego pola wyboru. W tabeli poniżej znajdziesz podsumowanie, kiedy wyświetla się ekran zgody na szczegółowe uprawnienia.

Określ, czy problem dotyczy Twoich aplikacji

Przeprowadź szczegółową kontrolę wszystkich sekcji aplikacji, w których używane są punkty końcowe autoryzacji Google OAuth 2.0 na potrzeby żądań uprawnień. Zwróć uwagę na te, które żądają 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 przypadek, gdy użytkownicy autoryzują tylko niektóre zakresy.

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

Sprawdź kod aplikacji lub wychodzące wywołanie sieciowe, aby ustalić, czy żądania autoryzacji wysyłane przez Twoją aplikację z użyciem protokołu Google OAuth 2.0 powodują wyświetlenie ekranu zgody szczegółowych uprawnień.

Sprawdzanie kodu aplikacji

Sprawdź sekcje kodu aplikacji, w których wywołujesz punkty końcowe autoryzacji OAuth Google, aby prosić użytkowników o pozwolenie. Jeśli używasz jednej z bibliotek klienta interfejsów API Google, w krokach inicjowania klienta często możesz sprawdzić, jakie zakresy żądania są wysyłane przez aplikację. W następnej sekcji znajdziesz kilka przykładów. Aby określić, czy dotyczy to Twojej aplikacji, zapoznaj się z dokumentacją pakietów SDK używanych przez Twoją aplikację do obsługi Google OAuth 2.0. Aby dowiedzieć się, czy dotyczy to Twojej aplikacji, zapoznaj się ze wskazówkami podanymi 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 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
});

Sprawdź wychodzące połączenie sieciowe

Podczas badania wywołań sieciowych szukaj żądań wysyłanych do punktów końcowych autoryzacji Google OAuth i sprawdzaj parametr scope.

Te wartości cause, że wyświetla się ekran zgody na szczegółowe uprawnienia.

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

  Poniższe przykładowe żądanie zawiera wszystkie 3 zakresy logowania i 1 zakres inny niż logowanie umożliwiający wyświetlenie 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 niewymagający logowania.

  To przykładowe żądanie zawiera 2 zakresy niewymagające logowania, 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 obsługi szczegółowych uprawnień

Jeśli determine, że Twoja aplikacja wymaga aktualizacji, aby obsługiwała szczegółowe uprawnienia, musisz wprowadzić w kodzie niezbędne zmiany, aby prawidłowo obsługiwać zgodę w wielu zakresach. Wszystkie aplikacje powinny być zgodne z tymi sprawdzonymi metodami:

1. Zapoznaj się z Zasadami dotyczącymi danych użytkownika w usługach interfejsów API Google i upewnij się, że ich przestrzegasz.
2. Wyślij prośbę o konkretne zakresy wymagane do wykonania zadania. Musisz przestrzegać zasad Google OAuth 2.0, które żądają tylko potrzebnych zakresów. Nie pytaj o wiele zakresów podczas logowania, chyba że jest to niezbędne do działania głównej funkcji aplikacji. Łączenie kilku zakresów (zwłaszcza dla nowych użytkowników, którzy nie znają funkcji aplikacji) może utrudniać zrozumienie potrzeby tych uprawnień. Może to budzić alarmy i zniechęcać użytkowników do dalszego korzystania z Twojej aplikacji.
3. Zanim poprosisz użytkowników o autoryzację, podaj uzasadnienie. Wyjaśnij, dlaczego Twoja aplikacja potrzebuje pozwolenia, co zrobisz z danymi użytkownika i jakie korzyści przyniesie mu zatwierdzenie Twojej prośby. Z naszych badań wynika, że te wyjaśnienia zwiększają zaufanie i zaangażowanie użytkowników.
4. Używaj przyrostowej autoryzacji, gdy aplikacja żąda zakresów, aby uniknąć konieczności zarządzania wieloma tokenami dostępu.
5. Sprawdź, które zakresy zostały przyznane użytkownikom. Gdy żądasz wielu zakresów naraz, użytkownicy mogą nie przyznawać wszystkich zakresów, jakie żąda aplikacja. Aplikacja powinna zawsze sprawdzać, które zakresy zostały przyznane przez użytkownika, i obsługiwać wszystkie zakresy odmowy, wyłączając odpowiednie funkcje. Postępuj zgodnie z zasadami Google OAuth 2.0 dotyczącymi obsługiwania zgody dla wielu zakresów i poproś użytkownika o ponowne wyrażenie zgody dopiero wtedy, gdy wyraźnie wskaże on zamiar korzystania z 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 Google OAuth 2.0, i zaktualizuj aplikację, aby obsługiwała szczegółowe uprawnienia zgodnie ze sprawdzonymi metodami.

Jeśli do interakcji z Google OAuth 2.0 używasz pakietu SDK auth.api.signin w Usługach Google Play, możesz użyć funkcji requestPermissions, aby zażądać najmniejszego zestawu wymaganych zakresów, a funkcji hasPermissions do sprawdzić, który zakres uprawnień przyznanych użytkownikowi podczas wysyłania żądań szczegółowych uprawnień.

Aplikacje rozszerzeń do Chrome

Do współpracy z Google OAuth 2.0 używaj interfejsu Chrome Identity API zgodnie ze sprawdzonymi metodami.

Z przykładu poniżej dowiesz się, jak prawidłowo obsługiwać szczegółowe uprawnienia.

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

Właściwe 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 Google OAuth 2.0, i zaktualizuj aplikację, aby obsługiwała szczegółowe uprawnienia zgodnie ze sprawdzonymi metodami.

Jeśli do interakcji z Google OAuth 2.0 używasz biblioteki Google Sign-In na iOS i 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 Google OAuth 2.0, i zaktualizuj aplikację, aby obsługiwała szczegółowe uprawnienia zgodnie ze sprawdzonymi metodami.

Dostęp po stronie serwera (offline)

Poniższy fragment kodu przedstawia przykładowe żądania NodeJS w zakresie 2 zakresów niezwiązanych z logowaniem. Użytkownicy zobaczą szczegółowy ekran zgody na 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);
}

Właściwe 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 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 do interakcji z Google OAuth 2.0 używają biblioteki JavaScript usług tożsamości Google, zapoznaj się z tą dokumentacją dotyczącą obsługi szczegółowych uprawnień.
• W przypadku aplikacji, które bezpośrednio wywołują za pomocą JavaScriptu punkty końcowe autoryzacji OAuth 2.0, zapoznaj się z tą dokumentacją dotyczącą obsługi szczegółowych uprawnień.

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

1. Określ 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 żądanych zakresów, aplikacja powinna działać zgodnie z oczekiwaniami.
2. Przetestuj swoją aplikację z włączonymi szczegółowymi uprawnieniami. Szczegółowe uprawnienia można włączyć na 2 sposoby:
   1. Sprawdź ekrany zgody OAuth 2.0 Twojej aplikacji, aby sprawdzić, czy są dla niej włączone szczegółowe uprawnienia. Za pomocą konsoli Google Cloud możesz też utworzyć nowy identyfikator klienta Google OAuth 2.0 w przeglądarce, na Androida lub iOS, ponieważ zawsze są w nich włączone szczegółowe uprawnienia.
   2. Ustaw parametr enable_granular_consent na true podczas wywoływania punktów końcowych autoryzacji Google OAuth. Niektóre pakiety SDK bezpośrednio obsługują ten parametr. Jeśli nie chcesz zmieniać tego parametru i jego wartości, zapoznaj się z dokumentacją. Jeśli Twoja implementacja nie obsługuje dodawania tego parametru, możesz utworzyć za pomocą konsoli Google Cloud nowy identyfikator klienta Google OAuth 2.0 na potrzeby internetu, Androida lub iOS, tylko do celów testowych, zgodnie z tym, co pisaliśmy powyżej.