Permisos de autorización para complementos de Editor

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 podría usar el alcance "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 alcance le solicita al usuario que permita que el complemento vea y administre los documentos en los que se instaló esta aplicación.

Nota: El alcance de currentonly solo está disponible en los servicios de Apps Script. Esto no incluye los servicios avanzados de Apps Script ni las llamadas directas a las APIs de Google Workspace.

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

Advertencia: Siempre usa el conjunto de permisos más restrictivo posible. Para proteger la información del usuario, los complementos y otras aplicaciones publicadas nunca deben solicitar más permisos de alcance de los que realmente necesitan. Los permisos que requiere tu complemento se examinan durante el proceso de revisión del complemento de publicación. Si el complemento usa permisos demasiado amplios, no puede pasar la revisión.

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

Nota: Evita usar permisos restringidos en tu complemento si puedes. Es más fácil aprobar la revisión del complemento para su publicación pública si no los usas. Puedes usar los permisos restringidos libremente para los complementos no públicos.

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.

Permisos del complemento del editor

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

Apps Script determina automáticamente los alcances 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 del Editor, a menudo puedes confiar en esta recopilación automática de permisos en lugar de determinar los permisos por tu cuenta y establecerlos de forma explícita.

Si no configuras tus permisos de forma explícita y tu complemento del Editor solo lee o escribe en el archivo del 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 permisos de archivo del editor que establece en currentonly. Por ejemplo, si agregas este comentario a un archivo de proyecto de secuencia de comandos de un complemento de Hojas de cálculo, especificas que el complemento solo necesita permiso para operar en la hoja abierta 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 no tiene abierta.

Nota: El alcance de currentonly solo está disponible en los servicios de Apps Script. Esto no incluye los servicios avanzados de Apps Script ni las llamadas directas a las APIs de Google Workspace.