Gérer les autorisations précises

Présentation

Grâce aux autorisations précises, les consommateurs bénéficient d'un contrôle plus précis sur les données de compte qu'ils choisissent de partager avec chaque application. Elles sont avantageuses pour les utilisateurs et les développeurs, car elles offrent plus de contrôle, de transparence et de sécurité. Ce guide vous explique les changements nécessaires et la marche à suivre pour mettre à jour vos applications afin qu'elles gèrent les autorisations précises.

Qu'est-ce qu'une autorisation précise ?

Imaginez que vous développiez une application de productivité qui demande à la fois les champs d'application "E-mail" et "Agenda". Vos utilisateurs souhaitent peut-être utiliser votre application uniquement pour Google Agenda, mais pas pour Gmail. Avec les autorisations OAuth précises, les utilisateurs peuvent choisir d'accorder uniquement l'autorisation Google Agenda, mais pas Gmail. En permettant aux utilisateurs d'accorder l'accès à des données spécifiques, cela minimise l'exposition des données, renforce la confiance et permet aux utilisateurs de contrôler leur vie numérique en privilégiant la confidentialité. Il est important de concevoir votre application pour gérer de tels scénarios.

Lorsqu'un champ d'application autre que "Se connecter" est demandé

Champs d'application "Se connecter" et autres

Pour les applications qui demandent à la fois des champs d'application "Se connecter" et d'autres, les utilisateurs voient d'abord la page d'autorisation pour les champs d'application Se connecter (email, profile, et openid). Une fois qu'ils ont accepté de partager leurs informations d'identité de base (nom, adresse e-mail et photo de profil), ils voient un écran d'autorisation précis pour les champs d'application autres que "Se connecter". Dans ce cas, l'application doit vérifier les champs d'application accordés par les utilisateurs et ne peut pas supposer qu'ils accordent tous les champs d'application demandés. Dans l'exemple suivant, l'application Web demande les trois champs d'application "Se connecter" et un champ d'application Google Drive autre que "Se connecter". Une fois que les utilisateurs ont accepté les champs d'application "Se connecter", ils voient l' écran d'autorisation précis pour l'autorisation Google Drive :

Plus d'un champ d'application autre que "Se connecter"

Un écran d'autorisation précis s'affiche pour les utilisateurs lorsque les applications demandent plus d'un champ d'application autre que "Se connecter". Les utilisateurs peuvent sélectionner les autorisations qu'ils souhaitent approuver pour les partager avec l'application. Voici un exemple d'écran d'autorisation précis demandant l'accès aux messages Gmail et aux données Google Agenda de l'utilisateur :

Pour les applications qui ne demandent que des champs d'application Se connecter (email, profile, et openid), l'écran d'autorisation précis n'est pas applicable. Les utilisateurs approuvent ou refusent l'intégralité de la demande de connexion. En d'autres termes, si les applications ne demandent que des champs d'application "Se connecter" (un, deux ou les trois), l'écran d'autorisation précis n'est pas applicable.

Pour les applications qui ne demandent qu'un champ d'application autre que "Se connecter", l'écran d'autorisation précis n'est pas applicable. En d'autres termes, les utilisateurs approuvent ou refusent l'intégralité de la demande, et il n'y a pas de case à cocher dans l'écran d'autorisation. Le tableau suivant récapitule quand l'écran d'autorisation précis s'affiche.

Déterminer si vos applications sont concernées

Examinez attentivement toutes les sections de votre application dans lesquelles les points de terminaison d'autorisation Google OAuth 2.0 sont utilisés pour les demandes d'autorisation. Faites attention à celles qui demandent plusieurs champs d'application, car elles activent les écrans d'autorisation précis présentés aux utilisateurs. Dans ce cas, assurez-vous que votre code peut gérer le cas où les utilisateurs n'autorisent que certains des champs d'application.

Déterminer si votre application utilise plusieurs champs d'application

Inspectez le code de votre application ou l'appel réseau sortant pour déterminer si les demandes d'autorisation Google OAuth 2.0 effectuées par votre application entraîneront l'affichage de l'écran d'autorisation précis.

