Jak obsługiwać szczegółowe uprawnienia

Omówienie

Dzięki szczegółowym uprawnieniom konsumenci mają większą kontrolę nad danymi na koncie udostępniać każdej aplikacji. Są korzystne zarówno dla użytkowników, jak i deweloperów, ponieważ zapewniają kontrolę, przejrzystość i bezpieczeństwo. Z tego przewodnika dowiesz się, jakie zmiany należy wprowadzić i co zrobić, aby zaktualizować aplikacje i umożliwić im obsługę szczegółowych uprawnień.

Co to są uprawnienia szczegółowe?

Wyobraź sobie, że tworzysz aplikację zwiększającą produktywność, która wymaga dostępu do zakresów e-maila i kalendarza. Twoi użytkownicy możesz chcieć używać Twojej aplikacji tylko w Kalendarzu Google, ale nie w Gmailu. Ze szczegółami protokołu OAuth użytkownicy mogą przyznawać uprawnienia tylko do Kalendarza Google, ale nie do Gmaila. Pozwalając użytkownikom na przyznawanie dostępu do określonych danych, minimalizuje to ryzyko ujawnienia danych i zwiększa precyzję zaufania i zapewnia użytkownikom kontrolę nad ich życiem cyfrowym, stawiając na ochronę prywatności. Ważne jest, zaprojektować aplikację pod kątem takich scenariuszy.

Gdy żądane jest więcej niż 1 zakres bez logowania

Zakresy logowania i niewymagające logowania

W przypadku aplikacji, które żądają zakresów zarówno logowania, jak i bez logowania, użytkownicy najpierw widzą zgodę strona zakresów logowania (email, profile i openid). Po wyrażeniu zgody przez użytkowników na podać podstawowe informacje o tożsamości (imię i nazwisko, adres e-mail i zdjęcie profilowe), szczegółowy ekran zgody dla zakresów niewymagających logowania. W tym przypadku aplikacja musi sprawdzić, które zakresy są przyznane przez użytkowników, i nie może zakładać, że użytkownicy przyznają wszystkie żądane i zakresu. W poniższym przykładzie aplikacja internetowa żąda wszystkich 3 zakresów logowania i Zakres Dysku Google niewymagający logowania. Gdy użytkownicy wyrażą zgodę na zakresy logowania, zobaczą szczegółowy ekran zgody dla uprawnień do Dysku Google:

Więcej niż 1 zakres bez logowania

Gdy aplikacje będą prosić o dodatkowe uprawnienia, użytkownik zobaczy szczegółowy ekran zgody. niż jeden zakres niezwiązany z logowaniem. Użytkownicy mogą wybrać, które uprawnienia chcą przyznać aplikacji. Poniżej znajduje się przykład szczegółowego ekranu akceptacji dotyczącego uprawnień dostęp do wiadomości w Gmailu i danych Kalendarza Google użytkownika:

W przypadku aplikacji, które proszą tylko o zalogowanie się (email, profile i openid), zakres szczegółowy ekran zgody uprawnień nie ma zastosowania. Użytkownicy zatwierdzają lub odrzucają całe logowanie użytkownika. Innymi słowy, jeśli aplikacje żądają tylko zakresów logowania (jeden, dwa lub wszystkie 3), szczegółowy ekran zgody nie ma zastosowania.

W przypadku aplikacji, które wymagają tylko jednego zakresu uprawnień bez logowania, szczegółowy ekran zgody na uprawnienia nie jest dostępny. Innymi słowy, użytkownicy zatwierdzają lub odrzucić całą prośbę, a na ekranie zgody nie będzie żadnego pola wyboru. Tabela poniżej podsumowuje, kiedy wyświetlany jest ekran zgody na szczegółowe uprawnienia.

Sprawdź, czy ta zmiana wpłynie na Twoje aplikacje

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

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

Sprawdź kod aplikacji lub wychodzące połączenie sieciowe, aby określić, czy OAuth 2.0 żądania autoryzacji wysyłane przez aplikację będą powodować wyświetlenie ekranu zgody na szczegółowe uprawnienia. wyświetlana.

