Cómo manejar permisos detallados

Descripción general

Con los permisos detallados, los consumidores obtienen un control más preciso sobre los datos de la cuenta que eligen compartir con cada app. Estos permisos benefician tanto a los usuarios como a los desarrolladores, ya que proporcionan 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 detallados de OAuth, los usuarios pueden optar por otorgar solo el permiso del Calendario de Google, pero no el de Gmail. Permitir que los usuarios otorguen acceso a datos específicos minimiza la exposición de los datos, refuerza la confianza y les brinda a los usuarios un control que prioriza la privacidad sobre su vida digital. Es importante diseñar tu aplicación para que controle esas situaciones.

Cuando se solicita más de un permiso que no sea de acceso

Permisos 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 acepten compartir su información de identidad básica (nombre, dirección de correo electrónico y foto de perfil), verán 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 los usuarios otorgan todos los permisos solicitados. En el siguiente ejemplo, la aplicación web solicita los tres permisos de acceso y un permiso de acceso que no es de Google Drive. Después de que los usuarios otorguen su consentimiento a los permisos de acceso, verán la pantalla de consentimiento de permisos detallados para el permiso de Google Drive:

Más de un permiso que no sea de acceso

Se mostrará una pantalla de consentimiento de permisos detallados a los usuarios cuando las aplicaciones soliciten más de un permiso que no sea de acceso. Los usuarios pueden seleccionar qué permisos quieren aprobar para compartir con la aplicación. A continuación, se muestra un ejemplo de pantalla de consentimiento de permisos detallados en la que se 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 permisos de acceso (email, profile y openid), no corresponde 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), la pantalla de consentimiento de permisos detallados no corresponde.

En el caso de las aplicaciones que solicitan solo un permiso que no sea de acceso, no se aplica la pantalla de consentimiento de permisos detallados. En otras palabras, los usuarios aprueban o rechazan toda la solicitud, y no hay una 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.

Determina si tus aplicaciones se ven afectadas

Realiza una revisión exhaustiva de todas las secciones de tu aplicación en las que se usen extremos de autorización de Google OAuth 2.0 para las solicitudes de permiso. Presta atención a las que solicitan varios permisos, ya que activan pantallas de consentimiento de permisos detallados que se 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 permisos.

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 Google OAuth 2.0 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 SDK que usa tu aplicación para controlar Google OAuth 2.0 y determinar si tu aplicación se ve afectada. Para ello, usa como referencia la orientación que se muestra en los siguientes ejemplos.

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

Inspecciona la llamada de red saliente

El método para inspeccionar las llamadas de red variará según el tipo de cliente de tu aplicación.

• Aplicación web: Inspecciona la actividad de red en Chrome
• Android: Inspecciona el tráfico de red con el Inspector de red
• Apps de Chrome
  • Navega a la página de extensiones de Chrome.
  • Marca la casilla de verificación Modo de desarrollador en la esquina superior derecha de la página de extensiones.
  • Selecciona la extensión que quieres supervisar.
  • Haz clic en el vínculo página en segundo plano en la sección Inspeccionar vistas de la página de la extensión.
  • Se abrirá un diálogo de Herramientas para desarrolladores en el que podrás supervisar el tráfico de red en la pestaña Red.
• iOS: Analiza el tráfico HTTP con Instruments
• Apps para computadoras: Usa una herramienta de captura de red disponible para el sistema operativo para el que se desarrolló la app.

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

Estos valores hacen 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 permisos de Acceso y un permiso 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 permiso que no es de acceso.

  En el siguiente ejemplo de solicitud, se incluyen 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 cumplirla.
2. Solicita los permisos específicos que se necesitan para una tarea. Debes cumplir con la política de Google OAuth 2.0, que establece que solo debes solicitar los permisos que necesitas. Debes evitar solicitar varios permisos durante 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 dificultar que comprendan 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 cada vez que tu aplicación solicite permisos para evitar tener que administrar varios tokens de acceso.
5. Verifica 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 denegación de permisos inhabilitando las funciones pertinentes. Sigue las políticas de Google OAuth 2.0 sobre el manejo del consentimiento para varios permisos y vuelve a solicitar el consentimiento del usuario solo cuando haya indicado claramente su intención de usar la función específica que requiere el permiso.

Actualiza tu aplicación para controlar 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 los Servicios de Play 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 extensiones 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

En el archivo de manifiesto de ejemplo, se declaran dos permisos que no son de acceso para la aplicación de la 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)

El modo de acceso del servidor (sin conexión) requiere que hagas lo siguiente:

• Configura un servidor y define un extremo de acceso público para recibir el código de autorización.
• Configura el URI de redireccionamiento de tu extremo público en la página Clientes de la consola de Google Cloud.

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 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 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 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 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 apps web del servidor para obtener información sobre cómo 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 Google OAuth 2.0, debes revisar esta documentación sobre el manejo de permisos detallados.

Prueba tu aplicación actualizada para controlar los permisos detallados

1. Describe todos los casos en los que los usuarios pueden responder a las solicitudes de permiso y el comportamiento esperado de tu aplicación. Por ejemplo, si el usuario solo autoriza dos de los tres permisos solicitados, tu aplicación debería comportarse en consecuencia.

2. Prueba tu aplicación con el permiso detallado habilitado. Existen dos formas de habilitar los permisos detallados:

   1. Revisa las pantallas de consentimiento de OAuth 2.0 de tu aplicación para ver si ya tiene habilitados los permisos detallados. También puedes crear un nuevo ID de cliente de OAuth 2.0 de Google para la 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 tienen compatibilidad explícita con este parámetro. En otros casos, consulta la documentación para ver cómo puedes agregar este parámetro y su valor de forma manual. Si tu implementación no admite agregar el 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 con 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 De confianza 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 como se espera.