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 du compte qu'ils choisissent de partager avec chaque application. Elles profitent à la fois aux utilisateurs et aux développeurs en offrant 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 ?

Imaginons que vous développiez une application de productivité qui demande des champs d'application pour l'adresse e-mail et l'agenda. Vos utilisateurs peuvent vouloir utiliser votre application uniquement pour Google Agenda, mais pas pour Gmail. Grâce aux autorisations OAuth précises, les utilisateurs peuvent choisir de n'accorder l'autorisation que pour Google Agenda, mais pas pour 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 leur donne un contrôle axé sur la confidentialité de leur vie numérique. Il est important de concevoir votre application de manière à gérer de tels scénarios.

Lorsque plusieurs champs d'application autres que la connexion sont demandés

Champs d'application avec et sans connexion

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

Plusieurs champs d'application autres que la connexion

Un écran de consentement d'autorisation précis s'affiche lorsque les applications demandent plusieurs champs d'application autres que la connexion. Les utilisateurs peuvent sélectionner les autorisations qu'ils souhaitent approuver pour les partager avec l'application. Voici un exemple d'écran de consentement pour des autorisations précises 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 de connexion (email, profile et openid), l'écran de consentement des autorisations précises ne s'applique pas. 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 de connexion (un, deux ou les trois), l'écran de consentement pour les autorisations précises ne s'applique pas.

Pour les applications qui ne demandent qu'un seul champ d'application autre que la connexion, l'écran de consentement des autorisations précises ne s'applique pas. En d'autres termes, les utilisateurs approuvent ou refusent l'intégralité de la demande, et l'écran de consentement ne comporte pas de case à cocher. Le tableau suivant récapitule les cas dans lesquels l'écran de consentement pour les autorisations précises s'affiche.

Déterminer si vos applications sont concernées

Examinez attentivement toutes les sections de votre application où des points de terminaison d'autorisation Google OAuth 2.0 sont utilisés pour les demandes d'autorisation. Prêtez attention à celles qui demandent plusieurs champs d'application, car elles activent des écrans de consentement 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 champs d'application.

Comment 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 de consentement pour les autorisations précises.

Inspecter le code de votre application

Examinez les sections du code de votre application dans lesquelles vous appelez les points de terminaison d'autorisation Google OAuth pour demander l'autorisation des utilisateurs. Si vous utilisez l'une des bibliothèques clientes des API Google, vous pouvez souvent trouver les champs d'application demandés par votre application lors des étapes d'initialisation du client. Vous trouverez quelques exemples dans la section suivante. Vous devez consulter la documentation des SDK que votre application utilise pour gérer Google OAuth 2.0 afin de déterminer si votre application est concernée, en vous basant sur les conseils présentés dans 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 earlier.
    * 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 un appel réseau sortant

La méthode d'inspection des appels réseau varie en fonction du type d'application.

• Application Web : inspecter l'activité réseau sur Chrome
• Android : inspecter le trafic réseau avec l'outil d'inspection du réseau
• Applications Chrome
  • Accédez à la page des extensions Chrome.
  • Cochez la case Mode développeur en haut à droite de la page des extensions.
  • Sélectionnez l'extension que vous souhaitez surveiller.
  • Cliquez sur le lien page en arrière-plan dans la section Inspecter les vues de la page de l'extension.
  • Une boîte de dialogue Outils pour les développeurs s'ouvre. Elle vous permet de surveiller le trafic réseau dans l'onglet Réseau.
• iOS : Analyser le trafic HTTP avec Instruments
• Applications de bureau : utilisez un outil de capture réseau disponible pour le système d'exploitation pour lequel l'application a été développée.

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 paramètre scope.

Ces valeurs entraînent l'affichage de l'écran de consentement pour les autorisations précises.

• Le paramètre scope contient des champs d'application de connexion et des champs d'application autres que de connexion.

  L'exemple de requête suivant contient les trois champs d'application de connexion et un champ d'application non lié à la connexion 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 plusieurs champs d'application autres que la connexion.

  L'exemple de requête suivant contient deux champs d'application autres que la connexion 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 le consentement pour 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 pour une tâche. Vous devez respecter la règle 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. Le regroupement de plusieurs champs d'application, en particulier pour les nouveaux utilisateurs qui ne connaissent pas les fonctionnalités de votre application, peut rendre difficile la compréhension de la nécessité de ces autorisations. Cela peut susciter des inquiétudes et dissuader les utilisateurs d'interagir davantage avec 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 des données de l'utilisateur et en quoi l'approbation de la demande sera bénéfique pour l'utilisateur. Nos recherches indiquent que ces explications renforcent la confiance et l'engagement des utilisateurs.
4. Utilisez l'autorisation incrémentielle 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 habilitations accordées 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 sur la gestion du consentement pour plusieurs champs d'application et ne demandez à nouveau le consentement de l'utilisateur 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

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

Si vous utilisez le SDK auth.api.signin des services Play pour interagir avec Google OAuth 2.0, vous pouvez utiliser la fonction requestPermissions pour demander l'ensemble de champs d'application le plus restreint possible, et la fonction hasPermissions 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 utiliser 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 la connexion pour l'application d'extension 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"
      ]
  }
}

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

Vous devez consulter la documentation des SDK que vous utilisez pour interagir avec Google OAuth 2.0 et mettre à 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 pour interagir avec Google OAuth 2.0, consultez la documentation sur la gestion des autorisations précises.

Applications Web

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

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

Le mode d'accès côté serveur (hors connexion) nécessite d'effectuer les opérations suivantes :

• Configurez un serveur et définissez un point de terminaison accessible publiquement pour recevoir le code d'autorisation.
• Configurez l'URI de redirection de votre point de terminaison public sur la page Clients de la console Google Cloud.

L'extrait de code suivant montre un exemple NodeJS qui demande deux champs d'application autres que la connexion. Les utilisateurs verront l'écran de consentement pour les autorisations précises.

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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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 la bibliothèque JavaScript Google Identity Services 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 la gestion des autorisations précises par votre application mise à jour

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 l'autorisation précise activée. Il existe deux façons d'activer les autorisations précises :

   1. Vérifiez les écrans de consentement 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 pour le Web, Android ou iOS via la console Google Cloud à des fins de test, car l'autorisation précise est toujours activée pour ces ID.

   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 les autres, consultez la documentation pour savoir comment ajouter manuellement ce paramètre et sa valeur. Si votre implémentation ne permet pas d'ajouter le paramètre, vous pouvez créer un ID client Google OAuth 2.0 Web, Android ou iOS via 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 d'un compte Workspace. En effet, les applications Workspace Enterprise avec délégation d'autorité au niveau du domaine ou marquées comme fiables ne sont pas concernées par les modifications apportées aux autorisations précises pour le moment. Par conséquent, si vous effectuez des tests avec un compte Workspace de votre organisation, il est possible que l'écran de consentement précis ne s'affiche pas comme prévu.