Gérer les autorisations précises

Présentation

Grâce à des autorisations précises, les clients peuvent contrôler plus précisément les données du compte. qu'ils choisissent de partager avec chaque application. Elles profitent aux utilisateurs et aux développeurs, car elles offrent le contrôle, la transparence et la sécurité. Ce guide vous aidera à comprendre 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 nécessite à la fois des champs d'application pour les e-mails et les agendas. Vos utilisateurs peut vouloir utiliser votre application uniquement pour Google Agenda, mais pas pour Gmail. Avec OAuth précis les utilisateurs peuvent choisir de n'accorder l'autorisation qu'à Google Agenda, et non à Gmail. En permettant aux utilisateurs d'accorder l'accès à des données spécifiques, cela réduit l'exposition des données et renforce et leur offre un contrôle axé sur la confidentialité sur leur vie numérique. Il est important de concevoir votre application pour gérer de tels scénarios.

Lorsque plusieurs champs d'application non liés à la connexion sont demandés

Portées de connexion et hors connexion

Pour les applications qui demandent à la fois des niveaux d'accès connectés et non connectés, les utilisateurs voient d'abord le consentement page des habilitations de connexion (email, profile et openid). Une fois que les utilisateurs ont donné leur consentement partagent leurs informations d'identité de base (nom, adresse e-mail et photo de profil), les utilisateurs verront un écran de consentement précis pour les niveaux d'accès non connectés. Dans ce cas, l'application doit vérifier les niveaux d'accès accordés par les utilisateurs et ne peut pas supposer que les utilisateurs accordent tous les droits champs d'application. Dans l'exemple suivant, l'application Web demande les trois champs d'application Sign-In et un Google Drive non connecté. Une fois que les utilisateurs ont donné leur consentement pour les champs d'application de la connexion, ils voient les écran de consentement détaillé pour l'autorisation Google Drive:

Plusieurs portées hors connexion

Un écran d'autorisation précis s'affiche pour les utilisateurs lorsque les applications demandent plus plusieurs niveaux d'accès non connectés. Les utilisateurs peuvent sélectionner les autorisations qu'ils souhaitent partager avec l'application. Voici un exemple d'écran de consentement précis demandant une autorisation l'accès aux messages Gmail et aux données Google Agenda de l'utilisateur:

Pour les applications qui demandent uniquement Sign-In d'accès (email, profile et openid), le niveau de précision l'écran de consentement pour les autorisations ne s'applique pas. Les utilisateurs acceptent ou refusent l'ensemble de la procédure de connexion requête. En d'autres termes, si les applications ne demandent que des habilitations de connexion (un, deux ou tous 3), l'écran de consentement précis des autorisations ne s'applique pas.

Pour les applications qui ne demandent qu'une autorisation hors connexion, l'écran de consentement aux autorisations précises n'est pas applicable. En d'autres termes, les utilisateurs approuvent ou refusent l'ensemble de la demande, et aucune case à cocher ne figure sur l'écran de consentement. Le tableau suivant indique quand l'écran de consentement granulaire des autorisations s'affiche.

Déterminer si vos applications sont concernées

Examinez attentivement toutes les sections de votre candidature Les points de terminaison d'autorisation Google OAuth 2.0 sont utilisés pour les demandes d'autorisation. Faites attention aux Ceux qui demandent plusieurs champs d'application lorsqu'ils activent des écrans de consentement précis pour les autorisations présentées aux utilisateurs. Dans de tels cas, assurez-vous que votre code peut gérer le cas où les utilisateurs autoriser certains champs d'application.

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

Inspectez le code de votre application ou appel réseau sortant pour déterminer si le OAuth 2.0 Les demandes d'autorisation envoyées par votre application entraîneront l'affichage précis des autorisations à afficher.

Inspecter le code de votre application

Examinez les sections du code de votre application dans lesquelles vous appelez les points de terminaison d'autorisation OAuth de Google pour demander l'autorisation des utilisateurs. Si vous utilisez l'une des API Google les bibliothèques clientes, vous pouvez souvent trouver les portées des requêtes de votre application dans les étapes d'initialisation. Vous trouverez quelques exemples dans la section suivante. Reportez-vous au des SDK utilisés par votre application pour gérer Google OAuth 2.0 afin de déterminer application est concernée. Suivez les conseils fournis dans les exemples suivants référence.

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

Lorsque vous inspectez les appels réseau, recherchez les requêtes envoyées points de terminaison d'autorisation, puis examinez le paramètre scope.

Ces valeurs entraînent l'affichage de l'écran de consentement précis des autorisations.

• Le paramètre scope contient les champs d'application liés à la connexion et ceux qui ne le sont pas.

  L'exemple de requête suivant contient les trois champs d'application Sign-In et un champ d'application non-Sign-In 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 non connectés.

  L'exemple de requête suivant contient deux habilitations non connectées pour afficher le Google Drive de l'utilisateur des métadonnées 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 des autorisations plus 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 les Services d'API Google: Règlement sur les données utilisateur et veillez à les respecter.
