Alcances de la autorización

Los usuarios deben autorizar los proyectos de secuencias de comandos que acceden a sus datos o actúan en su nombre. Cuando un usuario ejecuta un script que requiere autorización por primera vez, la IU muestra 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 podría querer 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 permisos de OAuth.

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

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

Algunos alcances incluyen otros. Por ejemplo, cuando se autoriza el alcance https://www.googleapis.com/auth/spreadsheets, se 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, se les presenta a los usuarios la pantalla de consentimiento detallado de OAuth. 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.

Ver 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é 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, 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 alcances.

A veces, Apps Script asigna automáticamente a los proyectos alcances muy permisivos. Esto puede significar que tu secuencia de comandos le pide al usuario más de lo que necesita, lo que es una mala práctica. En el caso de las secuencias de comandos publicadas, debes reemplazar los permisos amplios por un conjunto más limitado que satisfaga las necesidades de la secuencia de comandos 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.

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 proyecto. Para establecer 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. Ubica 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 .

Cómo controlar los permisos detallados de OAuth

Nota: La pantalla de consentimiento detallado de OAuth se lanzó primero 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á progresivamente en las plataformas restantes, como macros, ejecuciones de activadores 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 detallado de OAuth permite que los usuarios especifiquen qué permisos individuales de OAuth quieren autorizar. Los permisos detallados de OAuth brindan a los usuarios un control más preciso 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 capacidades con el Calendario de Google, pero no con Gmail. Con los permisos de OAuth detallados, los usuarios pueden optar por otorgar solo permiso de Calendario, pero no de Gmail.

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

Solicitar automáticamente permiso para los alcances necesarios

Si un flujo de ejecución necesita permiso para los permisos en orden de funcionamiento, 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, si no lo hizo, 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 faltantes:

• requireScopes(authMode, oAuthScopes): Usa este método para los flujos de ejecución que dependen de uno o más permisos, pero no de todos los permisos que usa tu secuencia de comandos.
• requireAllScopes(authMode): Usa este método si un flujo de ejecución depende de todos los permisos 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 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 el estado de sus permisos. Por ejemplo, puedes decidir desactivar funciones específicas de tu secuencia de comandos que requieren permisos que el usuario no otorgó o presentar un diálogo personalizado que explique los permisos faltantes. Los siguientes métodos obtienen un objeto con la información de permisos del usuario, que incluye los alcances que autorizó el usuario y una URL para solicitar los alcances faltantes:

• getAuthorizationInfo(authMode, oAuthScopes): Usa este método para verificar el estado de permiso de alcances específicos.
• getAuthorizationInfo(authMode): Usa este método para verificar el estado del permiso 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 alcances 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 requeridos. 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 los activadores tengan permisos

Las funciones asociadas con los activadores pueden ejecutarse 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

Algunos 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 someterse a la verificación del cliente de OAuth antes de que puedas publicarlo de forma pública como una app web o un complemento. 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

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 planeas 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 los permisos restringidos antes de intentar publicar. Si tu app usa alguno de ellos, 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 los alcances restringidos libremente para las apps y los secuencias de comandos no públicos.