Używanie protokołu OAuth 2.0 w aplikacjach międzyserwerowych

tu tu tu tu tu tu tu tu potrzebujesz potrzebujesz tu tu żeby Więcej informacji znajdziesz w opisie uwierzytelniania w dokumentacji Google Cloud Platform.

System Google OAuth 2.0 obsługuje interakcję między serwerami, na przykład między aplikacją internetową a usługą Google. W takiej sytuacji potrzebujesz konta usługi, które należy do Twojej aplikacji, a nie do użytkownika. Twoja aplikacja wywołuje interfejsy API Google w imieniu konta usługi, więc użytkownicy nie biorą bezpośrednio udziału. Ten scenariusz jest czasem nazywany „"dwuetapowej autoryzacji OAuth”&"2LO." Powiązany termin „trzyetapowa autoryzacja OAuth” odnosi się do sytuacji, w których Twoja aplikacja wywołuje interfejsy API Google w imieniu użytkowników i w niektórych przypadkach wymagana jest zgoda użytkownika.

Zwykle aplikacja korzysta z konta usługi, gdy używa interfejsów API Google do obsługi własnych danych, a nie danych użytkownika. Na przykład aplikacja, która używa Google Cloud Datastore do przechowywania danych, używa konta usługi do uwierzytelniania wywołań interfejsu API Google Cloud Datastore.

Administratorzy domeny Google Workspace mogą również przyznawać kontu usługi uprawnienia dostępu w całej domenie, aby uzyskiwać dostęp do danych użytkowników w imieniu użytkowników domeny.

W tym dokumencie opisano, jak aplikacja może komunikować się między serwerami za pomocą protokołu OAuth 2.0, korzystając z biblioteki klienta interfejsów API Google (zalecane) lub HTTP.

Niektóre interfejsy API Google umożliwiają wykonywanie autoryzowanych wywołań interfejsu API z użyciem podpisanego tokena JWT zamiast protokołu OAuth 2.0, co pozwala zapisywać żądania sieciowe. Zobacz Załącznik: autoryzacja konta usługi bez protokołu OAuth.

Omówienie

Aby obsługiwać interakcje między serwerami, najpierw utwórz konto usługi dla swojego projektu w . Jeśli chcesz uzyskać dostęp do danych użytkowników na koncie Google Workspace, przekaż dostęp do konta usługi całej domenie.

Następnie Twoja aplikacja przygotowuje się do autoryzowanych wywołań interfejsu API, korzystając z danych logowania konta usługi i żądając tokena dostępu od serwera uwierzytelniania OAuth 2.0.

Na koniec aplikacja może użyć tokena dostępu do wywoływania interfejsów API Google.

Zalecenie: aplikacja może wykonywać te zadania, korzystając z biblioteki klienta interfejsów API Google w Twoim języku lub bezpośrednio komunikując się z systemem OAuth 2.0 przez HTTP. Mechanika interakcji uwierzytelniania serwer-serwer wymaga jednak, aby aplikacje tworzyły i kryptograficznie podpisyły tokeny internetowe JSON (JWT), a ponadto łatwo można popełnić poważne błędy, które mogą mieć poważny wpływ na bezpieczeństwo Twojej aplikacji.

Dlatego zdecydowanie zalecamy korzystanie z bibliotek takich jak biblioteki klienta interfejsów API Google, które odciągają kryptografię od kodu aplikacji.

Tworzę konto usługi

Dane logowania konta usługi obejmują wygenerowany adres e-mail, który jest unikalny i co najmniej 1 parę klucz publiczny/prywatny. Jeśli przekazywanie dostępu w całej domenie jest włączone, identyfikator klienta jest też częścią danych logowania na konto usługi.

Jeśli aplikacja działa w Google App Engine, konto usługi jest konfigurowane automatycznie podczas tworzenia projektu.

Jeśli aplikacja działa w Google Compute Engine, podczas tworzenia projektu konto usługi jest konfigurowane automatycznie, ale podczas tworzenia instancji Google Compute Engine musisz określić zakresy, do których aplikacja ma mieć dostęp. Więcej informacji znajdziesz w artykule Przygotowywanie instancji do korzystania z kont usługi.

Jeśli Twoja aplikacja nie działa w Google App Engine ani Google Compute Engine, musisz uzyskać te dane logowania w . Aby wygenerować dane logowania do konta usługi lub wyświetlić publiczne dane logowania, które zostały już wygenerowane, wykonaj te czynności:

Najpierw utwórz konto usługi:

1. Otwórz Service accounts page.
2. If prompted, select a project, or create a new one.
3. Kliknij Utwórz konto usługi.
4. W ramach serwisu szczegóły konta, wpisz nazwę, ID, i opis dla konta usługi, a następnie kliknij przycisk Utwórz i kontynuować.
5. Opcjonalnie: W Grant to konto usługa dostępu do projektu, wybierz role IAM do przyznania się do konta usługi.
6. Kliknij Kontynuuj.
7. Opcjonalnie: W Grant użytkownikom dostęp do tego konta usługi, dodawać użytkowników lub grup, które mają prawo do korzystania i zarządzania kontem serwisowym.
8. Kliknij Gotowe.
9. Kliknij Tworzenie klucza, a następnie kliknij przycisk Utwórz.

Następnie utwórz klucz konta usługi:

1. Kliknij adres e-mail utworzonego konta usługi.
2. Kliknij kartę kluczy.
3. Na liście rozwijanej dodać klucz, wybierz Utwórz nowy klucz.
4. Kliknij Utwórz.

Twoja nowa para kluczy publiczny/prywatny zostanie wygenerowana i pobrana na Twój komputer; służy jako jedyna kopia klucza prywatnego. Jesteś odpowiedzialny za bezpieczne przechowywanie. Jeśli zgubisz tę parę kluczy, będziesz musiał wygenerować nową.

W każdej chwili możesz wrócić do API Console, aby wyświetlić adres e-mail, odciski cyfrowe klucza publicznego i inne informacje oraz wygenerować dodatkowe pary kluczy publiczny/prywatny. Więcej informacji o danych logowania do konta usługi w API Consoleznajdziesz w sekcji Konta usługi w pliku pomocy API Console.

Zanotuj adres e-mail konta usługi i zapisz plik klucza prywatnego konta usługi w lokalizacji dostępnej dla Twojej aplikacji. Aplikacja potrzebuje ich do wykonywania autoryzowanych wywołań interfejsu API.

Uwaga: klucze prywatne należy bezpiecznie przechowywać zarówno w środowisku programistycznym, jak i produkcyjnym. Google nie przechowuje kopii kluczy prywatnych. Dotyczy to tylko Twoich kluczy publicznych. Więcej informacji znajdziesz w sekcji poświęconej bezpiecznym uwierzytelnianiu danych logowania klienta w zasadach OAuth 2.0.

Przekazywanie uprawnień do całej domeny kontu usługi

Jeśli masz konto Google Workspace, administrator organizacji może upoważnić aplikację do uzyskiwania dostępu do danych użytkowników w imieniu użytkowników domeny Google Workspace. Na przykład aplikacja, która używa interfejsu Google Calendar API do dodawania wydarzeń do kalendarzy wszystkich użytkowników w domenie Google Workspace, używa konta usługi do uzyskiwania dostępu do interfejsu Google Calendar API na rzecz użytkowników. Autoryzacja konta usługi w celu uzyskiwania dostępu do danych w imieniu użytkowników w domenie jest czasami nazywana „przekazywaniem uprawnień w obrębie całej domeny” do konta usługi.

Uwaga: jeśli korzystasz z Google Workspace Marketplace do instalowania aplikacji dla domeny, wymagane uprawnienia są przyznawane automatycznie podczas instalacji. Nie musisz ręcznie autoryzować kont usługi, z których korzysta aplikacja.

