Come gestire le autorizzazioni granulari

Panoramica

Con autorizzazioni granulari, i consumatori ottengono un controllo più granulare sui dati dell'account. che decidono di condividere con ogni app. Sono utili sia per gli utenti che per gli sviluppatori, fornendo controllo, trasparenza e sicurezza. Questa guida ti aiuterà a comprendere le necessarie modifiche e passaggi per aggiornare correttamente le applicazioni in modo da gestire autorizzazioni granulari.

Che cos'è l'autorizzazione granulare?

Immagina di sviluppare un'app di produttività che richiede ambiti sia per l'email che per il calendario. I tuoi utenti potresti voler utilizzare la tua applicazione solo per Google Calendar, ma non per Gmail. Con OAuth granulare autorizzazioni, gli utenti possono scegliere di concedere l'autorizzazione solo a Google Calendar e non a Gmail. Consentendo agli utenti di concedere l'accesso a dati specifici, questa impostazione riduce al minimo l'esposizione dei dati, rafforza e offre agli utenti un controllo della loro vita digitale incentrato sulla privacy. È importante progettare la tua applicazione per gestire questi scenari.

Quando vengono richiesti più ambiti senza accesso

Ambiti di accesso e non di accesso

Per le applicazioni che richiedono ambiti di accesso e non, gli utenti vedono prima il consenso pagina per Ambiti di accesso (email, profile e openid). Dopo che gli utenti hanno dato il consenso condividono le informazioni di base sull'identità (nome, indirizzo email e foto del profilo), gli utenti vedranno una schermata di consenso granulare per gli ambiti non Accesso. In questo caso, l'applicazione deve verificare quali ambiti vengono concessi dagli utenti e non può presumere che gli utenti concedano tutte le richieste ambiti. Nell'esempio seguente, l'applicazione web richiede tutti e tre gli ambiti di accesso e una Ambito senza accesso a Google Drive. Dopo che gli utenti acconsentono agli ambiti di accesso, gli utenti vedranno la schermata per il consenso granulare delle autorizzazioni per Google Drive:

Più di un ambito senza accesso

Quando le applicazioni ne richiedono di più, agli utenti viene mostrata una schermata di consenso granulare per il consenso degli utenti. rispetto a un ambito senza accesso. Gli utenti possono selezionare le autorizzazioni da approvare per la condivisione con l'applicazione. Di seguito è riportato un esempio di schermata granulare per il consenso delle autorizzazioni accesso ai messaggi Gmail e ai dati di Google Calendar dell'utente:

Per le applicazioni che richiedono solo l'accesso Sign-In specifici (email, profile e openid), il livello la schermata per il consenso alle autorizzazioni non è applicabile. Gli utenti approvano o rifiutano l'intera richiesta di accesso. In altre parole, se le applicazioni richiedono solo gli ambiti di accesso (uno, due o tutti tre), la schermata per il consenso granulare non è applicabile.

Per le applicazioni che richiedono un solo ambito senza accesso, il report schermata per il consenso delle autorizzazioni non è applicabile. In altre parole, gli utenti approvano o rifiutare l'intera richiesta e la schermata di consenso non contiene una casella di controllo. La tabella seguente riepiloga la schermata di consenso granulare delle autorizzazioni.

Numero di ambiti di accesso	Numero di ambiti senza accesso	Schermata granulare per il consenso alle autorizzazioni
1-3	0	Non applicabile
1-3	1+	Applicabile
0	1	Non applicabile
0	2+	Applicabile

Determina se le tue applicazioni sono interessate

Svolgi un'analisi approfondita di tutte le sezioni della tua applicazione in cui Per le richieste di autorizzazione vengono utilizzati gli endpoint di autorizzazione Google OAuth 2.0. Fai attenzione a Quelli che richiedono più ambiti quando attivano schermate granulari per il consenso delle autorizzazioni presentati agli utenti. In questi casi, assicurati che il codice sia in grado di gestire il caso in cui gli utenti autorizzare alcuni ambiti.

Come determinare se la tua applicazione utilizza più ambiti

Esamina il codice dell'app o chiamata di rete in uscita per determinare se Google OAuth 2.0 Le richieste di autorizzazione effettuate dalla tua app causeranno la schermata di consenso granulare delle autorizzazioni da mostrare.

