Alcances de la autorización

Los usuarios deben autorizar los proyectos de secuencia de comandos que acceden a sus datos o actúan en su nombre. Cuando un usuario ejecuta una secuencia de comandos que requiere autorización por primera vez, la IU presenta un mensaje para iniciar el flujo de autorización.

Durante este flujo, la IU le indica al usuario lo que la secuencia de comandos quiere hacer con el permiso. Por ejemplo, una secuencia de comandos puede solicitar permiso para leer los mensajes de correo electrónico del usuario o crear eventos en su calendario. El proyecto de secuencia de comandos define estos permisos individuales como alcances de OAuth.

En la mayoría de las secuencias de comandos, Apps Script detecta automáticamente los permisos que necesitas. Puedes ver los permisos que usa una secuencia de comandos en cualquier momento. También puedes configurar los alcances de forma explícita en tu manifiesto con cadenas de URL. A veces, es necesario configurar los permisos de forma explícita para ciertas aplicaciones, como los complementos, ya que las aplicaciones publicadas siempre deben usar los permisos más limitados posibles.

Durante el flujo de autorización, Apps Script le presenta al usuario descripciones legibles por humanos de los permisos requeridos. Por ejemplo, si tu secuencia de comandos necesita acceso de solo lectura a tus hojas de cálculo, el manifiesto puede tener el permiso https://www.googleapis.com/auth/spreadsheets.readonly. Durante el flujo de autorización, una secuencia de comandos con este permiso le solicita al usuario que permita que esta aplicación "Vea tus Hojas de cálculo de Google".

Algunos permisos incluyen otros. Por ejemplo, cuando se autoriza, el permiso https://www.googleapis.com/auth/spreadsheets permite el acceso de lectura y escritura a las hojas de cálculo.

En algunas plataformas en las que se ejecutan secuencias de comandos, como cuando se ejecuta una secuencia de comandos directamente desde el IDE de Apps Script, a los usuarios se les presenta la pantalla de consentimiento de OAuth detallada. Esto permite que los usuarios seleccionen permisos específicos para otorgar en lugar de otorgar todos los permisos a la vez. Es importante diseñar tu secuencia de comandos para controlar los permisos de OAuth detallados.

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 Project OAuth Scopes.

Establece permisos explícitos

Apps Script determina automáticamente qué alcances 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, las apps web, las apps de Google Chat y las llamadas a la API de Google Chat, debes ejercer un control más directo de los permisos.

A veces, Apps Script asigna automáticamente a los proyectos permisos muy permisivos. Esto puede significar que tu secuencia de comandos le pide al usuario más de lo que necesita, lo que es una práctica inadecuada. En el caso de las secuencias de comandos publicadas, debes reemplazar los permisos amplios por un conjunto más limitado que cubra las necesidades de la secuencia de comandos y nada más.

Advertencia: Siempre usa el alcance menos permisivo 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.

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 alcances que usa el proyecto. Para configurar los permisos de tu proyecto, haz lo siguiente:

1. Abre el proyecto de secuencia de comandos.
2. A la izquierda, haz clic en Configuración del proyecto .
3. Selecciona la casilla de verificación Mostrar el archivo de manifiesto "appsscript.json" en el editor.
4. A la izquierda, haz clic en Editor .
5. A la izquierda, haz clic en el archivo appsscript.json.
6. Busca el campo de nivel superior etiquetado como oauthScopes. Si no está presente, puedes agregarlo.
7. 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:

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. En la parte superior, haz clic en Guardar .

Controla los permisos de OAuth detallados

Nota: La pantalla de consentimiento detallado de OAuth se lanzó por primera vez en el IDE de Apps Script para los usuarios que ejecutan una secuencia de comandos directamente desde Apps Script. La pantalla de consentimiento se lanzará de forma progresiva en las plataformas restantes, como macros, activadores de ejecuciones y complementos, con el tiempo. Para obtener más información, consulta Consentimiento detallado de OAuth en las ejecuciones del IDE de Google Apps Script.

La pantalla de consentimiento de OAuth detallada permite que los usuarios especifiquen qué permisos individuales de OAuth desean autorizar. Los permisos de OAuth detallados les brindan a los usuarios un control más detallado sobre los datos de la cuenta que eligen compartir con cada secuencia de comandos. Por ejemplo, imagina que desarrollas una secuencia de comandos que solicita permiso para los permisos de correo electrónico y calendario. Es posible que tus usuarios quieran usar tu secuencia de comandos solo por sus funciones con el Calendario de Google, pero no con Gmail. Con los permisos de OAuth detallados, los usuarios pueden optar por otorgar solo permiso al Calendario, pero no a Gmail.

