Eseguire l'autenticazione come progetto Google Apps Script utilizzando i service account

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

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

Quando utilizzare gli account di servizio in Apps Script

Per impostazione predefinita, Apps Script utilizza le credenziali dell'utente dello script per chiamare le API. Se chiami le API di Google utilizzando UrlFetchApp, puoi ottenere un token di accesso per l'utente dello script chiamando ScriptApp.getOAuthToken.

Tuttavia, in alcuni scenari, l'utilizzo degli account di servizio offre diversi vantaggi rispetto a ScriptApp.getOAuthToken. Valuta la possibilità di utilizzare l'autenticazione dell'account di servizio per i seguenti motivi:

• Migliori prestazioni con le API Cloud e i servizi Google Cloud: molte API Cloud di Google sono progettate per l'autenticazione dell'account di servizio. 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 con altri utenti. Utilizzando i service account, puoi condividere gli 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 input dell'utente.
• Sicurezza avanzata e principio del privilegio minimo: concedi ai service account autorizzazioni specifiche, fornendo l'accesso solo alle risorse di cui hanno bisogno. Questo segue 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 vengono gestiti utilizzando Identity and Access Management (IAM) di Google Cloud. IAM aiuta le organizzazioni Google Workspace a gestire l'accesso ai servizi autenticati all'interno dei progetti Apps Script.

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

Crea un account di servizio

Nel progetto Cloud, crea un account di servizio:

Assegna un ruolo all'account di servizio

È necessario assegnare un ruolo predefinito o personalizzato a un service account da un account di super amministratore.

1. Nella Console di amministrazione Google, vai a Menu 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 account di servizio.

4. Inserisci l'indirizzo email del service account.

5. Fai clic su Aggiungi > Assegna ruolo.

Crea le credenziali per un account di servizio

Per ottenere le credenziali per il tuo account di servizio:

1. Nella console Google Cloud, vai a Menu menu > IAM e amministrazione > Account di servizio.

   Vai a Service account

2. Seleziona il tuo account di servizio.
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 tua directory di lavoro. Questo file è l'unica copia di questa chiave. Per informazioni su come archiviare la chiave in modo sicuro, consulta la sezione Gestire le chiavi degli account di servizio.

5. Fai clic su Chiudi.

Copia il numero del progetto Cloud

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

   Vai a IAM e amministrazione > Impostazioni

2. Nel campo Numero progetto, copia il valore.

Configura l'autenticazione dell'account di servizio nel progetto Apps Script

Questa sezione spiega come aggiungere le credenziali dell'account di servizio dal progetto Cloud a un progetto Apps Script.

Imposta 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, fai clic su Cambia progetto.

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

5. Fai clic su Imposta progetto.

Salva le credenziali come proprietà dello script

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

1. Copia i contenuti del file JSON dell'account di servizio (credentials.json) che hai creato nella sezione precedente.
2. Nel progetto Apps Script, vai a Impostazioni progetto settings.
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 il contenuto del file chiave JSON.
4. Fai clic su Salva proprietà script.

Aggiungi la libreria OAuth2

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

Per aggiungere la libreria al progetto Apps Script:

1. Nell'editor di Apps Script, a sinistra, accanto a Librerie, fai clic su Aggiungi una libreria add.
2. Nel campo ID script, inserisci 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Fai clic su Cerca.
4. Seleziona la versione più recente, quindi fai clic su Aggiungi.

Chiama un'API utilizzando le credenziali dell'account di servizio

Per utilizzare le credenziali dell'account di servizio dal 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 dell'account di servizio 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 UrlFetch servizio:

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

• Creare credenziali di accesso
• Eseguire l'autenticazione come app di Google Chat