Cómo manejar permisos detallados

Descripción general

Con permisos detallados, los consumidores obtienen un control más preciso sobre los datos de la cuenta que deciden compartir con cada aplicación. Benefician tanto a los usuarios como a los desarrolladores al proporcionar la transparencia y la seguridad. Con esta guía, podrás comprender los conceptos y los pasos para actualizar correctamente tus aplicaciones a fin de administrar permisos detallados.

¿Qué es el permiso detallado?

Imagina que desarrollas una app de productividad que solicita permisos de correo electrónico y calendario. Tus usuarios es posible que quiera usar su aplicación solo para el Calendario de Google y no para Gmail. Con OAuth detallado , los usuarios pueden optar por otorgarles permiso únicamente 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 a los usuarios un control de su vida digital que prioriza la privacidad. Es importante que diseñes tu aplicación para que controle esas situaciones.

Cuando se solicita más de un alcance sin acceso

Alcances de acceso y no acceso

En el caso de las aplicaciones que solicitan permisos de acceso y de no acceso, los usuarios primero ven el consentimiento página de Permisos de acceso (email, profile y openid). Una vez que los usuarios otorguen su consentimiento para lo siguiente: comparten su información de identidad básica (nombre, dirección de correo electrónico y foto de perfil), los usuarios verán una pantalla de consentimiento de permisos detallada para los permisos sin acceso. En este caso, la aplicación Se deben verificar los permisos otorgados por los usuarios y no se puede suponer que los usuarios otorgan todos los permisos de los permisos de acceso. En el siguiente ejemplo, la aplicación web solicita los tres alcances de Sign-In y una Alcance de Google Drive sin Acceso. Una vez que los usuarios otorguen su consentimiento para los permisos de acceso, los usuarios verán las Pantalla de consentimiento detallada de permisos para el permiso de Google Drive:

Alcances de acceso y sin acceso

Más de un alcance sin acceso

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

Más de un alcance sin acceso

Para las aplicaciones que solo solicitan Acceso de permisos (email, profile y openid), los detalles la pantalla de consentimiento de permisos no es aplicable. Los usuarios aprueban o rechazan todo el acceso. para cada solicitud. En otras palabras, si las aplicaciones solo solicitan permisos de acceso (uno, dos o todos) 3), la pantalla de consentimiento detallada del permiso no es aplicable.

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

Cantidad de permisos de acceso Cantidad de permisos sin acceso Pantalla de consentimiento de permisos detallada
1-3 0 No aplicable
1-3 1+ Servicios
0 1 No aplicable
0 2 años o más Servicios

Determina si tus aplicaciones se ven afectadas

Revisa minuciosamente todas las secciones de tu postulación en las que Los extremos de autorización de Google OAuth 2.0 se utilizan para las solicitudes de permisos. Presta atención a los 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 manejar los casos en los que los usuarios autorizar algunos de los alcances.

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

Inspecciona el código de tu app o la llamada de red saliente para determinar si el OAuth 2.0 Las solicitudes de autorización que realice tu app mostrarán la pantalla de consentimiento de permisos detallada. que se mostrará.

Cómo inspeccionar el código de la 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 alcances que solicita tu aplicación en los pasos de inicialización del cliente. En la siguiente sección, se muestran algunos ejemplos. Debes consultar el documentación de los SDK que usa tu aplicación para controlar Google OAuth 2.0 y, así, determinar si tu su aplicación se ve afectada, siguiendo la guía que se muestra en los siguientes ejemplos como referencia.

Google Identity Services

Los siguientes servicios de identidad de Google El fragmento de código de la biblioteca JavaScript inicializa TokenClient con varias sin Acceso. La pantalla de consentimiento de permisos detallados se mostrará cuando la app web solicite la autorización de los usuarios. 

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

Python

En el siguiente fragmento de código, se usa el módulo google-auth-oauthlib.flow para crear la solicitud de autorización; El parámetro scope incluye dos sin Acceso. Se mostrará la pantalla de consentimiento detallada del permiso cuando la Web la aplicación solicita autorización de los usuarios. 

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'])

Node.js

