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 les indica a los usuarios qué permisos solicita la secuencia de comandos. Por ejemplo, una secuencia de comandos podría solicitar permiso para leer mensajes de correo electrónico o crear eventos de 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 requeridos. Puedes ver los permisos 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. Las aplicaciones publicadas, como los complementos, deben usar los permisos más específicos posibles.

Durante el flujo de autorización, Apps Script presenta descripciones legibles de los alcances requeridos. Por ejemplo, si tu secuencia de comandos necesita acceso de solo lectura a las hojas de cálculo, el manifiesto podría incluir el alcance https://www.googleapis.com/auth/spreadsheets.readonly. El mensaje de autorización le solicita al usuario que "vea tus hojas de cálculo de Google".

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

En algunas plataformas, como el IDE de Apps Script, los usuarios ven la pantalla de consentimiento detallado de OAuth. Esta pantalla permite a los usuarios seleccionar permisos específicos para otorgar en lugar de otorgar todos los permisos a la vez. Diseña tu secuencia de comandos para controlar los permisos de OAuth detallados.

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 info_outline.
3. Consulta los permisos en Project OAuth Scopes.

Establece permisos explícitos

Apps Script determina automáticamente los permisos requeridos analizando el código en busca de llamadas a funciones. Si bien esto es suficiente para la mayoría de las secuencias de comandos, debes ejercer un control más directo para los complementos publicados, las apps web, las apps de Chat y las llamadas a la API de Chat.

A veces, Apps Script asigna automáticamente permisos amplios. Esto puede significar que tu secuencia de comandos les solicita a los usuarios más acceso del que necesita. En el caso de las secuencias de comandos publicadas, reemplaza los permisos amplios por un conjunto limitado que satisfaga las necesidades de la secuencia de comandos.

Puedes establecer de forma explícita los permisos que usa tu proyecto de secuencia de comandos editando su archivo de manifiesto. El campo oauthScopes del manifiesto es un array de 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 settings.
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 code.
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. Reemplaza el contenido del array oauthScopes por los permisos que deseas que use el proyecto. 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 save.

Cómo controlar los permisos detallados de OAuth

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. Con el tiempo, la pantalla de consentimiento se lanzará progresivamente en otras plataformas, como macros, activadores y complementos. 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. Esto les brinda a los usuarios un control detallado sobre los datos de la cuenta que comparten con cada secuencia de comandos. Por ejemplo, si una secuencia de comandos solicita permisos de correo electrónico y calendario, los usuarios pueden optar por otorgar permiso de Calendario, pero no de Gmail.

En las siguientes secciones, se describe cómo controlar los permisos de OAuth detallados.

Solicitar permiso automáticamente para los alcances necesarios

Si un flujo de ejecución requiere alcances específicos, puedes solicitar a los usuarios que otorguen esos permisos. Tu secuencia de comandos puede verificar los permisos y solicitarlos automáticamente si faltan.

Los siguientes métodos de la clase ScriptApp validan los permisos y renderizan el mensaje de autorización:

• requireScopes(authMode, oAuthScopes): Usa este método para los flujos que dependen de permisos específicos.
• requireAllScopes(authMode): Usa este método si un flujo de ejecución depende de todos los permisos del proyecto.

Ejemplo

En el siguiente ejemplo, se muestra cómo llamar a requireScopes() y requireAllScopes(). 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("dana@example.com", "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("dana@example.com", "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 permisos faltantes

Puedes recuperar el estado de permiso de los usuarios y diseñar experiencias personalizadas. Por ejemplo, puedes inhabilitar las funciones que requieren permisos faltantes o mostrar un diálogo en el que se explique el requisito. Los siguientes métodos recuperan 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): Verifica el estado de permiso para alcances específicos.
• getAuthorizationInfo(authMode): Verifica el estado de permiso para todos los permisos del proyecto.

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

Ejemplo

En el siguiente ejemplo, se muestra cómo usar getAuthorizationInfo() para omitir funciones en las que los usuarios no otorgaron los permisos requeridos. Esto permite que el resto del flujo de ejecución continúe sin 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("dana@example.com", "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 se ejecutan automáticamente, y es posible que los usuarios no estén presentes para otorgar permisos. Te recomendamos que uses requireScopes(authMode, oAuthScopes) antes de instalar un dispositivo de activación. 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 aplicación 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
• Servicios 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 publicas una app que usa alcances restringidos, debe cumplir con todas las especificaciones.

Revisa la lista completa de permisos restringidos antes de publicar. Las apps que cumplan con los requisitos deben seguir los Requisitos adicionales para permisos específicos de la API.

Si es posible, evita usar permisos restringidos para simplificar el proceso de revisión. Puedes usar los alcances restringidos libremente para las apps no públicas.