Sprawdzanie kodu aplikacji

Sprawdź sekcje kodu aplikacji, w których wywołujesz punkty końcowe autoryzacji OAuth Google, aby poprosić użytkowników o przyznanie uprawnień. Jeśli używasz interfejsu API Google Biblioteki klienta – często możesz sprawdzić, jakie zakresy żąda aplikacja w kliencie. kroków inicjowania. Przykłady znajdziesz w sekcji poniżej. Zapoznaj się z dokumentacji pakietów SDK używanych przez aplikację do obsługi protokołu Google OAuth 2.0. Pozwala ona ustalić, czy danej aplikacji. Aby to zrobić, postępuj zgodnie ze wskazówkami podanymi w poniższych przykładach. odwołania.

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

Sprawdzając połączenia sieciowe, szukaj żądań wysłanych do Google OAuth punktów końcowych autoryzacji i sprawdź parametr scope.

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

• Parametr scope zawiera zakresy logowania i zakresy niezwiązane z logowaniem.

  To przykładowe żądanie zawiera wszystkie 3 zakresy logowania i 1 zakres niebędący zakresem logowania aby wyświetlić metadane 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 niebędący zakresem logowania.

  To przykładowe żądanie zawiera 2 zakresy bez logowania pozwalające wyświetlić Dysk Google użytkownika i zarządzać 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 określisz, że aplikacja wymaga aktualizacji szczegółowych uprawnień, należy wprowadzić w kodzie niezbędne zmiany, by zapewnić dla wielu zakresów. Wszystkie aplikacje powinny być zgodne z tymi sprawdzonymi metodami:

1. Zapoznaj się z Usługi interfejsów API Google: zasady dotyczące danych użytkownika i dbaj o ich przestrzeganie.
2. Poproś o konkretne zakresy potrzebne do wykonania działania. Ty muszą być zgodne z zasadami Google OAuth 2.0, wymaga jedynie zakresu . Nie proś o wielokrotne podczas logowania, chyba że jest to niezbędne do działania głównej funkcji aplikacji. Łączenie w kilku zakresach, zwłaszcza w przypadku użytkowników, którzy pierwszy raz nie znają Twojej funkcji aplikacji, może utrudnić im zrozumienie potrzeb, uprawnień. Może to zwiększyć alarm i zniechęcić użytkowników do dalszego korzystania aplikacji.
3. Przedstaw użytkownikom uzasadnienie, zanim poprosisz o żądania autoryzacji. Wyraźnie wyjaśnij, dlaczego aplikacja potrzebuje żądanego uprawnienia, co zrobisz z danymi użytkownika i jakie korzyści przyniesie użytkownikowi zaakceptowanie prośby. Nasze badania wskazują, że te wyjaśnienia zwiększają zaufanie użytkowników i ich zaangażowanie.
4. Użycie autoryzacja przyrostowa za każdym razem, gdy aplikacja żąda zakresów, aby uniknąć konieczności zarządzania wieloma tokenami dostępu.
5. Sprawdź, które zakresy zostały przyznane przez użytkowników. Gdy żądasz dostępu do wielu zakresów naraz, użytkownicy mogą nie przyznać uprawnień do 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ć wszelkie zakresy odmowy, wyłączając odpowiednie funkcje zabezpieczeń. Przestrzegaj zasad protokołu Google OAuth 2.0 obsługa zgody dla wielu i ponownie prosić użytkownika o zgodę dopiero wtedy, gdy wyraźnie zaznaczy to, z zamiarem użycia konkretnej funkcji, która wymaga tego zakresu.

Zaktualizuj aplikację, aby obsługiwać szczegółowe uprawnienia

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 z najlepszymi praktykami.

Jeśli do interakcji z Google OAuth 2.0 używasz pakietu SDK auth.api.signin z Usług Google Play, możesz użyć funkcji requestPermissions, aby poprosić o najmniejszy zestaw wymaganych zakresów, oraz funkcji hasPermissions, aby sprawdzić, jakie zakresy użytkownik przyznał podczas żądania szczegółowych uprawnień.

Aplikacje rozszerzeń do Chrome

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

W tym przykładzie pokazujemy, jak prawidłowo obsługiwać szczegółowe uprawnienia.

manifest.json

Przykładowy plik manifestu deklaruje 2 zakresy dostępu bez logowania 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"]
  }
}

Niewłaściwe 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 zaktualizuj swoją aplikację tak, aby obsługiwała szczegółowe uprawnienia na podstawie sprawdzonych metodach.

Jeśli używasz biblioteki logowania przez Google na urządzeniach z iOS i macOS do interakcji z protokołem Google OAuth 2.0, zapoznaj się z dokumentacja dotycząca obsługi szczegółowej uprawnień.

Aplikacje internetowe

Zapoznaj się z dokumentacją pakietów SDK, których używasz do interakcji z Google OAuth 2.0 zaktualizuj swoją aplikację tak, aby obsługiwała szczegółowe uprawnienia na podstawie sprawdzonych metodach.

Dostęp po stronie serwera (w trybie offline)

Ten fragment kodu pokazuje przykładowe żądanie Node.js z 2 zakresami dostępu bez logowania. Użytkownicy będą zobaczyć szczegółowy ekran zgody.

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

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 przewodnik po aplikacjach internetowych po stronie serwera, z którego dowiesz się, jak uzyskać dostęp do interfejsów API Google z aplikacji serwerowych.

Dostęp tylko po stronie klienta

• Dotyczy aplikacji korzystających z usług tożsamości Google. biblioteki JavaScript do interakcji z protokołem Google OAuth 2.0, zapoznaj się z tym dokumentacja obsługi szczegółowych uprawnień.
• Dla aplikacji, które bezpośrednio wykonują wywołania przy użyciu JavaScriptu do autoryzacji Google OAuth 2.0 punktów końcowych, sprawdź to dokumentacja obsługi szczegółowych uprawnień.

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

1. Określ wszystkie przypadki, w których użytkownicy mogą odpowiedzieć na prośby o uprawnienia, a także oczekiwane działanie Twojej aplikacji. Jeśli na przykład użytkownik autoryzuje tylko 2 z 3 wymaganych zakresów, aplikacja powinna się odpowiednio zachować.
2. Testuj aplikację z włączoną szczegółową kontrolą uprawnień. Dostęp do szczegółowych uprawnień można włączyć na 2 sposoby:
   1. Przejrzyj ekrany akceptacji OAuth 2.0 w swojej aplikacji, by dowiedzieć się, szczegółowe uprawnienia są już włączone aplikacji. Możesz też utworzyć nowy identyfikator klienta Google OAuth 2.0 w przeglądarce albo na Androida lub iOS. w konsoli Google Cloud do celów testowych, bo szczegółowe uprawnienia są zawsze nie są dla nich włączone.
   2. Ustaw parametr enable_granular_consent do true podczas wywoływania Google OAuth między punktami końcowymi autoryzacji. Niektóre pakiety SDK obsługują ten parametr. W przypadku innych użytkowników zapoznaj się z dokumentacją, aby dowiedzieć się, jak dodać ten parametr ręcznie ustawić jego wartość. Jeśli Twoja implementacja nie obsługuje dodawania parametru, możesz utworzyć nowy identyfikator klienta OAuth 2.0 Google na potrzeby testów w przeglądarce, na Androidzie lub na iOS w Google Cloud Console, zgodnie z opisem w poprzednim punkcie.
3. Podczas testowania zaktualizowanej aplikacji użyj osobistego konta Google (@gmail.com) zamiast konto Workspace. Dzieje się tak, ponieważ aplikacje Workspace Enterprise zawierają przekazywanie uprawnień w całej domenie lub oznaczone jako Zaufane obecnie nie mają wpływu zmiany szczegółowych uprawnień. Dlatego testowanie w Workspace na koncie Twojej organizacji może nie wyświetlać się nowy szczegółowy ekran zgody.