Inspecter le code de votre application

Examinez les sections du code de votre application dans lesquelles vous effectuez des appels aux points de terminaison d'autorisation Google OAuth pour demander l'autorisation aux utilisateurs. Si vous utilisez l'une des bibliothèques clientes de l'API Google, vous pouvez souvent trouver les champs d'application demandés par votre application dans les étapes d'initialisation du client. Quelques exemples sont présentés dans la section suivante. Vous devez vous reporter à la documentation des SDK utilisés par votre application pour gérer Google OAuth 2.0 afin de déterminer si votre application est concernée, en vous basant sur les exemples suivants.

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

Inspecter l'appel réseau sortant

Lors de l'inspection des appels réseau, recherchez les requêtes envoyées aux points de terminaison d'autorisation Google OAuth et examinez le scope paramètre.

Ces valeurs entraînent l'affichage de l'écran d'autorisation précis.

• Le paramètre scope contient des champs d'application "Se connecter" et d'autres.

  L'exemple de requête suivant contient les trois champs d'application "Se connecter" et un champ d'application autre que "Se connecter" pour afficher les métadonnées des fichiers Google Drive de l'utilisateur :

  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

• Le paramètre scope contient plus d'un champ d'application autre que "Se connecter".

  L'exemple de requête suivant contient deux champs d'application autres que "Se connecter" pour afficher les métadonnées Google Drive de l'utilisateur et gérer des fichiers Google Drive spécifiques :

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

Bonnes pratiques pour gérer les autorisations précises

Si vous déterminez que votre application doit être mise à jour pour gérer les autorisations précises, vous devez apporter les modifications nécessaires à votre code pour gérer correctement l'autorisation de plusieurs champs d'application. Toutes les applications doivent respecter les bonnes pratiques suivantes :

1. Consultez le Règlement sur les données utilisateur dans les services d'API Google et assurez-vous de le respecter.
2. Demandez les champs d'application spécifiques nécessaires à une tâche. Vous devez respecter le règlement Google OAuth 2.0 qui stipule que vous ne devez demander que les champs d'application dont vous avez besoin. Évitez de demander plusieurs champs d'application lors de la connexion, sauf si cela est essentiel pour la fonctionnalité de base de votre application. Regrouper plusieurs champs d'application, en particulier pour les nouveaux utilisateurs qui ne connaissent pas les fonctionnalités de votre application, peut leur rendre difficile la compréhension de la nécessité de ces autorisations. Cela peut susciter des inquiétudes et dissuader les utilisateurs de continuer à utiliser votre application.
3. Fournissez une justification aux utilisateurs avant de leur demander l' autorisation. Expliquez clairement pourquoi votre application a besoin de l'autorisation demandée, ce que vous ferez avec les données de l'utilisateur et comment l'utilisateur bénéficiera de l'approbation de la demande. Nos recherches indiquent que ces explications augmentent la confiance et l'engagement des utilisateurs.
4. Utilisez l'autorisation incrémentale chaque fois que votre application demande des champs d'application pour éviter d'avoir à gérer plusieurs jetons d'accès.
5. Vérifiez les champs d'application accordés par les utilisateurs. Lorsque vous demandez plusieurs champs d'application à la fois, les utilisateurs peuvent ne pas accorder tous les champs d'application demandés par votre application. Votre application doit toujours vérifier les champs d'application accordés par l'utilisateur et gérer tout refus de champs d'application en désactivant les fonctionnalités concernées. Suivez les règles Google OAuth 2.0 concernant la gestion de l'autorisation pour plusieurs champs d'application et n'invitez l'utilisateur à donner son autorisation que lorsqu'il a clairement indiqué son intention d'utiliser la fonctionnalité spécifique qui nécessite le champ d'application.

Mettre à jour votre application pour gérer les autorisations précises

Applications Android

Consultez la documentation des SDK que vous utilisez pour interagir avec Google OAuth 2.0 et mettez à jour votre application pour gérer les autorisations précises en fonction des bonnes pratiques.

