Permisos

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

Durante este flujo, el mensaje le indica al usuario qué permiso quiere obtener la aplicación. Por ejemplo, un complemento puede solicitar 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 alcances de OAuth.

Declaras los alcances en tu manifiesto con cadenas de URL. Durante el flujo de autorización, Apps Script presenta al usuario una descripción legible por humanos del permiso. Por ejemplo, tu complemento de Google Workspace podría usar el permiso "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 le permita hacer lo siguiente: Ver tus mensajes de correo electrónico cuando se esté ejecutando.

Cómo ver los permisos

Para ver los alcances que requiere actualmente 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 "Alcances de OAuth del proyecto".

También puedes ver los alcances actuales del proyecto de secuencia de comandos en el manifiesto del proyecto, debajo del campo oauthScopes, pero solo si configuraste esos alcances de forma explícita.

Cómo configurar permisos explícitos

Apps Script determina automáticamente qué alcances necesita una secuencia de comandos a través de un análisis de su código en busca de llamadas a función 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 alcances.

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

Puedes establecer de forma explícita los alcances 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 permisos de tu proyecto, sigue estos pasos:

1. Consulta los permisos que usa actualmente tu complemento. Determina qué cambios se deben realizar, como usar un alcance más estrecho.
2. Abre el archivo de manifiesto de tu complemento.
3. Busca 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 de OAuth sensibles puede requerir que el complemento pase por una verificación de cliente de OAuth antes de que puedas publicarlo. Si deseas obtener más información, consulta las siguientes guías:

• Verificación de cliente de OAuth para Apps Script
• Apps sin verificar
• Preguntas frecuentes sobre la verificación de OAuth
• Política de Datos del Usuario del Servicio de las APIs de Google

Permisos restringidos

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

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

Elige los permisos de los complementos de Google Workspace

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

Permisos de editor

A continuación, se muestran los permisos de uso frecuente para los complementos de Google Workspace que extienden Documentos, Hojas de cálculo y Presentaciones.

Gmail

Hay algunos permisos que se crearon específicamente para los complementos de Google Workspace para ayudar a proteger los datos de Gmail del usuario. Debes agregar estos permisos de forma explícita a tu manifiesto de complementos, junto con cualquier otro que requiera el código del complemento.

A continuación, se muestran los permisos de uso frecuente para los complementos de Google Workspace que extienden Gmail. Los que se etiquetan como Obligatorios se deben agregar al manifiesto del complemento de Google Workspace si tu complemento extiende Gmail.

Asegúrate de reemplazar el permiso https://mail.google.com muy amplio en tu complemento por un conjunto de permisos más estrecho que permita las interacciones que necesita tu complemento y nada más.

Permisos del Calendario de Google

A continuación, se muestran 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 Chat, debes autenticarte como el usuario de Google Chat o como la app de Chat. Cada tipo de autenticación requiere diferentes permisos, y no todos los métodos de la API de Chat admiten la autenticación de apps.

Para obtener más información sobre los permisos de Chat y los tipos de autenticación, 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 compatibles:

Permisos de Google Drive

A continuación, se muestran los permisos de uso frecuente para los complementos de Google Workspace que extienden Google Drive.

Tokens de acceso

Para proteger los datos del usuario, los permisos de Gmail que se usan en los complementos de Google Workspace solo otorgan acceso temporal a los datos del usuario. Para habilitar el acceso temporal, debes llamar a la función GmailApp.setCurrentMessageAccessToken(accessToken) con un token de acceso como argumento. Debes obtener un token de acceso de un objeto de 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 permisos de Google Workspace

Es posible que tu complemento requiera alcances adicionales si usa otros servicios de Google Workspace o Apps Script. En la mayoría de los casos, puedes permitir que Apps Script detecte estos permisos y actualice el manifiesto automáticamente. Cuando edites la lista de alcances de tu manifiesto, no quites ningún alcance, a menos que lo reemplaces por una alternativa más apropiada, como un alcance más estrecho.

En la siguiente tabla, se muestra una lista de los permisos que suelen usar los complementos de Google Workspace: