Autenticarsi come progetto Apps Script utilizzando i service account

Questa guida spiega come eseguire l'autenticazione con un service account quando chiami le API in Apps Script.

Un service account è un tipo speciale di account utilizzato da un'applicazione, anziché da una persona. Puoi utilizzare un service account per accedere ai dati o eseguire azioni tramite l'account robot oppure per accedere ai dati per conto degli utenti di Google Workspace o Cloud Identity. Per saperne di più, consulta Informazioni sui service account.

Per una panoramica sull'autenticazione per le API Google Workspace, vedi Creare credenziali di accesso.

Quando utilizzare i service account in Apps Script

Ecco alcuni motivi per cui potresti prendere in considerazione l'utilizzo dell'autenticazione dell'account di servizio anziché altri metodi di autenticazione come ScriptApp.getOAuthToken():

• Prestazioni migliori con le API e i servizi Google Cloud: molte API Google Cloud sono progettate per l'autenticazione dei service account. I service account possono anche fornire un modo più integrato, affidabile e sicuro per interagire con la maggior parte delle API.
• Autorizzazioni disaccoppiate: i service account hanno le proprie autorizzazioni, separate da quelle di qualsiasi utente. Il metodo di autenticazione ScriptApp.getOAuthToken() può non riuscire quando condividi il progetto Apps Script con altri utenti. Utilizzando gli account di servizio, puoi condividere script e pubblicarli come componenti aggiuntivi di Google Workspace.
• Script automatizzati e attività a lunga esecuzione: i service account ti consentono di eseguire script automatizzati, processi batch o attività in background senza l'intervento dell'utente.
• Sicurezza avanzata e principio del privilegio minimo: puoi concedere autorizzazioni specifiche ai service account, fornendo l'accesso solo alle risorse di cui hanno bisogno. Ciò è in linea con il principio del privilegio minimo, che riduce i rischi per la sicurezza. L'utilizzo di ScriptApp.getOAuthToken() spesso concede a uno script tutte le autorizzazioni utente, che possono essere troppo ampie.
• Gestione centralizzata degli accessi: i service account sono gestiti utilizzando Identity and Access Management (IAM) di Google Cloud. IAM può aiutare le organizzazioni Google Workspace a gestire l'accesso ai servizi autenticati all'interno dei progetti Apps Script.

Prerequisiti

• Un progetto Google Cloud.
• Nel tuo progetto Cloud, attiva le API con cui vuoi eseguire l'autenticazione utilizzando le credenziali del service account.
• Per assegnare ruoli agli account di servizio, devi disporre dei privilegi di super amministratore.

Crea un account di servizio

Nel tuo progetto Cloud, crea un service account:

Console Google Cloud

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Fai clic su Crea account di servizio.
3. Compila i dettagli del service account, quindi fai clic su Crea e continua.
   Nota: per impostazione predefinita, Google crea un ID service account univoco. Se vuoi modificare l'ID, modificalo nel campo ID account di servizio.
4. (Facoltativo) Assegna ruoli al service account per concedere l'accesso alle risorse del progetto Google Cloud. Per ulteriori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
5. Fai clic su Continua.
6. (Facoltativo) Inserisci gli utenti o i gruppi che possono gestire ed eseguire azioni con questo service account. Per maggiori dettagli, consulta Gestione della simulazione dell'identità dei service account.
7. Fai clic su Fine. Prendi nota dell'indirizzo email del service account.

Interfaccia a riga di comando gcloud

1. Crea l'account di servizio:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. (Facoltativo) Assegna ruoli al service account per concedere l'accesso alle risorse del progetto Google Cloud. Per ulteriori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

Assegna un ruolo al service account

Devi assegnare un ruolo predefinito o personalizzato a un service account da un account super amministratore.

1. Nella Console di amministrazione Google, vai a Menu > Account > Ruoli amministratore.

   Vai a Ruoli amministratore

2. Posiziona il puntatore del mouse sul ruolo che vuoi assegnare, quindi fai clic su Assegna amministratore.

3. Fai clic su Assegna service account.

4. Inserisci l'indirizzo email del service account.

5. Fai clic su Aggiungi > Assegna ruolo.

Crea le credenziali per un service account

Devi ottenere le credenziali sotto forma di coppia di chiavi pubblica/privata. Queste credenziali vengono utilizzate dal codice per autorizzare le azioni del service account all'interno della tua app.

Per ottenere le credenziali per il tuo service account:

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Seleziona il tuo service account.
3. Fai clic su Chiavi > Aggiungi chiave > Crea nuova chiave.
4. Seleziona JSON, quindi fai clic su Crea.

   Una nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come nuovo file. Salva il file JSON scaricato come credentials.json nella directory di lavoro. Questo file è l'unica copia di questa chiave. Per informazioni su come archiviare la chiave in modo sicuro, consulta la sezione Gestione delle chiavi degli account di servizio.

5. Fai clic su Chiudi.

Copia il numero del progetto cloud

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Impostazioni.

   Vai a IAM e amministrazione > Impostazioni

2. Nel campo Numero di progetto, copia il valore.

Configurare l'autenticazione del service account nel progetto Apps Script

Questa sezione spiega come aggiungere le credenziali del service account dal tuo progetto Cloud a un progetto Apps Script.

Impostare il progetto cloud in Apps Script

1. Vai ad Apps Script per aprire o creare un progetto:

   
   Apri Apps Script

2. Nel progetto Apps Script, fai clic su Impostazioni progetto .

3. In Progetto Google Cloud (GCP), fai clic su Cambia progetto.

4. In Numero di progetto Google Cloud, incolla il numero di progetto Google Cloud.

5. Fai clic su Imposta progetto.

Salva le credenziali come proprietà dello script

Archivia in modo sicuro le credenziali del service account salvandole come proprietà dello script nelle impostazioni del progetto Apps Script:

1. Copia i contenuti del file JSON dell'account di servizio (credentials.json) che hai creato nella sezione precedente.
2. Nel tuo progetto Apps Script, vai a Impostazioni progetto .
3. Nella pagina Impostazioni progetto, vai a Proprietà script e fai clic su Aggiungi proprietà script e inserisci quanto segue:
   • Nel campo Proprietà, inserisci SERVICE_ACCOUNT_KEY.
   • Nel campo Valore, incolla i contenuti del file chiave JSON.
4. Fai clic su Salva proprietà script.

Aggiungere la libreria OAuth2

Per gestire il flusso di autenticazione OAuth2, puoi utilizzare la libreria Apps Script apps-script-oauth2.

Per aggiungere la libreria al tuo progetto Apps Script:

1. Nell'editor Apps Script, a sinistra, accanto a Librerie, fai clic su Aggiungi una libreria .
2. Nel campo ID script, inserisci 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Fai clic su Cerca.
4. Seleziona l'ultima versione e poi fai clic su Aggiungi.

Chiama un'API utilizzando le credenziali del service account

Per utilizzare le credenziali del service account dal tuo progetto Apps Script, puoi utilizzare la seguente funzione getServiceAccountService():

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

Sostituisci SCOPE con l'ambito di autorizzazione necessario per chiamare l'API. Lo script utilizza le credenziali del service account che hai salvato come proprietà dello script SERVICE_ACCOUNT_KEY nel passaggio precedente.

Puoi quindi utilizzare queste credenziali per chiamare un'API, come mostrato nell'esempio seguente con il servizio UrlFetch:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

Sostituisci API_URL con l'endpoint HTTP che stai chiamando.

Argomenti correlati

• Crea credenziali di accesso
• Autenticarsi come app Google Chat