Permisos de autorización para complementos del editor

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, la solicitud 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 manifest 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 podría usar el permiso "Leer el documento actual", que se escribe en tu manifiesto como https://www.googleapis.com/auth/documents.currentonly. Durante el flujo de autorización, un complemento con este permiso le solicita al usuario que le permita hacer lo siguiente: Ver y administrar los documentos en los que se instaló esta aplicación.

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 .
  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 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 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 manifest. 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 Editor que extiende Hojas de cálculo, podrías tener lo siguiente:

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}

  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:

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, el complemento 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.

Permisos del complemento del editor

Cuando compilas un complemento de Editor, el servicio de Apps Script y los métodos que usa el código del complemento determinan los permisos necesarios. Por ejemplo, un complemento de Hojas de cálculo podría necesitar el permiso https://www.googleapis.com/auth/spreadsheets.readonly para leer información de diferentes Hojas de cálculo de Google.

Apps Script determina automáticamente los permisos que requieren los servicios que usas a medida que agregas código a tu proyecto de secuencia de comandos. En el caso de los complementos de Editor, a menudo puedes confiar en esta recopilación automática de permisos en lugar de determinarlos por tu cuenta y configurarlos de forma explícita.

Si no configuras tus alcances de forma explícita y tu complemento de editor solo lee o escribe en el archivo de editor abierto, agrega el siguiente comentario a uno de los archivos de tu proyecto de secuencia de comandos:

  /**
   * @OnlyCurrentDoc
   */

Este comentario le indica a Apps Script que reduzca los alcances de los archivos del editor que establece en currentonly. Por ejemplo, si agregas este comentario a un archivo de proyecto de secuencia de comandos de complemento de Hojas de cálculo de Google, especificas que el complemento solo necesita permiso para operar en la hoja abierta actualmente y no en ninguna otra hoja que el usuario pueda tener en Google Drive. Por el contrario, no debes usar este comentario si tu complemento de Hojas de cálculo necesita leer o escribir datos en una hoja que el usuario aún no abrió.