Con el siguiente fragmento de código, se crea un objeto google.auth.OAuth2, que define la parámetros en la solicitud de autorización cuyo parámetro scope incluya dos sin Acceso. Se mostrará la pantalla de consentimiento detallada del permiso cuando la aplicación web solicita autorización de los usuarios. 

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

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

Mientras inspeccionas las llamadas de red, busca las solicitudes que se enviaron al OAuth de Google extremos de autorización 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 sin acceso.

    La siguiente solicitud de ejemplo contiene los tres alcances de acceso y uno sin acceso. para ver los metadatos de los archivos de Google Drive de un 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 administrar permisos detallados

Si determinas que tu aplicación necesita actualizarse para controlar permisos detallados, debes aplicar las actualizaciones necesarias a tu código para administrar adecuadamente el consentimiento para varios permisos. Todas las aplicaciones deben cumplir con las siguientes prácticas recomendadas:

  1. Revisa las Servicios de las APIs de Google: Política de Datos del Usuario y asegúrate de cumplirlas.
  2. Solicita los permisos específicos que se necesitan para una tarea. Tú debe cumplir con la política de Google OAuth 2.0 que solo pueden solicitar permisos necesitan. Evita pedir varias de acceso, a menos que sea esencial para la funcionalidad principal de la aplicación. Paquetes varios ámbitos juntos, especialmente para los usuarios nuevos que no están familiarizados con tu de aplicaciones pueden dificultar la comprensión de la necesidad de estas permisos. Esto puede generar alarmas y disuadir a los usuarios de seguir interactuando con tu y mantener la integridad de su aplicación.
  3. Proporciona una justificación a los usuarios antes de hacer una pregunta solicitud de autorización. Explica claramente por qué tu aplicación necesita el permiso solicitado. lo que harás con los datos del usuario y cómo este se beneficiará si aprueba la solicitud. Nuestra investigación indica que estas explicaciones aumentan la confianza y la participación de los usuarios.
  4. Uso autorización incremental siempre que la aplicación solicite alcances para evitar tener que administrar múltiples tokens de acceso.
  5. Verifica qué permisos otorgaron los usuarios. Cuando solicita varios de una sola vez, es posible que los usuarios no otorguen todos los permisos que solicita tu app. Tu app siempre debe verificar los permisos otorgados por el usuario y controlar cualquier denegación de permisos inhabilitando atributos. Sigue las políticas de Google OAuth 2.0 en para varias de permisos y solo deberás volver a solicitar el consentimiento del usuario cuando lo haya indicado claramente. un intent para usar la función específica que requiere el alcance.

Actualiza tu aplicación para controlar permisos detallados

Aplicaciones para Android

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

Si usas auth.api.signin SDK de Play Services para interactuar con Google OAuth 2.0, puedes usar requestPermissions para solicitar el conjunto más pequeño de permisos necesario, y las hasPermissions para verificar el alcance que otorgó el usuario cuando solicitando permisos detallados.

Aplicaciones de extensión de Chrome

Deberías usar Chrome Identity para funcionar con Google OAuth 2.0 según prácticas recomendadas.

En el siguiente ejemplo, se muestra cómo administrar de forma adecuada los permisos detallados.

manifest.json

El ejemplo de archivo de manifiesto declara dos alcances que no son de acceso para la extensión de Chrome y mantener la integridad de su aplicación.

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

Todo o nada

Los usuarios hacen clic en el botón para iniciar el proceso de autorización. El fragmento de código supone que a los usuarios se les presenta un "todo o nada" pantalla de consentimiento para los dos alcances especificados en el archivo manifest.json. Omite verificar qué alcances otorgaron los usuarios.

oauth.js

...
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

Alcances más pequeños

Selecciona el conjunto más pequeño de permisos necesario.

La aplicación solo debe solicitar el conjunto más pequeño de permisos necesario. Se recomienda que tu aplicación solicite un alcance a la vez cuando sea necesario para completar una tarea.

En este ejemplo, se supone que ambos alcances declarados en manifest.json de Google Cloud son el conjunto más pequeño de permisos necesarios. El archivo oauth.js usa la API de Chrome Identity para iniciar el proceso de autorización con Google. Debes habilitar habilitar permisos detallados, de modo que los usuarios tengan un mayor control cuando otorguen permisos a tu y mantener la integridad de su aplicación. Tu aplicación debería manejar correctamente la respuesta de los usuarios verificando qué alcances autorizan los usuarios.

oauth.js

...
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 SDK que usas para interactuar con Google OAuth 2.0 y actualiza tu aplicación para controlar permisos detallados según prácticas recomendadas.

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

Aplicaciones web

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

Acceso al servidor (sin conexión)

El modo de acceso del servidor (sin conexión) requiere que hagas lo siguiente:
  • Activa un servidor y define un extremo de acceso público para recibir el código de autorización.
  • Configura el de redireccionamiento de tu extremo público en la de la consola de Google Cloud.

El siguiente fragmento de código muestra un ejemplo de Node.js en el que se solicitan dos alcances que no son de acceso. Los usuarios consulta la pantalla de consentimiento de permisos detallada.

Enfoque incorrecto

Todo o nada

Se redirecciona a los usuarios a la URL de autorización. El fragmento de código supone que se presenta a los usuarios con la frase "todo o nada" pantalla de consentimiento para los dos alcances especificados en scopes. Omite verificar qué alcances otorgaron los usuarios.

main.js

...
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

Alcance más pequeño

Selecciona el conjunto más pequeño de permisos necesarios.

La aplicación solo debe solicitar el conjunto más pequeño de permisos necesario. Se recomienda que tu aplicación solicite un alcance a la vez cuando sea necesario para completar una tarea. Cada vez que tu aplicación solicite permisos, debe usar la autorización incremental para evitar tener que administrar varios tokens de acceso.

Si tu aplicación debe solicitar múltiples alcances que no son de acceso, siempre debes usar la autorización incremental cuando solicitas y verificas qué permisos otorgaron los usuarios.

En este ejemplo, se supone que los dos alcances indicados son necesarios para que la app funcionen correctamente. Debes habilitar habilitar permisos detallados, de modo que los usuarios tengan un mayor control cuando otorguen permisos a tu y mantener la integridad de su aplicación. Tu aplicación debería manejar correctamente la respuesta de los usuarios verificando qué alcances autorizaron.

main.js

...
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 el guía de la app web del servidor sobre cómo acceder a las APIs de Google desde aplicaciones basadas en el servidor.

Acceso solo del cliente

  • Para aplicaciones que usan Google Identity Services JavaScript para interactuar con Google OAuth 2.0, deberías revisar esto documentación en el manejo de permisos detallados.
  • Para aplicaciones que realizan llamadas directamente con JavaScript a la autorización de Google OAuth 2.0 extremos, deberías revisar este documentación en 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 permisos. el comportamiento esperado de tu aplicación. Por ejemplo, si el usuario solo autoriza dos de los tres alcances solicitados, tu aplicación debería comportarse en consecuencia.
  2. Prueba tu aplicación con el permiso detallado habilitado. Hay dos formas de habilitar permisos detallados:
    1. Revisa las pantallas de consentimiento de OAuth 2.0 de tu aplicación para ver si permisos detallados ya están habilitados para tu y mantener la integridad de su aplicación. También puedes crear un nuevo ID de cliente de Google OAuth 2.0 para la Web, Android o iOS a través de la consola de Google Cloud con fines de prueba, ya que siempre se otorga permiso detallado habilitado para ellos.
    2. Configura el parámetro enable_granular_consent a true cuando se llama a Google OAuth . de acceso y autorización. Algunos SDK tienen compatibilidad explícita para esto. parámetro. Para otros, consulta la documentación para ver cómo puedes agregar este parámetro y su valor de forma manual. Si tu implementación no permite agregar el parámetro, puedes crear un sitio web nuevo ID de cliente de Google OAuth 2.0 para Android o iOS a través de la consola de Google Cloud para pruebas solo como se indica en el punto anterior.
  3. Cuando pruebes la aplicación actualizada, usa una Cuenta de Google personal (@gmail.com) en lugar de una cuenta de Workspace. Esto se debe a que, en este momento, los cambios en los permisos detallados no afectan a las apps de Workspace Enterprise con delegación de autoridad en todo el dominio o marcadas como Confiable. 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.