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 el manifiesto con cadenas de URL. Durante el flujo de autorización, Apps Script le presenta al usuario una descripción del alcance que es legible. 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.

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

Configuración de permisos explícitos

Apps Script determina automáticamente qué permisos necesita una secuencia de comandos 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 https://mail.google.com muy permisivo de forma predeterminada. Cuando un usuario autoriza un proyecto de secuencia de comandos con este alcance, se le otorga al proyecto 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 satisfaga 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 permisos que usa actualmente 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 alcances que usa tu proyecto, reemplaza el contenido de este array por los alcances 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 pase por 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
• Servicio 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 de 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 los alcances de API específicos 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 de edición

A continuación, se incluyen los permisos que se usan con frecuencia para los complementos de Google Workspace que extienden Documentos, Hojas de cálculo y Presentaciones.

Gmail

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

A continuación, se indican los permisos que se usan con frecuencia para los complementos de Google Workspace que extienden Gmail. Los que están etiquetados como Obligatorios se deben agregar al manifiesto del complemento de Google Workspace si este extiende Gmail.

Asegúrate de reemplazar el alcance https://mail.google.com muy amplio de tu complemento por un conjunto más reducido de alcances que permitan las interacciones que necesita tu complemento y nada más.

Permisos de Calendario de Google

A continuación, se indican los permisos que se usan con frecuencia 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 usuario de Google Chat o como app de 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 alcances 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

A continuación, se indican los alcances que se usan con frecuencia 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 alcances 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 permisos de tu manifiesto, no quites ningún permiso, a menos que lo reemplaces por una alternativa más adecuada, como un permiso más específico.

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