Come gestire le autorizzazioni granulari

Panoramica

Con le autorizzazioni granulari, i consumatori hanno un controllo più preciso sui dati dell'account che scelgono di condividere con ogni app. Offrono vantaggi sia agli utenti sia agli sviluppatori, fornendo maggiore controllo, trasparenza e sicurezza. Questa guida ti aiuterà a comprendere le modifiche e i passaggi necessari per aggiornare correttamente le tue applicazioni in modo che gestiscano le autorizzazioni granulari.

Che cos'è un'autorizzazione granulare?

Supponi di sviluppare un'app di produttività che richiede gli ambiti email e calendario. I tuoi utenti potrebbero voler utilizzare la tua applicazione solo per Google Calendar, ma non per Gmail. Con le autorizzazioni OAuth granulari, gli utenti possono scegliere di concedere l'autorizzazione solo a Google Calendar, ma non a Gmail. Consentendo agli utenti di concedere l'accesso a dati specifici, si riduce al minimo l'esposizione dei dati, si rafforza la fiducia e si offre agli utenti un controllo sulla loro vita digitale che mette al primo posto la privacy. È importante progettare l'applicazione in modo che gestisca questi scenari.

Quando viene richiesto più di un ambito non di accesso

Ambiti di accesso e non di accesso

Per le applicazioni che richiedono sia ambiti di accesso sia ambiti non di accesso, gli utenti vedono prima la schermata per il consenso per ambiti di accesso (email, profile, e openid). Dopo che gli utenti hanno acconsentito a condividere le informazioni di base sull'identità (nome, indirizzo email e foto del profilo), vedranno una schermata per il consenso per le autorizzazioni granulari per gli ambiti non di accesso. In questo caso, l'applicazione deve controllare quali ambiti sono stati concessi dagli utenti e non può presupporre che gli utenti concedano tutti gli ambiti richiesti ambiti. Nell'esempio seguente, l'applicazione web richiede tutti e tre gli ambiti di accesso e un ambito non di accesso di Google Drive. Dopo che gli utenti hanno acconsentito agli ambiti di accesso, vedranno la schermata per il consenso per le autorizzazioni granulari per l'autorizzazione di Google Drive:

Più di un ambito non di accesso

Agli utenti viene mostrata una schermata per il consenso granulare per le autorizzazioni quando le applicazioni richiedono più di un ambito non di accesso. Gli utenti possono selezionare le autorizzazioni che vogliono approvare per la condivisione con l'applicazione. Di seguito è riportato un esempio di schermata per il consenso per le autorizzazioni granulari che richiede l'accesso ai messaggi Gmail e ai dati di Google Calendar dell'utente:

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

Per le applicazioni che richiedono solo un ambito non di accesso, la schermata per il consenso per le autorizzazioni granulari non è applicabile. In altre parole, gli utenti approvano o rifiutano l'intera richiesta e nella schermata per il consenso non è presente alcuna casella di controllo. La tabella seguente riassume quando viene visualizzata la schermata per il consenso per le autorizzazioni granulari.

Determinare se le tue applicazioni sono interessate

Esamina attentamente tutte le sezioni dell'applicazione in cui vengono utilizzati gli endpoint di autorizzazione OAuth 2.0 di Google per le richieste di autorizzazione. Presta attenzione a quelle che richiedono più ambiti, in quanto attivano le schermate di consenso per le autorizzazioni granulari presentate agli utenti. In questi casi, assicurati che il codice possa gestire il caso in cui gli utenti autorizzano solo alcuni degli ambiti.

Come determinare se la tua applicazione utilizza più ambiti

Ispeziona il codice dell'app o lachiamata di rete in uscita per determinare se lerichieste di autorizzazione OAuth 2.0 di Google effettuate dalla tua app causano la visualizzazione della schermata per il consenso per le autorizzazioni granulari.

Ispezionare il codice dell'applicazione

Esamina le sezioni del codice dell'applicazione in cui effettui chiamate agli endpoint di autorizzazione OAuth di Google per richiedere l'autorizzazione agli utenti. Se utilizzi una delle librerie client delle API di Google spesso puoi trovare gli ambiti richiesti dalla tua applicazione nei passaggi di inizializzazione del client. Alcuni esempi sono riportati nella sezione seguente. Consulta la documentazione degli SDK utilizzati dalla tua applicazione per gestire OAuth 2.0 di Google per determinare se la tua applicazione è interessata, utilizzando come riferimento le indicazioni riportate negli esempi seguenti.

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

Ispezionare la chiamata di rete in uscita

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

Questi valori causano la visualizzazione della schermata per il consenso per le autorizzazioni granulari.

• Il parametro scope contiene ambiti di accesso e ambiti non di accesso.

  La 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.

  La seguente richiesta di esempio contiene due ambiti non di accesso per visualizzare i metadati di Google Drive dell'utente 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 la gestione delle autorizzazioni granulari

Se determini che la tua applicazione deve essere aggiornata per gestire le 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 le Norme relative ai dati utente dei servizi API di Google e assicurati di rispettarle.
2. Richiedi ambiti specifici necessari per un'attività. Devi rispettare le norme OAuth 2.0 di Google che prevedono di richiedere solo gli ambiti necessari. Evita di chiedere più ambiti durante l'accesso, a meno che non sia essenziale per la funzionalità di base della tua app. Raggruppare più ambiti, soprattutto per i nuovi utenti che non conoscono le funzionalità della tua applicazione, può rendere difficile comprendere la necessità di queste autorizzazioni. Questo potrebbe generare allarmi e dissuadere gli utenti dal continuare a utilizzare la tua applicazione.
3. Fornisci una giustificazione agli utenti prima di chiedere la 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. Le nostre ricerche indicano che queste spiegazioni aumentano la fiducia e il coinvolgimento degli utenti.
4. Utilizza l'autorizzazione incrementale ogni volta che l'applicazione richiede ambiti per evitare di dover gestire più token di accesso.
5. Controlla quali ambiti hanno concesso gli utenti. Quando richiedono più ambiti contemporaneamente, gli utenti potrebbero non concedere tutti gli ambiti richiesti dalla tua app. La tua app deve sempre controllare quali ambiti sono stati concessi dall'utente e gestire l'eventuale rifiuto degli ambiti disattivando le funzionalità pertinenti. Segui le norme OAuth 2.0 di Google sulla gestione del consenso per più ambiti e chiedi di nuovo il consenso all'utente solo quando ha indicato chiaramente l'intenzione di utilizzare la funzionalità specifica che richiede l'ambito.

Aggiornare l'applicazione per gestire le autorizzazioni granulari

Applicazioni Android

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

Se utilizzi auth.api.signin SDK di Play Services per interagire con OAuth 2.0 di Google, puoi utilizzare la funzione requestPermissions per richiedere il set di ambiti più piccolo necessario, e la funzione hasPermissions per controllare quali ambiti ha concesso l'utente quando ha richiesto le autorizzazioni granulari.

Applicazioni di estensioni di Chrome

Devi utilizzare l'API Chrome Identity per lavorare con OAuth 2.0 di Google in base alle 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'applicazione di estensione di 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"]
  }
}

Approccio errato

...
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

...
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 OAuth 2.0 di Google e aggiorna l'applicazione per gestire le autorizzazioni granulari in base alle best practice.

Se utilizzi la libreria Accedi con Google per iOS e macOS per interagire con OAuth 2.0 di Google, consulta la documentazione sulla gestione delle autorizzazioni granulari.

Applicazioni web

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

Accesso lato server (offline)

Il seguente snippet di codice mostra un esempio di NodeJS che richiede due ambiti non di accesso. Gli utenti vedranno la schermata per il consenso delle autorizzazioni granulari.

Approccio errato

...
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

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

Consulta la guida per le app web lato server su come accedere alle API di Google dalle applicazioni basate su server.

Accesso solo lato client

• Per le applicazioni che utilizzano la libreria JavaScript Servizi di identità Google per interagire con OAuth 2.0 di Google, consulta questa documentazione sulla gestione delle autorizzazioni granulari.
• Per le applicazioni che effettuano chiamate direttamente utilizzando JavaScript agli endpoint di autorizzazione OAuth 2.0 di Google, consulta questa documentazione sulla gestione delle autorizzazioni granulari.

Testare l'applicazione aggiornata per la gestione delle autorizzazioni granulari

1. Descrivi tutti i casi in cui gli utenti possono rispondere alle richieste di autorizzazione e il comportamento previsto della tua applicazione. Ad esempio, se l'utente autorizza solo due dei tre ambiti richiesti, la tua applicazione deve comportarsi di conseguenza.
2. Testa la tua applicazione con le autorizzazioni granulari attivate. Esistono due modi per attivare le autorizzazioni granulari:
   1. Controlla le schermate di consenso OAuth 2.0 della tua applicazione per verificare se le autorizzazioni granulari sono già attivate per la tua applicazione. Puoi anche creare un nuovo ID client OAuth 2.0 di Google per web, Android o iOS tramite la console Google Cloud a scopo di test, poiché le autorizzazioni granulari sono sempre attivate per questi ID.
   2. Imposta il parametro enable_granular_consent su true quando chiami gli endpoint di autorizzazione OAuth di Google. Alcuni SDK supportano esplicitamente questo parametro. Per altri, consulta la documentazione per scoprire come aggiungere manualmente questo parametro e il relativo valore. Se la tua implementazione non supporta l'aggiunta del parametro, puoi creare un nuovo ID client OAuth 2.0 di Google per web, Android o iOS tramite la console Google Cloud solo a scopo di test, come indicato nel punto precedente.
3. Quando testi l'applicazione aggiornata, utilizza un Account Google personale (@gmail.com) anziché un account Workspace. Questo perché le app Workspace Enterprise con delega dell'autorità a livello di dominio o contrassegnate come attendibili non sono interessate dalle modifiche alle autorizzazioni granulari in questo momento. Di conseguenza, il test con un account Workspace della tua organizzazione potrebbe non mostrare la nuova schermata per il consenso granulare come previsto.