Uwaga: kont usługi możesz używać w aplikacjach działających z domeny Google Workspace, ale nie są one użytkownikami Twojego konta Google Workspace i nie podlegają zasadom domeny skonfigurowanym przez administratorów Google Workspace. Na przykład zasady określone w konsoli administracyjnej Google Workspace ograniczające możliwość udostępniania dokumentów poza domenę przez użytkowników Google Workspace nie mają zastosowania do kont usługi.

Aby przekazać uprawnienia do całej domeny kontu usługi, superadministrator domeny Google Workspace musi wykonać te czynności:

1. W konsoli administracyjnej Google Workspace otwórz Menu główne > Zabezpieczenia > Dostęp i kontrola danych > Dostęp do interfejsów API.
2. W okienku Przekazywanie dostępu w całej domenie wybierz Zarządzaj przekazywaniem dostępu w całej domenie.
3. Kliknij Dodaj nową.
4. W polu Identyfikator klienta wpisz identyfikator klienta konta usługi. Identyfikator klienta konta usługi znajdziesz w Service accounts page.
5. W polu Zakresy OAuth (rozdzielone przecinkami) wpisz listę zakresów, do których aplikacja ma mieć dostęp. Jeśli na przykład Twoja aplikacja potrzebuje pełnego dostępu do Google Drive API i Google Calendar API, wpisz: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
6. Kliknij Autoryzuj.

Twoja aplikacja ma teraz uprawnienia do wywoływania interfejsów API jako użytkowników w Twojej domenie (w celu „podszycia się”). Przygotowując się do autoryzowanych wywołań interfejsu API, określasz użytkownika, którego chcesz użyć.

Uwaga: przyznawanie dostępu personifikacji zwykle trwa kilka minut od dodania identyfikatora klienta, ale w niektórych przypadkach rozpowszechnienie zmian na konta wszystkich użytkowników konta Google może potrwać do 24 godzin.

Przygotowywanie wywołania interfejsu API

Java

Po uzyskaniu adresu e-mail i klucza prywatnego klienta od API Consoleużyj biblioteki klienta interfejsów API Google dla języka Java, aby utworzyć obiekt GoogleCredential z danych logowania konta usługi i zakresów, do których aplikacja potrzebuje dostępu. Przykład:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Jeśli tworzysz aplikację w Google Cloud Platform, możesz użyć domyślnych danych logowania aplikacji, co może uprościć cały proces.

Przekazywanie uprawnień w całej domenie

Jeśli delegujesz dostęp do konta usługi w całej domenie i chcesz podszywać się pod konto użytkownika, określ adres e-mail konta użytkownika za pomocą metody createDelegated obiektu GoogleCredential. Na przykład:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("[e-mail]");

Wykorzystaj obiekt GoogleCredential, aby wywołać interfejsy API Google w swojej aplikacji.

Python

Po uzyskaniu od klienta API Consoleadresu e-mail i klucza prywatnego w Bibliotece klienta interfejsów API Google dla języka Python wykonaj te czynności:

1. Utwórz obiekt Credentials na podstawie danych logowania konta usługi oraz zakresów, do których aplikacja potrzebuje dostępu. Na przykład:

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   Jeśli tworzysz aplikację w Google Cloud Platform, możesz użyć domyślnych danych logowania aplikacji, co może uprościć cały proces.

2. Przekazywanie uprawnień w całej domenie

   Jeśli masz przekazany dostęp do konta usługi w całej domenie i chcesz się podszyć pod konto użytkownika, użyj metody with_subject istniejącego obiektu ServiceAccountCredentials. Przykład:

   delegated_credentials = credentials.with_subject('[e-mail]')

Obiekt danych logowania umożliwia wywoływanie interfejsów API Google w aplikacji.

HTTP/REST

Zalecenie: chociaż aplikacja może wykonywać te zadania przez bezpośrednią interakcję z systemem OAuth 2.0 przy użyciu protokołu HTTP, mechanika interakcji uwierzytelniania serwer-serwer wymaga, aby aplikacje tworzyły i kryptograficzne podpisy tokenów sieciowych JSON (JWT). Łatwo jest popełnić poważne błędy, które mogą mieć poważny wpływ na bezpieczeństwo aplikacji.

