Cómo manejar permisos detallados

Descripción general

Con los permisos detallados, los usuarios obtienen un control más preciso sobre los datos de la cuenta que eligen compartir con cada app, lo que beneficia tanto a los usuarios como a los desarrolladores, ya que proporciona mayor control, transparencia y seguridad. Esta guía te ayudará a comprender los cambios y los pasos necesarios para actualizar tus aplicaciones de forma correcta y controlar los permisos detallados.

¿Qué es un permiso detallado?

Imagina que desarrollas una app de productividad que solicita permisos de correo electrónico y calendario. Es posible que tus usuarios quieran usar tu aplicación solo para el Calendario de Google, pero no para Gmail. Con los permisos de OAuth detallados, los usuarios pueden optar por otorgar solo permiso al Calendario de Google, pero no a Gmail. Permitir que los usuarios otorguen acceso a datos específicos minimiza la exposición de los datos, refuerza la confianza y les brinda control con prioridad en la privacidad sobre su vida digital. Es importante que diseñes tu aplicación para que controle estas situaciones.

Cuando se solicita más de un alcance que no es de acceso

Alcances de acceso y sin acceso

En el caso de las aplicaciones que solicitan permisos de acceso y de no acceso, los usuarios primero ven la página de consentimiento para los permisos de acceso (email, profile y openid). Después de que los usuarios dan su consentimiento para compartir su información de identidad básica (nombre, dirección de correo electrónico y foto de perfil), ven una pantalla de consentimiento de permisos detallados para los permisos de no acceso. En este caso, la aplicación debe verificar qué permisos otorgan los usuarios y no puede suponer que otorgan todos los permisos solicitados. En el siguiente ejemplo, la aplicación web solicita los tres permisos de acceso y un permiso de acceso a Google Drive. Después de que los usuarios den su consentimiento para los alcances de acceso, verán la pantalla de consentimiento de permisos detallados para el permiso de Google Drive:

Más de un alcance que no es de acceso

Se mostrará una pantalla de consentimiento de permisos detallados a los usuarios cuando las aplicaciones soliciten más de un alcance que no sea de acceso. Los usuarios pueden seleccionar los permisos que quieren aprobar para compartir con la aplicación. A continuación, se muestra un ejemplo de una pantalla de consentimiento de permisos detallados que solicita acceso a los mensajes de Gmail y los datos del Calendario de Google del usuario:

En el caso de las aplicaciones que solo solicitan alcances de acceso (email, profile y openid), no se aplica la pantalla de consentimiento de permisos detallados. Los usuarios aprueban o rechazan toda la solicitud de acceso. En otras palabras, si las aplicaciones solo solicitan permisos de acceso (uno, dos o los tres), no se aplica la pantalla de consentimiento de permisos detallados.

Para las aplicaciones que solicitan solo un alcance que no es de acceso, la pantalla de consentimiento de permisos detallados no es aplicable. En otras palabras, los usuarios aprueban o rechazan toda la solicitud, y no hay ninguna casilla de verificación en la pantalla de consentimiento. En la siguiente tabla, se resume cuándo se muestra la pantalla de consentimiento de permisos detallados.

Cómo determinar si tus aplicaciones se ven afectadas

Realiza una revisión exhaustiva de todas las secciones de tu aplicación en las que se utilizan los extremos de autorización de OAuth 2.0 de Google para las solicitudes de permisos. Presta atención a las que solicitan varios permisos, ya que activan pantallas de consentimiento de permisos detallados que se les presentan a los usuarios. En esos casos, asegúrate de que tu código pueda controlar la situación en la que los usuarios solo autorizan algunos de los alcances.

Cómo determinar si tu aplicación usa varios permisos

Inspecciona el código de tu app o la llamada de red saliente para determinar si las solicitudes de autorización de OAuth 2.0 de Google que realiza tu app harán que se muestre la pantalla de consentimiento de permisos detallados.

Inspecciona el código de tu aplicación

Revisa las secciones del código de tu aplicación en las que realizas llamadas a los extremos de autorización de OAuth de Google para solicitar permiso a los usuarios. Si usas una de las bibliotecas cliente de la API de Google, a menudo puedes encontrar los permisos que solicita tu aplicación en los pasos de inicialización del cliente. En la siguiente sección, se muestran algunos ejemplos. Debes consultar la documentación de los SDKs que usa tu aplicación para controlar Google OAuth 2.0 y determinar si tu aplicación se ve afectada. Para ello, usa la orientación que se muestra en los siguientes ejemplos como referencia.

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

Inspecciona la llamada de red saliente

Mientras inspeccionas las llamadas de red, busca las solicitudes enviadas a los extremos de autorización de Google OAuth y examina el parámetro scope.

Estos valores provocan que se muestre la pantalla de consentimiento de permisos detallados.

• El parámetro scope contiene permisos de acceso y permisos que no son de acceso.

  La siguiente solicitud de ejemplo contiene los tres alcances de acceso y un alcance que no es de acceso para ver los metadatos de los archivos de Google Drive del usuario:

  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

• El parámetro scope contiene más de un alcance que no es de acceso.

  La siguiente solicitud de ejemplo contiene dos permisos que no son de acceso para ver los metadatos de Google Drive del usuario y administrar archivos específicos de 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

Prácticas recomendadas para controlar los permisos detallados

Si determinas que tu aplicación debe actualizarse para controlar los permisos detallados, debes realizar las actualizaciones necesarias en tu código para controlar correctamente el consentimiento de varios permisos. Todas las aplicaciones deben cumplir con las siguientes prácticas recomendadas:

1. Revisa la Política de Datos del Usuario de los Servicios de las APIs de Google y asegúrate de cumplir con ella.
2. Solicita los permisos específicos que se necesitan para una tarea. Debes cumplir con la política de OAuth 2.0 de Google, que establece que solo debes solicitar los permisos que necesitas. Debes evitar solicitar varios permisos en el acceso, a menos que sea esencial para la funcionalidad principal de tu app. Agrupar varios permisos, en especial para los usuarios nuevos que no conocen las funciones de tu aplicación, puede dificultarles la comprensión de la necesidad de estos permisos. Esto puede generar alarmas y disuadir a los usuarios de seguir interactuando con tu aplicación.
3. Proporciona una justificación a los usuarios antes de solicitar la autorización. Explica claramente por qué tu aplicación necesita el permiso solicitado, qué harás con los datos del usuario y cómo se beneficiará el usuario si aprueba la solicitud. Nuestra investigación indica que estas explicaciones aumentan la confianza y la participación de los usuarios.
4. Usa la autorización incremental siempre que tu aplicación solicite permisos para evitar tener que administrar varios tokens de acceso.
5. Verifica a qué permisos otorgaron los usuarios. Cuando se solicitan varios permisos a la vez, es posible que los usuarios no otorguen todos los permisos que solicita tu app. Tu app siempre debe verificar qué permisos otorgó el usuario y controlar cualquier rechazo de permisos inhabilitando las funciones pertinentes. Sigue las políticas de OAuth 2.0 de Google sobre el control del consentimiento para varios permisos y solo vuelve a solicitar el consentimiento del usuario una vez que haya indicado claramente su intención de usar la función específica que requiere el permiso.

Actualiza tu aplicación para que controle los permisos detallados

Aplicaciones para Android

Debes consultar la documentación de los SDKs que usas para interactuar con Google OAuth 2.0 y actualizar tu aplicación para que controle los permisos detallados según las prácticas recomendadas.

Si usas el SDK de auth.api.signin de Play Services para interactuar con Google OAuth 2.0, puedes usar la función requestPermissions para solicitar el conjunto más pequeño de permisos necesarios y la función hasPermissions para verificar qué permisos otorgó el usuario cuando solicitó permisos detallados.

Aplicaciones de extensión de Chrome

Debes usar la API de Chrome Identity para trabajar con Google OAuth 2.0 según las prácticas recomendadas.

En el siguiente ejemplo, se muestra cómo controlar correctamente los permisos detallados.

manifest.json

El archivo de manifiesto de ejemplo declara dos permisos que no son de acceso con la cuenta para la aplicación de extensión de 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"]
  }
}

Enfoque incorrecto

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

Enfoque correcto

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

Aplicaciones para iOS, iPadOS y macOS

Debes consultar la documentación de los SDKs que usas para interactuar con Google OAuth 2.0 y actualizar tu aplicación para que controle los permisos detallados según las prácticas recomendadas.

Si usas la biblioteca de Acceso con Google para iOS y macOS para interactuar con Google OAuth 2.0, debes revisar la documentación sobre el manejo de permisos detallados.

Aplicaciones web

Debes consultar la documentación de los SDKs que usas para interactuar con Google OAuth 2.0 y actualizar tu aplicación para que controle los permisos detallados según las prácticas recomendadas.

Acceso del servidor (sin conexión)

En el siguiente fragmento de código, se muestra un ejemplo de NodeJS que solicita dos permisos que no son de acceso. Los usuarios verán la pantalla de consentimiento de permisos detallados.

Enfoque incorrecto

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

Enfoque correcto

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

Revisa la guía de la app web del servidor para acceder a las APIs de Google desde aplicaciones basadas en servidores.

Acceso solo del cliente

• En el caso de las aplicaciones que usan la biblioteca de JavaScript de Google Identity Services para interactuar con Google OAuth 2.0, debes revisar esta documentación sobre el manejo de permisos detallados.
• En el caso de las aplicaciones que realizan llamadas directamente con JavaScript a los extremos de autorización de OAuth 2.0 de Google, debes revisar esta documentación sobre el manejo de permisos detallados.

Prueba tu aplicación actualizada para controlar permisos detallados

1. Describe todos los casos en los que los usuarios pueden responder a las solicitudes de permisos y el comportamiento esperado de tu aplicación. Por ejemplo, si el usuario solo autoriza dos de los tres alcances solicitados, tu aplicación debe comportarse en consecuencia.
2. Prueba tu aplicación con el permiso detallado habilitado. Existen dos formas de habilitar los permisos detallados:
   1. Verifica las pantallas de consentimiento de OAuth 2.0 de tu aplicación para ver si los permisos detallados ya están habilitados para ella. También puedes crear un nuevo ID de cliente de Google OAuth 2.0 para Web, Android o iOS a través de la consola de Google Cloud con fines de prueba, ya que el permiso detallado siempre está habilitado para ellos.
   2. Establece el parámetro enable_granular_consent en true cuando llames a los extremos de autorización de OAuth de Google. Algunos SDKs admiten explícitamente este parámetro. En otros casos, consulta la documentación para saber cómo agregar este parámetro y su valor de forma manual. Si tu implementación no admite la adición del parámetro, puedes crear un nuevo ID de cliente de Google OAuth 2.0 para Web, Android o iOS a través de la consola de Google Cloud solo para fines de prueba, como se indica en el punto anterior.
3. Cuando pruebes tu aplicación actualizada, usa una Cuenta de Google personal (@gmail.com) en lugar de una cuenta de Workspace. Esto se debe a que las apps de Workspace Enterprise con delegación de autoridad en todo el dominio o marcadas como Confiables no se ven afectadas por los cambios en los permisos detallados en este momento. Por lo tanto, es posible que las pruebas con una cuenta de Workspace de tu organización no muestren la nueva pantalla de consentimiento detallado según lo previsto.