Ispeziona il codice dell'applicazione

Esamina le sezioni del codice dell'applicazione in cui effettui chiamate al servizio OAuth di Google endpoint di autorizzazione per richiedere l'autorizzazione agli utenti. Se usi una delle API di Google nelle librerie client, spesso puoi trovare gli ambiti delle richieste dell'applicazione nel client passaggi di inizializzazione. Nella sezione che segue sono riportati alcuni esempi. Devi fare riferimento alle documentazione degli SDK utilizzati dalla tua applicazione per gestire Google OAuth 2.0 al fine di determinare se l'applicazione è interessata, utilizzando le indicazioni mostrate nei seguenti esempi come riferimento.

Servizi di identità Google

I seguenti Servizi di identità Google Lo snippet di codice della libreria JavaScript inizializza TokenClient con più in ambiti non di accesso. La schermata per il consenso granulare viene visualizzata quando sul web l'app richiede l'autorizzazione agli utenti.

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

Python

Il seguente snippet di codice utilizza il modulo google-auth-oauthlib.flow per creare la richiesta di autorizzazione; Il parametro scope include due in ambiti non di accesso. La schermata per il consenso granulare viene visualizzata quando sul web l'applicazione richiede l'autorizzazione agli utenti.

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'])

Node.js

Lo snippet di codice riportato di seguito crea un oggetto google.auth.OAuth2, che definisce nella richiesta di autorizzazione il cui parametro scope include due in ambiti non di accesso. La schermata per il consenso granulare viene visualizzata quando l'app web richiede l'autorizzazione agli utenti.

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

Ispezionare la chiamata di rete in uscita

Il metodo di ispezione delle chiamate di rete varia in base al tuo un tipo di client dell'applicazione.

• Applicazione web - esaminare l'attività di rete su Chrome
• Android – Ispezionare il traffico di rete con Network Inspector
• App di Chrome
  • Vai alla sezione Estensioni di Chrome
  • Seleziona la casella di controllo Modalità sviluppatore in alto a destra. angolo della pagina dell'estensione
  • Seleziona l'estensione che vuoi monitorare
  • Fai clic sul link della pagina di sfondo nel Sezione Esamina le visualizzazioni della pagina dell'estensione
  • Si aprirà un popup Strumenti per sviluppatori in cui potrai per monitorare il traffico di rete Scheda Network (Rete)
• iOS: Analisi del traffico HTTP con gli strumenti
• Piattaforma UWP (Universal Windows Platform) - Ispezionare il traffico di rete in Visual Studio
• App desktop: usa uno strumento di acquisizione della rete disponibile per il sistema operativo per cui è stata sviluppata l'app

Durante l'ispezione delle chiamate di rete, cerca le richieste inviate a Google OAuth endpoint di autorizzazione ed esamina il parametro scope.

Questi valori causano la visualizzazione della schermata di consenso granulare per le autorizzazioni.

• Il parametro scope contiene gli ambiti di accesso e quelli di altro tipo.

  Una seguente richiesta di esempio contiene tutti e tre gli ambiti di accesso e un ambito non di accesso per visualizzare i metadati dei file di Google Drive dell'utente:

  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

• Il parametro scope contiene più di un ambito non di accesso.

  Una seguente richiesta di esempio contiene due ambiti non di accesso per visualizzare Google Drive dell'utente i metadati e gestire file specifici di Google Drive:

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 practice per gestire autorizzazioni granulari

Se determina che la tua applicazione deve essere aggiornata per gestire autorizzazioni granulari, devi apportare gli aggiornamenti necessari al codice per gestire correttamente il consenso per più ambiti. Tutte le applicazioni devono rispettare le seguenti best practice:

1. Esamina Servizi API di Google: norme relative ai dati utente e assicurati di rispettarle.
2. Richiedi gli ambiti specifici necessari per un'attività. Tu devono rispettare i criteri Google OAuth 2.0 che richiedere solo gli ambiti necessaria. Dovresti evitare di chiedere ambiti al momento dell'accesso, a meno che non siano essenziali per la funzionalità di base dell'app. Raggruppamento diversi ambiti insieme, in particolare per i nuovi utenti che non conoscono dell'applicazione, può rendere difficile per loro comprendere l'esigenza autorizzazioni aggiuntive. Ciò può far aumentare gli allarmi e impedire agli utenti di interagire ulteriormente con il tuo un'applicazione.
3. Fornisci una giustificazione agli utenti prima di chiedere richiesta di autorizzazione. Spiega chiaramente perché la tua applicazione ha bisogno dell'autorizzazione richiesta. cosa farai con i dati dell'utente e in che modo l'utente trarrà vantaggio dall'approvazione della richiesta. La nostra ricerca indica che queste spiegazioni aumentano la fiducia e il coinvolgimento degli utenti.
4. Usa autorizzazione incrementale ogni volta che l'applicazione richiede ambiti per evitare di dover gestire più token di accesso.
5. Verifica gli ambiti a cui sono stati concessi gli utenti. Quando richiedi più ambiti contemporaneamente, gli utenti possono non concedere tutti gli ambiti richiesti dalla tua app. La tua app deve sempre controlla quali ambiti sono stati concessi dall'utente e gestisci gli eventuali rifiuti di ambiti disattivando le funzionalità di machine learning. Segui i criteri Google OAuth 2.0 su per la gestione del consenso gli ambiti e chiedere nuovamente il consenso all'utente solo dopo che lo ha indicato in modo chiaro. l'intento di utilizzare la funzionalità specifica che richiede l'ambito.

Aggiorna l'applicazione per gestire autorizzazioni granulari

App per Android

Consulta la documentazione degli SDK che utilizzi per interagire con Google OAuth 2.0 e aggiornare l'applicazione per gestire autorizzazioni granulari in base best practice.

Se utilizzi auth.api.signin SDK di Play Services per interagire con Google OAuth 2.0, puoi utilizzare requestPermissions: per richiedere l'insieme più piccolo di ambiti necessario, e ai hasPermissions per controllare gli ambiti concessi dall'utente quando richiedendo autorizzazioni granulari.

Applicazioni con estensioni di Chrome

Dovresti usare Google Chrome API Identity per funzionare con Google OAuth 2.0 sulla base di best practice.

L'esempio seguente mostra come gestire correttamente le autorizzazioni granulari.

manifest.json

Il file manifest di esempio dichiara due ambiti non di accesso per l'estensione di Chrome un'applicazione.

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

Approccio errato

Tutto o niente

Gli utenti fanno clic sul pulsante per avviare il processo di autorizzazione. Lo snippet di codice presuppone agli utenti viene presentata l'istanza "tutto o niente" schermata per il consenso per i due ambiti specificati in manifest.json file. Trascura di verificare quali ambiti sono stati concessi dagli utenti.

oauth.js

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

Approccio corretto

Ambiti più piccoli

Seleziona l'insieme più piccolo di ambiti necessario

L'applicazione deve richiedere solo l'insieme più piccolo di ambiti necessario. Consigliato che la tua applicazione richieda un ambito alla volta quando è necessario completare un'attività.

In questo esempio, si presume che entrambi gli ambiti siano dichiarati nell'manifest.json sono gli ambiti più piccoli necessari. Il file oauth.js utilizza Chrome API Identity per avviare il processo di autorizzazione con Google. Devi attivare attivare autorizzazioni granulari, in modo che gli utenti abbiano maggiore controllo quando concedono autorizzazioni un'applicazione. L'applicazione dovrebbe gestire correttamente la risposta degli utenti controllando quali ambiti autorizzano gli utenti.

oauth.js

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

Applicazioni iOS, iPadOS e macOS

Consulta la documentazione degli SDK che utilizzi per interagire con Google OAuth 2.0 e aggiornare l'applicazione per gestire autorizzazioni granulari in base best practice.

Se utilizzi la libreria Accedi con Google per iOS e macOS per interagire con Google OAuth 2.0, devi rivedere documentazione sulla gestione dei dati autorizzazioni aggiuntive.

Applicazioni web

Consulta la documentazione degli SDK che utilizzi per interagire con Google OAuth 2.0 e aggiornare l'applicazione per gestire autorizzazioni granulari in base best practice.

Accesso lato server (offline)

La modalità di accesso lato server (offline) richiede le seguenti operazioni:

• Supporta un server e definisci un endpoint accessibile pubblicamente per ricevere l'autorizzazione le API nel tuo codice.
• Configura il URI di reindirizzamento dell'endpoint pubblico della console Google Cloud.

Il seguente snippet di codice mostra un esempio NodeJS che richiede due ambiti non di accesso. Gli utenti consulta la schermata per il consenso granulare.

Approccio errato

Tutto o niente

Gli utenti vengono reindirizzati all'URL di autorizzazione. Lo snippet di codice presuppone che gli utenti vengano presentati con l'espressione "tutto o niente" schermata per il consenso per i due ambiti specificati in l'arrangiamento scopes. Trascura di verificare quali ambiti sono stati concessi dagli utenti.

main.js

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

Approccio corretto

Ambito più piccolo

Seleziona l'insieme più piccolo di ambiti necessario

L'applicazione deve richiedere solo l'insieme più piccolo di ambiti necessario. Consigliato che la tua applicazione richieda un ambito alla volta quando è necessario completare un'attività. Ogni volta che la tua applicazione richiede ambiti, deve utilizzare autorizzazione incrementale evitando di dover gestire più token di accesso.

Se la tua applicazione deve richiedere più ambiti non di accesso, devi sempre utilizzare autorizzazione incrementale quando richiedi e controlla quali ambiti sono stati concessi dagli utenti.

In questo esempio, si presume che entrambi gli ambiti indicati siano necessari affinché l'app funzionino correttamente. Devi attivare attivare autorizzazioni granulari, in modo che gli utenti abbiano maggiore controllo quando concedono autorizzazioni un'applicazione. L'applicazione dovrebbe gestire correttamente la risposta degli utenti controllando gli ambiti che hanno autorizzato.

main.js

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

Esamina il guida alle app web lato server su come accedere alle API di Google da applicazioni basate su server.

Accesso solo lato client

• Per le applicazioni che utilizzano i servizi di identità Google libreria JavaScript per interagire con Google OAuth 2.0, devi consultare questo documentazione sulla gestione di autorizzazioni granulari.
• Per le applicazioni che effettuano direttamente chiamate utilizzando JavaScript per l'autorizzazione Google OAuth 2.0 endpoint, è necessario esaminare questo documentazione sulla gestione di autorizzazioni granulari.

Testare l'applicazione aggiornata sulla gestione di autorizzazioni granulari

1. Delinea tutti i casi in cui gli utenti possono rispondere alle richieste di autorizzazione e il comportamento previsto dalla tua applicazione. Ad esempio, se l'utente autorizza solo due su tre ambiti richiesti, l'applicazione dovrebbe comportarsi di conseguenza.
2. Testa la tua applicazione attivando l'autorizzazione granulare. Esistono due modi per attivare autorizzazioni granulari:
   1. Controlla le schermate per il consenso OAuth 2.0 della tua applicazione per verificare se autorizzazioni granulari siano già abilitate per un'applicazione. Puoi anche creare un nuovo ID client Google OAuth 2.0 per web, Android o iOS tramite la console Google Cloud a scopo di test, poiché l'autorizzazione granulare è sempre abilitato per loro.
   2. Impostare il parametro Da enable_granular_consent a true durante la chiamata a OAuth di Google endpoint di autorizzazione. Alcuni SDK supportano esplicitamente questa funzionalità . Per altri, consulta la documentazione per sapere come aggiungere questo parametro e manualmente il suo valore. Se la tua implementazione non supporta l'aggiunta di questo parametro, puoi creare un nuovo cluster Web, ID client Google OAuth 2.0 per Android o iOS tramite la console Google Cloud per i test solo come indicato nel punto precedente.
      Importante: quando Google abilita autorizzazioni granulari per un'applicazione, Il parametro enable_granular_consent non avrà più alcun effetto.
3. Quando testi l'applicazione aggiornata, utilizza un Account Google personale (@gmail.com) anziché un account Workspace. Il motivo è che le app Workspace Enterprise con delega dell'autorità a livello di dominio o contrassegnata come Attendibile al momento non sono interessate dalle modifiche alle autorizzazioni granulari. Di conseguenza, i test con un'area di lavoro dell'organizzazione potrebbero non mostrare la nuova schermata del consenso granulare come previsto.