Si vous utilisez auth.api.signin SDK de Play Services pour interagir avec Google OAuth 2.0, vous pouvez utiliser requestPermissions fonction pour demander le plus petit ensemble de champs d'application nécessaires, et la hasPermissions fonction pour vérifier les champs d'application accordés par l'utilisateur lors de la demande d'autorisations précises.

Applications d'extension Chrome

Vous devez utiliser l'API Chrome Identity pour travailler avec Google OAuth 2.0 en fonction des bonnes pratiques.

L'exemple suivant montre comment gérer correctement les autorisations précises.

manifest.json

L'exemple de fichier manifeste déclare deux champs d'application autres que "Se connecter" pour l'application d'extension Chrome application.

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

Approche incorrecte

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

Approche correcte

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

Applications iOS, iPadOS et macOS

Consultez la documentation des SDK que vous utilisez pour interagir avec Google OAuth 2.0 et mettez à jour votre application pour gérer les autorisations précises en fonction des bonnes pratiques.

Si vous utilisez la bibliothèque Google Sign-In pour iOS et macOS afin d'interagir avec Google OAuth 2.0, consultez la documentation sur la gestion des autorisations précises.

Applications Web

Consultez la documentation des SDK que vous utilisez pour interagir avec Google OAuth 2.0 et mettez à jour votre application pour gérer les autorisations précises en fonction des bonnes pratiques.

Accès côté serveur (hors connexion)

L'extrait de code suivant montre un exemple NodeJS qui demande deux champs d'application autres que "Se connecter". Les utilisateurs verront l'écran d'autorisation précis.

Approche incorrecte

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

Approche correcte

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

Consultez le guide sur les applications Web côté serveur pour savoir comment accéder aux API Google à partir d'applications basées sur un serveur.

Accès côté client uniquement

• Pour les applications qui utilisent Google Identity Services bibliothèque JavaScript pour interagir avec Google OAuth 2.0, consultez cette documentation sur la gestion des autorisations précises.
• Pour les applications qui effectuent directement des appels à l'aide de JavaScript vers les points de terminaison d'autorisation Google OAuth 2.0 consultez cette documentation sur la gestion des autorisations précises.

Tester votre application mise à jour sur la gestion des autorisations précises

1. Décrivez tous les cas dans lesquels les utilisateurs peuvent répondre aux demandes d'autorisation et le comportement attendu de votre application. Par exemple, si l'utilisateur n'autorise que deux des trois champs d'application demandés, votre application doit se comporter en conséquence.
2. Testez votre application avec les autorisations précises activées. Vous pouvez activer les autorisations précises de deux manières :
   1. Cochez les écrans d'autorisation OAuth 2.0 de votre application pour voir si les autorisations précises sont déjà activées pour votre application. Vous pouvez également créer un ID client Google OAuth 2.0 Web, Android ou iOS dans la console Google Cloud à des fins de test, car les autorisations précises sont toujours activées pour eux.
   2. Définissez le paramètre enable_granular_consent sur true lorsque vous appelez les points de terminaison d'autorisation Google OAuth . Certains SDK sont explicitement compatibles avec ce paramètre. Pour d'autres, consultez la documentation pour savoir comment ajouter manuellement ce paramètre et sa valeur. Si votre implémentation n'est pas compatible avec l'ajout du paramètre, vous pouvez créer un ID client Google OAuth 2.0 Web, Android ou iOS dans la console Google Cloud à des fins de test uniquement, comme indiqué au point précédent.
3. Lorsque vous testez votre application mise à jour, utilisez un compte Google personnel (@gmail.com) au lieu de un compte Workspace. En effet, les applications Workspace Enterprise avec délégation d'autorité à l'échelle du domaine ou marquées comme "Approuvées" ne sont pas affectées par les modifications apportées aux autorisations précises pour le moment. Par conséquent, les tests avec un compte Workspace de votre organisation peuvent ne pas afficher le nouvel écran d'autorisation précis comme prévu.