Dlatego zdecydowanie zalecamy korzystanie z bibliotek takich jak biblioteki klienta interfejsów API Google, które odciągają kryptografię od kodu aplikacji.

Gdy uzyskasz identyfikator klienta i klucz prywatny z API Console, Twoja aplikacja musi wykonać te czynności:

1. Utwórz token sieciowy JSON (JWT, wymowa, "jot"), który zawiera nagłówek, zestaw roszczeń i podpis.
2. Poproś o token dostępu z serwera autoryzacji Google OAuth 2.0.
3. Przetwórz odpowiedź JSON zwracaną przez serwer autoryzacji.

W poniższych sekcjach znajdziesz instrukcje, jak wykonać te czynności.

Jeśli odpowiedź zawiera token dostępu, możesz wykorzystać go, aby wywołać interfejs API Google. (Jeśli odpowiedź nie zawiera tokena dostępu, żądanie JWT i żądanie tokena mogą być nieprawidłowo utworzone lub konto usługi może nie mieć uprawnień dostępu do żądanych zakresów).

Gdy token dostępu wygaśnie, aplikacja wygeneruje kolejny token JWT, podpisze go i poprosi o kolejny token dostępu.

W pozostałej części tej sekcji znajdziesz szczegóły dotyczące tworzenia tokena JWT, podpisywania tokena JWT, tworzenia żądania tokena dostępu i obsługiwania odpowiedzi.

Tworzenie tokena JWT

Token JWT składa się z 3 części: nagłówka, zestawu roszczeń i podpisu. Zestaw nagłówków i roszczeń jest obiektami JSON. Te obiekty JSON są serializowane do bajtów UTF-8, a następnie kodowane przy użyciu kodowania Base64url. Zapewnia to większą odporność na zmiany kodowania spowodowane wielokrotnymi operacjami kodowania. Nagłówek, zestaw roszczeń i podpis są łączone kropką (.).

Token JWT wygląda tak:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

Podstawowy ciąg znaków podpisu:

{Base64url encoded header}.{Base64url encoded claim set}

Tworzenie nagłówka JWT

Nagłówek składa się z 2 pól, które wskazują algorytm podpisywania i format potwierdzenia. Oba pola są obowiązkowe, a każde z nich ma tylko jedną wartość. W miarę wprowadzania kolejnych algorytmów i formatów ten nagłówek będzie się odpowiednio zmieniać.

Konta usługi korzystają z algorytmu SHA-256 RSA i formatu tokena JWT. W związku z tym nagłówek JSON powinien wyglądać tak:

{"alg":"RS256","typ":"JWT"}

Oto ilustracja Base64url:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Tworzenie zestawu roszczeń JWT

Zestaw deklaracji JWT zawiera informacje o tokenie JWT, w tym o żądane uprawnienia (zakresy), cel tokena, wydawcę, czas wydania tokena i czas jego życia. Większość pól jest obowiązkowa. Podobnie jak nagłówek JWT, zestaw deklaracji tokena JWT jest obiektem JSON i jest używany do obliczania podpisu.

Wymagane roszczenia

Wymagane roszczenia w zbiorze deklaracji JWT znajdziesz poniżej. Mogą być wyświetlane w dowolnej kolejności w zestawie roszczeń.

Nazwa	Opis
iss	Adres e-mail konta usługi.
scope	Lista rozdzielonych spacjami uprawnień, których żąda aplikacja.
aud	Deskryptor docelowego celu potwierdzenia. Gdy żądasz tokena dostępu, ta wartość to zawsze https://oauth2.googleapis.com/token.
exp	Czas wygaśnięcia potwierdzenia podany jako sekundy od 00:00:00 UTC, 1 stycznia 1970 roku. Ta wartość może przypadać maksymalnie 1 godzinę po opublikowaniu.
iat	Godzina wysłania potwierdzenia określona jako sekundy od 00:00:00 UTC 1 stycznia 1970 roku.

Poniżej znajdziesz wymagane pola JSON w zbiorze deklaracji JWT:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Dodatkowe roszczenia

