Permisos

Los usuarios deben autorizar los complementos y otras aplicaciones que acceden a sus datos o actúan en su nombre. Cuando un usuario ejecuta un complemento por primera vez, la IU del complemento muestra un mensaje de autorización para iniciar el flujo de autorización.

Durante este flujo, el mensaje le indica al usuario lo que la aplicación quiere hacer con el permiso. Por ejemplo, un complemento podría querer permiso para leer el mensaje de correo electrónico de un usuario o crear eventos en su calendario. El proyecto de secuencia de comandos del complemento define estos permisos individuales como permisos de OAuth.

Los permisos se declaran en tu manifiesto con cadenas de URL. Durante el flujo de autorización, Apps Script le presenta al usuario una descripción legible del alcance. Por ejemplo, tu complemento de Google Workspace podría usar el alcance "Leer el mensaje actual", que se escribe en tu manifiesto como https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Durante el flujo de autorización, un complemento con este alcance le solicita al usuario que permita que el complemento vea sus mensajes de correo electrónico cuando se esté ejecutando.

Los permisos que Apps Script usa para sus diversos servicios se superponen con los permisos que usa la API relacionada. Por ejemplo, el servicio de Calendar de Apps Script usa muchos de los mismos alcances que la API de Calendar. Puedes consultar los alcances que requieren los métodos de servicio de Apps Script en la documentación de referencia de Apps Script.

Ver permisos

Para ver los alcances que requiere tu proyecto de secuencia de comandos, haz lo siguiente:

1. Abre el proyecto de secuencia de comandos.
2. A la izquierda, haz clic en Descripción general info_outline.
3. Consulta los permisos en "Permisos de OAuth del proyecto".

También puedes ver los permisos actuales del proyecto de secuencia de comandos en el manifiesto del proyecto, en el campo oauthScopes, pero solo si estableciste esos permisos explícitamente.

Establece permisos explícitos

Apps Script determina automáticamente qué permisos necesita un script analizando su código en busca de llamadas a funciones que los requieran. Para la mayoría de las secuencias de comandos, esto es suficiente y te ahorra tiempo, pero para los complementos publicados, debes ejercer un control más directo de los permisos.

Por ejemplo, Apps Script podría otorgar al proyecto de secuencia de comandos de un complemento el alcance muy permisivo https://mail.google.com de forma predeterminada. Cuando un usuario autoriza un proyecto de secuencia de comandos con este alcance, se le otorga acceso completo a la cuenta de Gmail del usuario. En el caso de los complementos publicados, debes reemplazar este permiso por un conjunto más limitado que cubra las necesidades del complemento y nada más.

Puedes establecer de forma explícita los permisos que usa tu proyecto de secuencia de comandos editando su archivo de manifiesto. El campo del manifiesto oauthScopes es un array de todos los permisos que usa el complemento. Para establecer los alcances de tu proyecto, haz lo siguiente:

1. Consulta los alcances que usa tu complemento. Determina qué cambios se deben realizar, como usar un alcance más limitado.
2. Abre el archivo de manifiesto del complemento.
3. Ubica el campo de nivel superior etiquetado como oauthScopes. Si no está presente, puedes agregarlo.

4. El campo oauthScopes especifica un array de cadenas. Para establecer los permisos que usa tu proyecto, reemplaza el contenido de este array por los permisos que deseas que use. Por ejemplo, para un complemento de Google Workspace que extiende Gmail, podrías tener lo siguiente:

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      ...
    }
   

5. Guarda los cambios en el archivo de manifiesto.

Verificación de OAuth

El uso de ciertos permisos sensibles de OAuth puede requerir que tu complemento se someta a la verificación del cliente de OAuth antes de que puedas publicarlo. Si deseas obtener más información, consulta las siguientes guías:

• Verificación de clientes de OAuth para Apps Script
• Apps no verificadas
• Preguntas frecuentes sobre la verificación de OAuth
• Servicios de las APIs de Google: Política de Datos del Usuario

Permisos restringidos

Algunos permisos son restringidos y están sujetos a reglas adicionales que ayudan a proteger los datos del usuario. Si planeas publicar un complemento de Gmail o del Editor que use uno o más permisos restringidos, el complemento debe cumplir con todas las restricciones especificadas antes de que se pueda publicar.

Revisa la lista completa de los permisos restringidos antes de intentar publicar. Si tu complemento usa alguno de ellos, debes cumplir con los requisitos adicionales para permisos específicos de API antes de publicarlo.

La extensión de Herramientas para desarrolladores de Google Workspace para Visual Studio Code proporciona información de diagnóstico para todos los permisos, incluida la descripción del permiso y si es sensible o restringido.

Elige permisos para los complementos de Google Workspace

En las siguientes secciones, se proporcionan los alcances que se suelen usar para los complementos de Google Workspace.

Permisos del editor

Los siguientes permisos de uso frecuente para los complementos de Google Workspace extienden Documentos de Google, Hojas de cálculo de Google y Presentaciones de Google.

Gmail

Existen permisos creados específicamente para los complementos de Google Workspace que ayudan a proteger los datos de los usuarios de Gmail. Agrega estos permisos de forma explícita al manifiesto del complemento, junto con cualquier otro que se requiera.

En la siguiente tabla, se enumeran los permisos que se usan con frecuencia para los complementos de Google Workspace que extienden Gmail. Si tu complemento extiende Gmail, debes agregar todos los alcances etiquetados como Obligatorios al manifiesto de tu complemento de Google Workspace.

Reemplaza el permiso amplio https://mail.google.com por un conjunto más reducido de permisos que permitan las interacciones que necesita tu complemento.

Permisos del Calendario de Google

En la siguiente tabla, se enumeran los permisos de uso frecuente para los complementos de Google Workspace que extienden el Calendario de Google.

Permisos de Google Chat

Para llamar a la API de Google Chat, autentícate como el usuario de Google Chat o como la app de Google Chat. Cada tipo de autenticación requiere diferentes alcances, y no todos los métodos de la API de Chat admiten la autenticación de la app.

Para obtener más información sobre los permisos y los tipos de autenticación de Chat, consulta la Descripción general de la autenticación y la autorización de la API de Chat.

En la siguiente tabla, se muestran los métodos y los alcances de la API de Chat que se usan con frecuencia según los tipos de autenticación admitidos:

Permisos de Google Drive

En la siguiente tabla, se enumeran los alcances de uso frecuente para los complementos de Google Workspace que extienden Google Drive.

Tokens de acceso

Para proteger los datos del usuario, los alcances de Gmail que se usan en los complementos de Google Workspace otorgan acceso temporal a los datos del usuario. Para habilitar el acceso temporal, llama a GmailApp.setCurrentMessageAccessToken con un token de acceso de un objeto de evento de acción.

El token de acceso que habilita los permisos de Gmail no es el mismo que el token de acceso que devuelve ScriptApp.getOAuthToken. Usa el token proporcionado en el objeto del evento de acción.

A continuación, se muestra un ejemplo de cómo configurar un token de acceso para permitir el acceso a los metadatos de un mensaje. El único alcance necesario para este ejemplo es https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Otros alcances de Google Workspace

Es posible que tu complemento requiera permisos adicionales si usa otros servicios de Google Workspace o Apps Script. En la mayoría de los casos, Apps Script detecta estos permisos y actualiza el manifiesto automáticamente. Cuando edites la lista de permisos del manifiesto, no quites ninguno, a menos que los reemplaces por una alternativa más restringida.

En la siguiente tabla, se muestran los alcances que suelen usar los complementos de Google Workspace: