Permisos

Los usuarios deben autorizar 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 correspondiente.

Durante este flujo, el mensaje le indica al usuario qué desea hacer la aplicación. Por ejemplo, es posible que un complemento requiera permiso para leer el mensaje de correo electrónico de un usuario o crear eventos en su calendario. El proyecto de la secuencia de comandos del complemento define estos permisos individuales como permisos de OAuth.

Debes declarar los alcances en el manifiesto con strings de URL. Durante el flujo de autorización, Apps Script le presenta al usuario una descripción legible del alcance del alcance. Por ejemplo, el complemento de Google Workspace podría usar el alcance "Leer el mensaje actual", que está escrito en el manifiesto como https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Durante el flujo de autorización, un complemento con este alcance le pide al usuario que permita al complemento lo siguiente: Ver tus mensajes de correo electrónico cuando se ejecuta el complemento.

Visualiza los alcances

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

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

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

Configura permisos explícitos

Apps Script determina automáticamente qué permisos necesita una secuencia de comandos mediante el análisis de su código para las llamadas a funciones que los requieren. 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 darle a un proyecto de secuencia de comandos de 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. Para los complementos publicados, debes reemplazar este alcance por un conjunto más limitado que cubra las necesidades de los complementos y nada más.

Para configurar de forma explícita los alcances que usa tu proyecto de secuencia de comandos, edita el archivo de manifiesto. El campo de manifiesto oauthScopes es un array de todos los alcances que usa el complemento. Para configurar los alcances de tu proyecto, haz lo siguiente:

  1. Consulta los permisos que usa actualmente tu complemento. Determina qué cambios deben realizarse, por ejemplo, usar un alcance más limitado.
  2. Abre el archivo de manifiesto de tu complemento.
  3. Ubica el campo de nivel superior etiquetado como oauthScopes. Si no está presente, puedes agregarla.

  4. El campo oauthScopes especifica un array de strings. Para establecer los alcances que usa tu proyecto, reemplaza el contenido de este arreglo por los alcances que deseas que use. Por ejemplo, para un complemento de Google Workspace que extienda Gmail, es posible que tenga lo siguiente:

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

  5. Guarda los cambios del archivo de manifiesto.

Verificación de OAuth

El uso de ciertos alcances 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:

Permisos restringidos

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

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

Permisos del Calendario

A continuación, se muestran los permisos de uso frecuente de los complementos de Google Workspace que amplían el Calendario de Google.

Permiso
Accede a los metadatos del evento https://www.googleapis.com/auth/calendar.addons.execute

Es obligatorio si el complemento accede a metadatos de eventos de Calendario. Permite que el complemento acceda a los metadatos de eventos.

Cómo leer datos de eventos generados por el usuario https://www.googleapis.com/auth/calendar.addons.current.event.read

Es obligatoria si el complemento necesita leer datos de eventos generados por el usuario. Permite que el complemento acceda a datos de eventos generados por el usuario. Esos datos solo están disponibles si el campo del manifiesto addOns.calendar.eventAccess se establece en READ o READ_WRITE.

Escribe datos de eventos generados por el usuario https://www.googleapis.com/auth/calendar.addons.current.event.write

Es obligatoria si el complemento necesita escribir datos de eventos generados por el usuario. Permite que el complemento edite datos de eventos generados por el usuario. Esos datos solo están disponibles si el campo del manifiesto addOns.calendar.eventAccess se establece en WRITE o READ_WRITE.

Permisos de Drive

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

Permiso
Leer los metadatos del elemento seleccionado https://www.googleapis.com/auth/drive.addons.metadata.readonly

Es obligatorio si el complemento implementa una interfaz contextual que se activa cuando el usuario selecciona elementos en Drive. Permite que el complemento lea metadatos limitados sobre los elementos que un usuario seleccionó en Google Drive. Los metadatos se limitan al ID, el título, el tipo de MIME, la URL del ícono del elemento y si el complemento tiene permiso para acceder al elemento.

Acceso por archivo https://www.googleapis.com/auth/drive.file

Se recomienda si el complemento necesita acceder a archivos individuales de Drive. Otorga acceso por archivo a los archivos creados o abiertos por la app, mediante el Servicio de Drive avanzado de Apps Script. Sin embargo, esto no permite el uso de acciones similares con el servicio de Drive básico. La autorización de archivos se otorga por archivo y se revoca cuando el usuario desautoriza la aplicación.

Consulta el ejemplo de solicitud de acceso a los archivos para los archivos seleccionados.

Permisos del complemento de Gmail

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

A continuación, se muestran los permisos que se usan con frecuencia para los complementos de Google Workspace que extienden Gmail. Los etiquetados como Obligatorio deben agregarse al manifiesto del complemento de Google Workspace si este extiende Gmail.

Asegúrate de reemplazar también el alcance muy amplio de https://mail.google.com en tu complemento por un conjunto más limitado de alcances que permitan las interacciones que necesita el complemento y no más.