W niektórych przypadkach firmowych aplikacja może używać przekazywania dostępu w całej domenie do działania w imieniu konkretnego użytkownika w organizacji. Aby aplikacja mogła przyjmować te uprawnienia, użytkownik musi otrzymać odpowiednie uprawnienia. Zwykle zajmuje się tym superadministrator. Więcej informacji znajdziesz w artykule Kontrolowanie dostępu do interfejsów API za pomocą przekazywania dostępu w całej domenie.

Aby uzyskać token dostępu przyznający aplikacji dostęp do zasobu, podaj adres e-mail użytkownika w zgłoszeniu JWT ustawionym jako wartość pola sub.

Nazwa	Opis
sub	Adres e-mail użytkownika, którego aplikacja prosi o dostęp delegowany.

Jeśli aplikacja nie ma uprawnień do odgrywania roli użytkownika, odpowiedź na żądanie tokena dostępu, które zawiera pole sub, będzie stanowić błąd.

Poniżej znajdziesz przykładowy zestaw deklaracji JWT, który zawiera pole sub:

{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Kodowanie zestawu deklaracji JWT

Podobnie jak nagłówek JWT, zestaw deklaracji tokena JWT powinien być zserializowany za pomocą kodowania UTF-8 i Base64url-safe. Poniżej znajdziesz przykład reprezentacji zbioru JWT w formacie JSON:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Przetwarzanie podpisu

Podpis sieciowy JSON (JWS) to specyfikacja, która podaje mechanizm generowania podpisu JWT. Wpisany podpis składa się z tablicy bajtów tej treści:

{Base64url encoded header}.{Base64url encoded claim set}

Podczas przetwarzania podpisu należy użyć algorytmu podpisywania w nagłówku JWT. Jedynym algorytmem podpisywania obsługiwanym przez serwer autoryzacji Google OAuth 2.0 jest RSA z algorytmem szyfrowania SHA-256. Ta wartość jest wyrażana jako RS256 w polu alg w nagłówku JWT.

Podziękuj dane wejściowe za pomocą SHA256withRSA (znanej też jako RSASSA-PKCS1-V1_5-SIGN z funkcją skrótu SHA-256) kluczem prywatnym pobranym z klucza Google API Console. Wynikiem jest tablica bajtów.

Podpis musi być zakodowany w standardzie Base64url. Nagłówek, zestaw roszczeń i podpis są łączone kropką (.). Efekt to token JWT. Powinien mieć postać (dodana podziały wiersza, by zwiększyć czytelność):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Oto przykład tokena JWT przed kodowaniem Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"[e-mail]",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Poniżej znajduje się przykład tokena JWT, który został podpisany i jest gotowy do przeniesienia:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Wysyłanie żądania tokena dostępu

Po wygenerowaniu podpisanego tokena JWT aplikacja może go użyć, aby zażądać tokena dostępu. To żądanie tokena dostępu jest żądaniem HTTPS POST, a jego treść jest zakodowana na potrzeby adresu URL. Adres URL jest widoczny poniżej:

https://oauth2.googleapis.com/token

W żądaniu HTTPS POST wymagane są te parametry:

Nazwa	Opis
grant_type	Użyj tego ciągu znaków, zakodowanego w razie potrzeby: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	Token JWT, w tym podpis.

Poniżej nieprzetworzone żądanie HTTPS POST użyte w żądaniu tokena dostępu:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Poniżej znajduje się to samo żądanie za pomocą operatora curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Obsługa odpowiedzi

Jeśli formularz JWT i żądanie tokena dostępu są poprawnie sformatowane, a konto usługi ma uprawnienia do wykonania tej operacji, odpowiedź JSON z serwera autoryzacji będzie zawierać token dostępu. Oto przykładowa odpowiedź:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokenów dostępu można używać ponownie w okresie ważności określonym w wartości expires_in.

Wywołanie interfejsów API Google

Java

Aby wywołać obiekt API Google, użyj obiektu GoogleCredential, wykonując te czynności:

1. Utwórz obiekt usługi dla interfejsu API, który ma być wywoływany z użyciem obiektu GoogleCredential. Na przykład:

   SQLAdmin sqladmin =
       new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();

2. Przesyłaj żądania do usługi API za pomocą interfejsu udostępnionego przez obiekt usługi. Aby na przykład wyświetlić listę baz danych Cloud SQL w projekcie ekscytujące-example-123:

   SQLAdmin.Instances.List instances =
       sqladmin.instances().list("exciting-example-123").execute();

Python

Aby wywołać interfejs API Google, użyj autoryzowanego obiektu Credentials:

1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Aby utworzyć obiekt usługi, musisz wywołać funkcję build, podając nazwę i wersję interfejsu API oraz autoryzowany obiekt Credentials. Aby na przykład wywołać interfejs API Cloud SQL Administration w wersji 1beta3:

   import googleapiclient.discovery
   
   sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

2. Przesyłaj żądania do usługi API za pomocą interfejsu udostępnionego przez obiekt usługi. Aby na przykład wyświetlić listę baz danych Cloud SQL w projekcie ekscytujące-example-123:

   response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania interfejsu API Google w imieniu danego konta usługi lub konta użytkownika, jeśli przyznano zakresy dostępu wymagane przez interfejs API. Aby to zrobić, umieść token dostępu w żądaniu do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka Authorization nagłówka Bearer. W miarę możliwości zalecamy użycie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków biblioteki klienta możesz skonfigurować, aby wywoływać wywołania interfejsów API Google (na przykład podczas wywoływania interfejsu Drive Files API).

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w Play OAuth 2.0 Playground.

Przykłady użycia HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) z nagłówkiem HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz określić własny token dostępu:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika z wykorzystaniem parametru ciągu zapytania access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Przykłady zapytań z operatorem curl

