Uwierzytelnianie jako projekt Apps Script za pomocą kont usługi

W tym przewodniku dowiesz się, jak uwierzytelniać się za pomocą konta usługi podczas wywoływania interfejsów API w Apps Script.

Konto usługi to specjalne konto używane przez aplikację, a nie przez osobę. Konta usługi możesz używać do uzyskiwania dostępu do danych lub wykonywania działań przez konto robota albo do uzyskiwania dostępu do danych w imieniu użytkowników Google Workspace lub Cloud Identity. Więcej informacji znajdziesz w artykule Konta usługi.

Omówienie uwierzytelniania w interfejsach Google Workspace API znajdziesz w artykule Tworzenie danych logowania.

Kiedy używać kont usługi w Apps Script

Oto kilka powodów, dla których warto rozważyć użycie uwierzytelniania za pomocą konta usługi zamiast innych metod uwierzytelniania, takich jak ScriptApp.getOAuthToken():

Lepsza wydajność dzięki interfejsom API i usługom Google Cloud: wiele interfejsów API Google Cloud jest przeznaczonych do uwierzytelniania kont usługi. Konta usługi mogą też zapewniać bardziej zintegrowany, niezawodny i bezpieczny sposób interakcji z większością interfejsów API.
Oddzielne uprawnienia: konta usługi mają własne uprawnienia, niezależne od uprawnień użytkowników. Metoda uwierzytelnianiaScriptApp.getOAuthToken() może zawieść, gdy udostępnisz projekt Apps Script innym użytkownikom. Korzystając z kont usług, możesz udostępniać skrypty i publikować je jako dodatki do Google Workspace.
Automatyczne skrypty i długotrwałe zadania: konta usługi umożliwiają uruchamianie automatycznych skryptów, procesów wsadowych lub zadań w tle bez udziału użytkownika.
Większe bezpieczeństwo i zasada minimalnego wymaganego poziomu uprawnień: możesz przyznawać kontom usługi konkretne uprawnienia, zapewniając dostęp tylko do potrzebnych im zasobów. Jest to zgodne z zasadą minimalnego wymaganego poziomu uprawnień, która zmniejsza ryzyko związane z bezpieczeństwem. Użycie ScriptApp.getOAuthToken() często przyznaje skryptowi wszystkie uprawnienia użytkownika, co może być zbyt szerokie.
Scentralizowane zarządzanie dostępem: konta usługi są zarządzane za pomocą usługi Identity and Access Management (IAM) w Google Cloud. IAM może pomóc organizacjom korzystającym z Google Workspace w zarządzaniu dostępem do uwierzytelnionych usług w projektach Apps Script.

Wymagania wstępne

Projekt Google Cloud.
W projekcie Cloud włącz interfejsy API, w których chcesz uwierzytelniać się za pomocą danych logowania konta usługi.
Aby przypisywać role do kont usługi, musisz mieć uprawnienia superadministratora.

Tworzenie konta usługi

W projekcie Cloud utwórz konto usługi:

Konsola Google Cloud

W konsoli Google Cloud otwórz Menu > Administracja > Konta usługi.
Otwórz stronę Konta usługi
Kliknij Utwórz konto usługi.
Wpisz szczegóły konta usługi, a następnie kliknij Utwórz i kontynuuj.
Uwaga: domyślnie Google tworzy unikalny identyfikator konta usługi. Jeśli chcesz zmienić identyfikator, zmodyfikuj go w polu identyfikatora konta usługi.
Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.
Kliknij Dalej.
Opcjonalnie: wpisz użytkowników lub grupy, które mogą zarządzać tym kontem usługi i wykonywać na nim działania. Więcej informacji znajdziesz w artykule Zarządzanie przejmowaniem tożsamości konta usługi.
Kliknij Gotowe. Zanotuj adres e-mail konta usługi.

interfejs wiersza poleceń gcloud

Utwórz konto usługi:

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

Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.

Przypisywanie roli do konta usługi

Do konta usługi musisz przypisać gotową lub niestandardową rolę za pomocą konta superadministratora.

W konsoli administracyjnej Google otwórz Menu> Konto > Role administratora.

Otwórz Role administratora
Wskaż rolę, którą chcesz przypisać, a następnie kliknij Przypisz administratora.
Kliknij Przypisz konta usługi.
Wpisz adres e-mail konta usługi.
Kliknij Dodaj> Przypisz rolę.

Tworzenie danych logowania do konta usługi

Musisz uzyskać dane logowania w postaci pary kluczy publiczny/prywatny. Te dane logowania są używane przez kod do autoryzowania działań konta usługi w aplikacji.

Aby uzyskać dane logowania do konta usługi:

W konsoli Google Cloud otwórz Menu > Administracja > Konta usługi.
Otwórz stronę Konta usługi
Wybierz konto usługi.
Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
Wybierz JSON, a potem kliknij Utwórz.
Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Jest to jedyna kopia tego klucza. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w artykule Zarządzanie kluczami konta usługi.
Kliknij Zamknij.

Skopiuj numer projektu Cloud

W konsoli Google Cloud kliknij Menu > Administracja > Ustawienia.
Otwórz Ustawienia w obszarze Administracja
W polu Numer projektu skopiuj wartość.

Konfigurowanie uwierzytelniania konta usługi w projekcie Apps Script

Z tej sekcji dowiesz się, jak dodać dane logowania konta usługi z projektu Cloud do projektu Apps Script.

Ustawianie projektu Cloud w Apps Script

Otwórz Apps Script, aby otworzyć lub utworzyć projekt:

Otwórz Apps Script
W projekcie Apps Script kliknij Ustawienia projektu .
W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
W sekcji Numer projektu GCP wklej numer projektu Google Cloud.
Kliknij Ustaw projekt.

Zapisywanie danych logowania jako właściwości skryptu

Bezpiecznie przechowuj dane logowania konta usługi, zapisując je jako właściwość skryptu w ustawieniach projektu Apps Script:

Skopiuj zawartość pliku JSON konta usługi (credentials.json) utworzonego w poprzedniej sekcji.
W projekcie Apps Script otwórz Ustawienia projektu .
Na stronie Ustawienia projektu otwórz Właściwości skryptu i kliknij Dodaj właściwość skryptu, a następnie wpisz te wartości:
- W polu Property (Usługa) wpisz SERVICE_ACCOUNT_KEY.
- W polu Wartość wklej zawartość pliku klucza JSON.
Kliknij Zapisz właściwości skryptu.

Dodawanie biblioteki OAuth2

Do obsługi procesu uwierzytelniania OAuth2 możesz użyć biblioteki Apps Scriptapps-script-oauth2.

Aby dodać bibliotekę do projektu Apps Script:

W edytorze Apps Script po lewej stronie obok Biblioteki kliknij Dodaj bibliotekę .
W polu Identyfikator skryptu wpisz 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
Kliknij Wyszukaj.
Wybierz najnowszą wersję, a potem kliknij Dodaj.

Wywoływanie interfejsu API za pomocą danych logowania konta usługi

Aby użyć danych logowania konta usługi z projektu Apps Script, możesz użyć tej funkcji: 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);
}

Zastąp SCOPE zakresem autoryzacji, który jest potrzebny do wywołania interfejsu API. Skrypt używa danych logowania konta usługi zapisanych jako właściwość skryptu SERVICE_ACCOUNT_KEY w poprzednim kroku.

Możesz następnie użyć tych danych logowania do wywołania interfejsu API, jak pokazano w poniższym przykładzie z usługą 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;
}

Zastąp API_URL wywoływanym punktem końcowym HTTP.