Permiso
Crear borradores nuevos https://www.googleapis.com/auth/gmail.addons.current.action.compose

Es obligatorio si el complemento usa activadores de acciones de Compose. Permite que el complemento cree temporalmente mensajes en borrador y respuestas nuevos. Consulta Cómo redactar mensajes en borrador para obtener más detalles; este alcance también se usa a menudo con acciones de redacción. Requiere un token de acceso.

Leer metadatos de mensajes abiertos https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Otorga acceso temporal a los metadatos del mensaje abierto (como el asunto o los destinatarios). No permite la lectura del contenido de los mensajes y requiere un token de acceso.

Es obligatoria si el complemento usa metadatos en los activadores de acciones de redacción. En el caso de las acciones de composición, este alcance es obligatorio si un activador de composición necesita acceder a los metadatos. En la práctica, este alcance permite que un activador de Compose acceda a las listas de destinatarios (a:, cc: y bcc:) de un borrador de correo electrónico de respuesta.

Leer el contenido de los mensajes abiertos https://www.googleapis.com/auth/gmail.addons.current.message.action

Otorga acceso al contenido del mensaje abierto cuando se interactúa con el usuario, como cuando se selecciona un elemento de menú complementario. Requiere un token de acceso.

Cómo leer el contenido de una conversación abierta https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Otorga acceso temporal al contenido y los metadatos del mensaje abierto. También otorga acceso al contenido de otros mensajes en la conversación abierta. Requiere un token de acceso.

Leer los metadatos y el contenido de los mensajes https://www.googleapis.com/auth/gmail.readonly

Leer los metadatos y el contenido del correo electrónico, incluido el mensaje abierto Obligatorio si necesitas leer información sobre otros mensajes, como cuando realizas una búsqueda o lees una conversación de correo electrónico completa.

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

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.

Permiso
Acceso actual a los archivos de Documentos https://www.googleapis.com/auth/documents.currentonly

Es obligatorio si el complemento accede a la API de Documentos de Apps Script. Otorga acceso temporal al contenido del documento abierto.

Acceso a archivos actuales de Hojas de cálculo https://www.googleapis.com/auth/spreadsheets.currentonly

Es obligatoria si el complemento accede a la API de Hojas de cálculo de Apps Script. Otorga acceso temporal al contenido de la hoja de cálculo abierta.

Acceso actual a archivos de Presentaciones https://www.googleapis.com/auth/presentations.currentonly

Es obligatoria si el complemento accede a la API de Apps Script Slides. Otorga acceso temporal al contenido de la presentación abierta.

Acceso por archivo https://www.googleapis.com/auth/drive.file

Es obligatorio para que el complemento use onFileScopeGrantedTrigger y si el complemento accede a la API de Documentos, Hojas de cálculo, Presentaciones o Drive. Otorga acceso por archivo a los archivos creados o abiertos por la app, mediante el Servicio de Drive avanzado de Apps Script. Sin embargo, esto no permite el uso de acciones similares con el servicio de Drive básico. La autorización de archivos se otorga por archivo y se revoca cuando el usuario desautoriza la app.

Otros alcances

Es posible que tu complemento requiera permisos adicionales si usa otros servicios de 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 los reemplaces por una alternativa más adecuada, como un alcance más limitado.

A modo de referencia, esta es una lista de los permisos de Apps Script que a menudo se usan junto con los complementos de Google Workspace:

Permiso
Leer la dirección de correo electrónico del usuario https://www.googleapis.com/auth/userinfo.email

Permite que el proyecto lea la dirección de correo electrónico del usuario actual.

Permitir llamadas a servicios externos https://www.googleapis.com/auth/script.external_request

Permite que el proyecto realice solicitudes UrlFetch. Esto también es necesario si el proyecto usa la biblioteca OAuth2 para Apps Script.

Leer la configuración regional y la zona horaria del usuario https://www.googleapis.com/auth/script.locale

Permite que el proyecto aprenda la configuración regional y la zona horaria del usuario actual. Consulta Cómo acceder a la configuración regional y a la zona horaria del usuario para obtener más información.

Crear activadores https://www.googleapis.com/auth/script.scriptapp

Permite que el proyecto cree activadores.

Vista previa de vínculos de terceros https://www.googleapis.com/auth/workspace.linkpreview

Obligatorio si el complemento brinda una vista previa de los vínculos de un servicio de terceros. Permite que el proyecto vea un vínculo en una aplicación de Google Workspace mientras el usuario interactúa con ella. Para obtener más información, consulta Cómo obtener una vista previa de los vínculos con chips inteligentes.

Crea recursos de terceros https://www.googleapis.com/auth/workspace.linkcreate

Es obligatoria si el complemento crea recursos en un servicio de terceros. Permite que el proyecto lea la información que los usuarios envían en el formulario de creación de recursos y que inserte un vínculo al recurso en una aplicación de Google Workspace. Para obtener más información, consulta Cómo crear recursos de terceros desde el menú @.