Te polecenia możesz przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład z użyciem opcji nagłówka HTTP (co jest zalecane):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Możesz też skorzystać z parametru ciągu zapytania:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Po wygaśnięciu tokenów dostępu

Tokeny dostępu wydane przez serwer autoryzacji Google OAuth 2.0 wygasają po upływie czasu określonego przez wartość expires_in. Gdy token dostępu wygaśnie, aplikacja powinna wygenerować kolejny token JWT, podpisać go i poprosić o kolejny token dostępu.

Kody błędów tokena JWT

Pole error	Pole error_description	Znaczenie	Jak rozwiązać problem
unauthorized_client	Unauthorized client or scope in request.	Jeśli chcesz użyć przekazywania dostępu w całej domenie, to konto usługi nie jest autoryzowane w konsoli administracyjnej domeny użytkownika.	Sprawdź, czy konto usługi jest autoryzowane na stronie Przekazywanie dostępu w całej domenie w konsoli administracyjnej użytkownika w polu sub (pole). Zwykle trwa to kilka minut, ale może minąć do 24 godzin, zanim autoryzacja pojawi się na kontach wszystkich użytkowników na koncie Google.
unauthorized_client	Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.	Konto usługi zostało autoryzowane za pomocą adresu e-mail klienta, a nie identyfikatora klienta (w postaci liczb) w konsoli administracyjnej.	Na stronie Przekazywanie dostępu w całej domenie w konsoli administracyjnej usuń klienta i dodaj go ponownie przy użyciu identyfikatora liczbowego.
access_denied	(dowolna wartość)	Jeśli używasz przekazywania dostępu w całej domenie, co najmniej jeden żądany zakres nie jest autoryzowany w konsoli administracyjnej.	Upewnij się, że konto usługi jest autoryzowane na stronie Przekazywanie dostępu w całej domenie w konsoli administracyjnej użytkownika w roszczeniu (pole sub), i że zawiera ono wszystkie zakresy, których dotyczy prośba w scope deklaracji JWT. Zwykle trwa to kilka minut, ale może minąć do 24 godzin, zanim autoryzacja pojawi się na kontach wszystkich użytkowników na koncie Google.
invalid_grant	Not a valid email.	Użytkownik nie istnieje.	Sprawdź, czy adres e-mail w roszczeniu sub (pole) jest prawidłowy.
invalid_grant	Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.	Zazwyczaj oznacza to nieprawidłowy czas lokalny. Może się też zdarzyć, że wartość exp przekracza 65 minut w przypadku wartości iat lub gdy wartość exp jest mniejsza niż wartość iat.	Upewnij się, że zegar w systemie, w którym jest wywoływany token JWT, jest ustawiony prawidłowo. W razie potrzeby zsynchronizuj godzinę z serwerem NTP Google.
invalid_grant	Invalid JWT Signature.	Potwierdzenie tokena JWT jest podpisane kluczem prywatnym niepowiązanym z kontem usługi określonym przez e-mail klienta lub użyty klucz został usunięty, wyłączony lub wygasł. Potwierdzenie tokena JWT może być niepoprawnie zakodowane – musi być zakodowane w standardzie Base64, bez znaków nowego wiersza ani dopełnienia.	Zdekoduj zestaw deklaracji JWT i sprawdź, czy klucz, który podpisał potwierdzenie, jest powiązany z kontem usługi. Spróbuj użyć biblioteki OAuth udostępnionej przez Google, aby sprawdzić, czy token JWT jest generowany prawidłowo.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Nie zażądano żadnych zakresów (pusta lista zakresów) lub jeden z żądanych zakresów nie istnieje (tj. jest nieprawidłowy).	Sprawdź, czy pole scope (pole) tokena JWT jest wypełnione i porównaj zawarte w nim zakresy z udokumentowanymi zakresami interfejsów API, których chcesz używać, aby uniknąć błędów i literówek. Pamiętaj, że lista zakresów w roszczeniu scope musi być oddzielona spacjami, a nie przecinkami.
disabled_client	The OAuth client was disabled.	Klucz używany do podpisywania potwierdzenia tokena JWT jest wyłączony.	Przejdź do Google API Consolei w sekcji Uprawnienia &Administrator Konta usługi włącz konto usługi zawierające &"Key ID" używany do podpisywania potwierdzenia.