En las siguientes secciones, se describen las principales formas de controlar los permisos de OAuth detallados.

Solicitar automáticamente el permiso para los alcances necesarios

Si un flujo de ejecución necesita permiso para los alcances para funcionar, puedes requerir que los usuarios otorguen esos permisos antes de poder usarlo. Tu secuencia de comandos puede verificar si el usuario ya otorgó el permiso y, de lo contrario, solicitárselo automáticamente.

Los siguientes métodos de la clase ScriptApp te permiten validar el permiso para los alcances requeridos y renderizar automáticamente el mensaje de autorización para solicitar los permisos que faltan:

• requireScopes(authMode, oAuthScopes): Usa este método para los flujos de ejecución que dependen de uno o más alcances, pero no de todos los que usa tu secuencia de comandos.
• requireAllScopes(authMode): Usa este método si un flujo de ejecución depende de todos los alcances que usa tu secuencia de comandos.

Ejemplo

En el siguiente ejemplo, se muestra cómo llamar a los métodos requireScopes(authMode, oAuthScopes) y requireAllScopes(authMode). La secuencia de comandos usa permisos para Gmail, Hojas de cálculo y el Calendario. La función sendEmail() solo requiere los permisos de Gmail y Hojas de cálculo, mientras que la función createEventSendEmail() requiere todos los permisos que usa la secuencia de comandos.

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

Crea una experiencia personalizada para los alcances faltantes

Puedes obtener los detalles de los permisos del usuario que ejecuta tu secuencia de comandos y diseñar una experiencia personalizada según su estado de permiso. Por ejemplo, puedes apagar funciones específicas de la secuencia de comandos que requieren permisos que el usuario no otorgó, o bien presentar un diálogo personalizado en el que se expliquen los permisos que faltan. Los siguientes métodos obtienen un objeto con la información de permisos del usuario que incluye los permisos que autorizó el usuario y una URL para que puedas solicitar los permisos faltantes:

• getAuthorizationInfo(authMode, oAuthScopes): Usa este método para verificar el estado de los permisos de alcances específicos.
• getAuthorizationInfo(authMode): Usa este método para verificar el estado de los permisos de todos los alcances que usa tu secuencia de comandos.

Para obtener los detalles del permiso del objeto de información de autorización, como una lista de los permisos que se autorizaron y una URL para solicitar los permisos faltantes, usa los métodos de la clase AuthorizationInfo.

Ejemplo

En el siguiente ejemplo, se muestra cómo llamar al método getAuthorizationInfo(authMode, oAuthScopes) para omitir funciones específicas dentro de un flujo de ejecución en el que no se otorgaron los permisos necesarios. Esto permite que el resto del flujo de ejecución continúe sin tener que solicitar la autorización de los permisos faltantes.

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("[e-mail]", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

Asegúrate de que las ejecuciones de activadores tengan permisos

Las funciones asociadas con los activadores se pueden ejecutar automáticamente en ciertos eventos, y es posible que el usuario no esté presente para proporcionar más permisos. Te recomendamos que uses requireScopes(authMode, oAuthScopes) antes de instalar un activador. Esto le solicita al usuario los permisos faltantes y no permite la instalación del activador sin ellos.

Ejemplo

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}


function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

Verificación de OAuth

Ciertos permisos de OAuth son sensibles porque permiten el acceso a los datos del usuario de Google. Si tu proyecto de secuencia de comandos usa permisos que permiten el acceso a los datos del usuario, el proyecto debe pasar por la verificación del cliente de OAuth antes de que puedas publicarlo públicamente como una app web o un complemento. Si deseas obtener más información, consulta las siguientes guías:

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

Permisos restringidos

Además de los permisos sensibles, algunos permisos se clasifican como restringidos y están sujetos a reglas adicionales que ayudan a proteger los datos del usuario. Si deseas publicar una app web o un complemento que use uno o más permisos restringidos, la app 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 app usa alguna de ellas, debes cumplir con los requisitos adicionales para permisos específicos de API antes de publicarla.

Nota: Si puedes, evita usar permisos restringidos en tu app. Es más fácil aprobar la revisión para la publicación pública si no los usas. Puedes usar libremente los permisos restringidos para apps y secuencias de comandos no públicas.