2. Demandez des niveaux d'accès spécifiques nécessaires à une tâche. Toi doivent respecter la règle OAuth 2.0 de Google que les niveaux d'accès besoin. Évitez de demander plusieurs champs d'application lors de la connexion, sauf si cela est essentiel au fonctionnement de base de votre application. Offres groupées plusieurs champs d'application ensemble, surtout pour les nouveaux utilisateurs qui ne connaissent pas d'applications, peut rendre difficile leur compréhension de la nécessité autorisations. Cela peut déclencher des alarmes et dissuader les utilisateurs d'interagir davantage avec vos application.
3. Fournissez une justification aux utilisateurs avant de leur poser la question. demande d'autorisation préalable. Expliquez clairement pourquoi votre application a besoin de l'autorisation demandée. ce que vous ferez des données de l'utilisateur et ce que l'approbation de la demande peut apporter à l'utilisateur. D'après nos recherches, ces explications renforcent la confiance et l'engagement des utilisateurs.
4. Utilisation 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 niveaux d'accès accordés par les utilisateurs. Lorsque vous demandez plusieurs niveaux d'accès à la fois, les utilisateurs peuvent ne pas accorder tous les niveaux d'accès demandés par votre application. Votre application doit toujours vérifier les champs d'application accordés par l'utilisateur et gérer tout déni de portée en désactivant caractéristiques. Suivez les règles Google OAuth 2.0 sur le traitement du consentement pour plusieurs champs d'application et ne demande à nouveau le consentement de l'utilisateur qu'une fois qu'il a clairement indiqué un intent pour utiliser la caractéristique spécifique qui nécessite le champ d'application.

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

Applications Android

Nous vous conseillons de consulter la documentation des SDK que vous utilisez pour interagir avec Google OAuth 2.0 et mettre à jour votre application pour gérer des autorisations précises bonnes pratiques.

Si vous utilisez auth.api.signin SDK des services Play pour interagir avec Google OAuth 2.0, vous pouvez utiliser requestPermissions pour demander le plus petit ensemble de champs d'application requis, et hasPermissions pour vérifier les niveaux d'accès accordés par l'utilisateur demandant des autorisations précises.

Extensions Chrome

Vous devez utiliser Google Chrome Identity afin qu'elle fonctionne avec Google OAuth 2.0, bonnes pratiques.

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

manifest.json

L'exemple de fichier manifeste déclare deux habilitations ne nécessitant pas la connexion pour l'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

Nous vous conseillons de consulter la documentation des SDK que vous utilisez pour interagir avec Google OAuth 2.0 et mettre à jour votre application pour gérer des autorisations précises bonnes pratiques.

Si vous utilisez la bibliothèque Google Sign-In pour iOS et macOS pour interagir avec Google OAuth 2.0, vous devez consulter documentation sur la gestion autorisations.

Applications Web

Nous vous conseillons de consulter la documentation des SDK que vous utilisez pour interagir avec Google OAuth 2.0 et mettre à jour votre application pour gérer des autorisations précises bonnes pratiques.

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

L'extrait de code suivant présente un exemple NodeJS qui demande deux portées autres que celles de connexion. Les utilisateurs verront l'écran de consentement aux 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 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 les guide des applications Web côté serveur pour savoir comment accéder aux API Google à partir d'applications 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 documentation sur la gestion des autorisations précises.
• Pour les applications qui effectuent directement des appels à l'aide de JavaScript avec l'autorisation Google OAuth 2.0 vous devez examiner 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 où les utilisateurs peuvent répondre à des demandes d'autorisation, ainsi que les 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 en activant une autorisation précise. Il existe deux façons d'activer des autorisations précises:
   1. Consultez les écrans de consentement OAuth 2.0 de votre application pour voir des 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 via la console Google Cloud à des fins de test, car une autorisation précise est toujours activée pour eux.
   2. Définir le paramètre enable_granular_consent à true lors de l'appel de la méthode des points de terminaison d'autorisation. Certains SDK proposent explicitement cette fonctionnalité . Pour les autres, consultez la documentation pour découvrir comment ajouter ce paramètre et manuellement. Si votre implémentation ne permet pas d'ajouter le paramètre, vous pouvez créer un nouvel objet Web, ID client Google OAuth 2.0 Android ou iOS via la console Google Cloud pour les tests 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 un compte Workspace. En effet, les applications Workspace Enterprise avec délégation d'autorité au niveau du domaine ou marquée comme Approuvée ne sont pas affectés par les modifications apportées aux autorisations précises pour le moment. Par conséquent, les tests avec un compte compte de votre organisation peut ne pas afficher le nouvel écran de consentement précis comme prévu.