Załącznik: autoryzacja konta usługi bez protokołu OAuth

Niektóre interfejsy API Google umożliwiają wykonywanie autoryzowanych wywołań interfejsu API z użyciem podpisanego tokena JWT zamiast tokena okaziciela, a nie tokena dostępu OAuth 2.0. Jeśli to możliwe, przed wysłaniem wywołania interfejsu API nie musisz wysyłać żądania sieciowego do serwera autoryzacji Google.

Jeśli interfejs API, który chcesz wywołać, został opublikowany w repozytorium interfejsów API Google, możesz wykonywać autoryzowane wywołania API przy użyciu tokena JWT zamiast tokena dostępu. Aby to zrobić:

1. Utwórz konto usługi w sposób opisany powyżej. Pamiętaj, aby zachować plik JSON otrzymany po utworzeniu konta.
2. Używając dowolnej standardowej biblioteki JWT, takiej jak jwt.io, utwórz token JWT z nagłówkiem i ładunkiem, jak w poniższym przykładzie:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "[e-mail]",
     "sub": "[e-mail]",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• W polu kid w nagłówku podaj identyfikator klucza konta usługi. Tę wartość znajdziesz w polu private_key_id pliku JSON konta usługi.
• W polach iss i sub podaj adres e-mail konta usługi. Tę wartość znajdziesz w polu client_email pliku JSON konta usługi.
• W polu aud podaj punkt końcowy interfejsu API. Na przykład: https://SERVICE.googleapis.com/.
• W polu iat określ bieżący czas systemu Unix, a w polu exp podaj czas, który dokładnie przypada 3600 sekund na końcu tokena JWT.

Podpisz token JWT kluczem RSA-256 przy użyciu klucza prywatnego w pliku JSON konta usługi.

Przykład:

Java

Parametry google-api-java-client i java-jwt:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("[e-mail]")
        .withSubject("[e-mail]")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Za pomocą PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '[e-mail]',
           'sub': '[e-mail]',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. Wywołaj interfejs API, używając podpisanego tokena JWT jako tokena okaziciela:

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com