Korzystanie z protokołu OAuth 2.0 dla aplikacji serwer-serwer

Ważne: jeśli pracujesz z Google Cloud Platform, chyba że planujesz zbudować własną bibliotekę klienta, użyj kont usług i biblioteki klienta w chmurze zamiast przeprowadzać autoryzację jawnie, jak opisano w tym dokumencie. Aby uzyskać więcej informacji, zobacz Omówienie uwierzytelniania w dokumentacji Google Cloud Platform.

System Google OAuth 2.0 obsługuje interakcje między serwerami, na przykład między aplikacją internetową a usługą Google. W tym scenariuszu potrzebne jest konto usługi , czyli konto należące do aplikacji, a nie do indywidualnego użytkownika końcowego. Twoja aplikacja wywołuje interfejsy API Google w imieniu konta usługi, więc użytkownicy nie są bezpośrednio zaangażowani. Ten scenariusz jest czasami nazywany „dwuetapową autoryzacją OAuth” lub „2LO”. (Powiązany termin „trzyetapowa autoryzacja OAuth” odnosi się do scenariuszy, w których aplikacja wywołuje interfejsy API Google w imieniu użytkowników końcowych i w których czasami wymagana jest zgoda użytkownika).

Zwykle aplikacja korzysta z konta usługi, gdy aplikacja korzysta z interfejsów API Google do pracy z własnymi danymi, a nie danymi użytkownika. Na przykład aplikacja, która korzysta z Google Cloud Datastore do utrwalania danych, używałaby konta usługi do uwierzytelniania swoich wywołań interfejsu API Google Cloud Datastore.

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

W tym dokumencie opisano, jak aplikacja może zakończyć przepływ protokołu OAuth 2.0 między serwerami przy użyciu biblioteki klienta interfejsów API Google (zalecane) lub protokołu HTTP.

W przypadku niektórych interfejsów API Google możesz wykonywać autoryzowane wywołania interfejsu API przy użyciu podpisanego tokena JWT zamiast protokołu OAuth 2.0, co pozwala zaoszczędzić żądanie sieciowe. Zobacz Dodatek: Autoryzacja konta usługi bez OAuth .

Przegląd

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

Następnie aplikacja przygotowuje się do wykonywania autoryzowanych wywołań interfejsu API przy użyciu poświadczeń konta usługi w celu zażądania tokenu dostępu z serwera uwierzytelniania OAuth 2.0.

Wreszcie, Twoja aplikacja może używać tokenu dostępu do wywoływania interfejsów API Google.

Zalecenie: Twoja aplikacja może wykonywać te zadania, korzystając z biblioteki klienta interfejsów API Google dla Twojego języka lub bezpośrednio współdziałając z systemem OAuth 2.0 przy użyciu protokołu HTTP. Jednak mechanika interakcji między serwerami a uwierzytelnianiem wymaga aplikacji do tworzenia i kryptograficznego podpisywania tokenów sieciowych JSON (JWT) i łatwo jest popełnić poważne błędy, które mogą mieć poważny wpływ na bezpieczeństwo aplikacji.

Z tego powodu zdecydowanie zalecamy korzystanie z bibliotek, takich jak biblioteki klienckie interfejsów API Google, które odrywają kryptografię od kodu aplikacji.

Tworzenie konta usługi

Poświadczenia konta usługi obejmują wygenerowany adres e-mail, który jest unikalny i co najmniej jedną parę kluczy publiczny / prywatny. Jeśli delegowanie w całej domenie jest włączone, identyfikator klienta jest również częścią poświadczeń konta usługi.

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

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

Jeśli Twoja aplikacja nie działa w Google App Engine lub Google Compute Engine, musisz uzyskać te poświadczenia w Google API Console. Aby wygenerować poświadczenia konta usługi lub wyświetlić publiczne poświadczenia, które zostały już wygenerowane, wykonaj następujące czynności:

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 sekcji Szczegóły konta usługi wpisz nazwę, identyfikator i opis konta usługi, a następnie kliknij przycisk Utwórz .
5. Opcjonalnie: w sekcji Uprawnienia konta usługi wybierz role IAM, które chcesz przyznać kontu usługi, a następnie kliknij Kontynuuj .
6. Opcjonalnie: w obszarze Przyznaj użytkownikom dostęp do tego konta usługi dodaj użytkowników lub grupy, które mogą używać tego konta usługi i zarządzać nim.
7. Kliknij Utwórz klucz , a następnie 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ą.

Jeśli chcesz przyznać kontu usługi G Suite uprawnienia obejmujące całą domenę , kliknij adres e-mail utworzonego konta usługi, a następnie skopiuj wartość z pola Unikalny identyfikator .

Aby przekazać uprawnienia do konta usługi, użyj wartości skopiowanej jako identyfikator klienta.

Możesz wrócić do API Console w dowolnym momencie, aby wyświetlić adres e-mail, odciski palców klucza publicznego i inne informacje lub wygenerować dodatkowe pary kluczy publiczny / prywatny. Aby uzyskać więcej informacji na temat poświadczeń konta usługi w API Console, zobacz Konta usług w pliku pomocy API Console.

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

Uwaga: musisz bezpiecznie przechowywać klucze prywatne i zarządzać nimi zarówno w środowisku programistycznym, jak i produkcyjnym. Google nie przechowuje kopii Twoich kluczy prywatnych, tylko klucze publiczne. Aby uzyskać więcej informacji, zobacz sekcję Bezpieczna obsługa poświadczeń klienta w zasadach OAuth 2.0 .

Delegowanie uprawnień w całej domenie do konta usługi

Jeśli masz konto Google Workspace, administrator organizacji może autoryzować aplikację do uzyskiwania dostępu do danych użytkownika w imieniu użytkowników w domenie Google Workspace. Na przykład aplikacja korzystająca z interfejsu API Kalendarza Google do dodawania wydarzeń do kalendarzy wszystkich użytkowników w domenie Google Workspace użyłaby konta usługi w celu uzyskania dostępu do interfejsu API Kalendarza Google w imieniu użytkowników. Autoryzowanie konta usługi w celu uzyskania dostępu do danych w imieniu użytkowników w domenie jest czasami nazywane „delegowaniem uprawnień w całej domenie” do konta usługi.

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

Uwaga: chociaż możesz używać kont usług w aplikacjach uruchamianych z domeny Google Workspace, konta usług nie są członkami konta Google Workspace i nie podlegają zasadom domeny określonym przez administratorów Google Workspace. Na przykład zasada ustawiona w konsoli administracyjnej Google Workspace, która ogranicza możliwość udostępniania dokumentów poza domenę przez użytkowników końcowych Google Workspace, nie dotyczy kont usług.

Aby delegować uprawnienia w całej domenie do konta usługi, najpierw włącz delegowanie w całej domenie dla istniejącego konta usługi w Service accounts page lub utwórz nowe konto usługi z włączonym delegowaniem w całej domenie.

Następnie superadministrator domeny Google Workspace musi wykonać następujące czynności:

1. Z Twojego Google Workspace domeny konsoli administracyjnej , należy przejść do menu głównego > Bezpieczeństwo> Sterowanie API.
2. W okienku Delegowanie w całej domenie wybierz Zarządzaj delegowaniem w całej domenie .
3. Kliknij Dodaj nowy .
4. W polu Identyfikator klienta wprowadź identyfikator klienta konta usługi. Identyfikator klienta konta usługi można znaleźć w Service accounts page.
5. W polu Zakresy protokołu OAuth (rozdzielane przecinkami) wprowadź listę zakresów, do których aplikacja ma mieć dostęp. Na przykład, jeśli Twoja aplikacja wymaga pełnego dostępu w całej domenie do Google Drive API i Google Calendar API, wpisz: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth / kalendarz .
6. Kliknij Autoryzuj .

Twoja aplikacja ma teraz uprawnienia do wykonywania wywołań API jako użytkownicy w Twojej domenie (w celu „podszywania się” pod użytkowników). Przygotowując się do wykonywania autoryzowanych wywołań interfejsu API, określasz użytkownika, który ma się podszywać.

Uwaga: po dodaniu identyfikatora klienta przyznanie dostępu do podszywania się zajmuje zwykle kilka minut, ale w niektórych przypadkach rozpowszechnienie go do wszystkich użytkowników konta Google może zająć do 24 godzin.

Przygotowanie do autoryzowanego wywołania API

Jawa

Po uzyskaniu adresu e-mail klienta i klucza prywatnego z API Console, użyj biblioteki klienta interfejsów API Google dla języka Java, aby utworzyć obiekt GoogleCredential na podstawie danych logowania konta usługi i zakresów, do których aplikacja potrzebuje dostępu. Na 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 zamiast tego użyć domyślnych danych logowania aplikacji , co może uprościć proces.

Przekaż uprawnienia w całej domenie

Jeśli delegowany całej domeny dostęp do konta usługi i chcesz, aby podszyć się pod konto użytkownika należy podać adres e-mail konta użytkownika z createDelegated sposobie GoogleCredential obiektu. Na przykład:

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

Użyj obiektu GoogleCredential aby wywołać interfejsy API Google w swojej aplikacji.

Pyton

Po uzyskaniu adresu e-mail klienta i klucza prywatnego z API Console użyj biblioteki klienta interfejsów API Google dla języka Python, aby wykonać następujące czynności:

1. Utwórz obiekt Credentials podstawie Credentials konta usługi i 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 zamiast tego użyć domyślnych danych logowania aplikacji , co może uprościć proces.

2. Przekaż uprawnienia w całej domenie

   Jeśli masz delegowany dostęp do konta usługi w całej domenie i chcesz personifikować konto użytkownika, użyj metody with_subject istniejącego obiektu ServiceAccountCredentials . Na przykład:

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

Użyj obiektu Credentials, aby wywołać interfejsy API Google w swojej aplikacji.

HTTP / REST

Zalecenie: chociaż aplikacja może wykonywać te zadania, bezpośrednio wchodząc w interakcję z systemem OAuth 2.0 przy użyciu protokołu HTTP, mechanika interakcji uwierzytelniania serwer-serwer wymaga, aby aplikacje tworzyły i podpisywały kryptograficznie tokeny JSON Web Tokens (JWT). błędy, które mogą mieć poważny wpływ na bezpieczeństwo aplikacji.

Z tego powodu zdecydowanie zalecamy korzystanie z bibliotek, takich jak biblioteki klienckie interfejsów API Google, które odrywają kryptografię od kodu aplikacji.

Po uzyskaniu identyfikatora klienta i klucza prywatnego z API Console aplikacja musi wykonać następujące czynności:

1. Utwórz JSON Web Token (JWT, wymawiane „jot”), który zawiera nagłówek, zestaw oświadczeń i podpis.
2. Poproś o token dostępu z serwera autoryzacji Google OAuth 2.0.
3. Obsługuj odpowiedź JSON zwracaną przez serwer autoryzacji.

W poniższych sekcjach opisano, jak wykonać te kroki.

Jeśli odpowiedź zawiera token dostępu, możesz go użyć do wywołania interfejsu API Google . (Jeśli odpowiedź nie zawiera tokenu dostępu, token JWT i żądanie tokenu mogą nie być poprawnie sformułowane lub konto usługi może nie mieć uprawnień dostępu do żądanych zakresów).

Po wygaśnięciu tokenu dostępu aplikacja generuje kolejny token dostępu, podpisuje go i żąda kolejnego tokenu dostępu.

W pozostałej części tej sekcji opisano specyfikę tworzenia tokena JWT, podpisywania tokena JWT, tworzenia żądania tokenu dostępu i obsługi odpowiedzi.

Tworzenie JWT

JWT składa się z trzech części: nagłówka, zestawu oświadczeń i podpisu. Nagłówek i zestaw oświadczeń to obiekty JSON. Te obiekty JSON są serializowane do bajtów UTF-8, a następnie kodowane przy użyciu kodowania Base64url. To kodowanie zapewnia odporność na zmiany kodowania spowodowane powtarzającymi się operacjami kodowania. Nagłówek, zestaw oświadczeń i podpis są łączone ze znakiem kropki ( . ).

JWT składa się z następujących elementów:

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

Podstawowy ciąg podpisu jest następujący:

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

Tworzenie nagłówka JWT

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

Konta usług opierają się na algorytmie RSA SHA-256 i formacie tokena JWT. W rezultacie reprezentacja nagłówka w formacie JSON jest następująca:

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

Reprezentacja Base64url jest następująca:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Tworzenie zbioru roszczeń JWT

Zestaw oświadczeń JWT zawiera informacje o tokenie JWT, w tym o żądanych uprawnieniach (zakresach), celu tokenu, wystawcy, godzinie wystawienia tokenu i okresie istnienia tokenu. Większość pól jest obowiązkowa. Podobnie jak nagłówek JWT, zestaw oświadczeń JWT jest obiektem JSON i jest używany do obliczania podpisu.

Wymagane roszczenia

Wymagane roszczenia w zestawie roszczeń JWT przedstawiono poniżej. Mogą pojawiać się w dowolnej kolejności w zestawie roszczeń.

Nazwa	Opis
iss	Adres e-mail konta usługi.
scope	Rozdzielana spacjami lista uprawnień, których żąda aplikacja.
aud	Deskryptor zamierzonego celu stwierdzenia. Przy żądaniu tokena dostępu ta wartość to zawsze https://oauth2.googleapis.com/token .
exp	Czas wygaśnięcia potwierdzenia określony w sekundach od 00:00:00 czasu UTC 1 stycznia 1970 r. Ta wartość ma maksymalnie 1 godzinę po wydaniu.
iat	Czas wystawienia potwierdzenia, określony w sekundach od 00:00:00 czasu UTC, 1 stycznia 1970.

Poniżej przedstawiono reprezentację wymaganych pól w zestawie oświadczeń JWT w formacie JSON:

{
  "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 aplikacja może używać delegowania w całej domenie do działania w imieniu określonego użytkownika w organizacji. Uprawnienie do wykonywania tego typu podszywania się musi zostać przyznane, zanim aplikacja będzie mogła podszyć się pod użytkownika. Zwykle jest to obsługiwane przez superadministratora. Aby uzyskać więcej informacji, zobacz Kontrolowanie dostępu do interfejsu API za pomocą delegowania w całej domenie .

Aby uzyskać token dostępu, który przyznaje aplikacji delegowany dostęp do zasobu, podaj adres e-mail użytkownika w oświadczeniu JWT ustawionym jako wartość pola sub .

Nazwa	Opis
sub	Adres e-mail użytkownika, dla którego aplikacja żąda delegowanego dostępu.

Jeśli aplikacja nie ma uprawnień do personifikacji użytkownika, odpowiedzią na żądanie tokenu dostępu, które zawiera pole sub będzie błąd .

Przykład zestawu oświadczeń JWT, który zawiera pole sub pokazano poniżej:

{
  "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 oświadczeń JWT

Podobnie jak nagłówek JWT, zestaw oświadczeń JWT powinien być serializowany do UTF-8 i zakodowany w standardzie Base64url. Poniżej znajduje się przykład reprezentacji JSON zestawu oświadczeń JWT:

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

Obliczanie podpisu

JSON Web Signature (JWS) to specyfikacja, która kieruje mechanizmem generowania podpisu dla tokena JWT. Dane wejściowe dla podpisu to tablica bajtów o następującej treści:

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

Podczas obliczania 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 wykorzystujący algorytm mieszający SHA-256. Jest to wyrażone jako RS256 w polu alg w nagłówku JWT.

Podpisz reprezentację wejścia UTF-8 za pomocą SHA256withRSA (znanego również jako RSASSA-PKCS1-V1_5-SIGN z funkcją skrótu SHA-256) za pomocą klucza prywatnego uzyskanego z Google API Console. Dane wyjściowe będą tablicą bajtów.

Podpis musi być następnie zakodowany w formacie Base64url. Nagłówek, zestaw oświadczeń i podpis są łączone ze znakiem kropki ( . ). Rezultatem jest JWT. Powinien wyglądać następująco (dla przejrzystości dodano podziały wierszy):

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

Poniżej znajduje się 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 JWT, który został podpisany i jest gotowy do transmisji:

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

Żądanie tokena dostępu

Po wygenerowaniu podpisanego tokena JWT aplikacja może użyć go do zażądania tokena dostępu. To żądanie tokenu dostępu jest żądaniem HTTPS POST , a treść jest zakodowana w postaci adresu URL. Adres URL jest pokazany poniżej:

https://oauth2.googleapis.com/token

W POST HTTPS POST wymagane są następujące parametry:

Nazwa	Opis
grant_type	Użyj następującego ciągu, w razie potrzeby zakodowanego w adresie URL: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	JWT wraz z podpisem.

Poniżej znajduje się surowy zrzut POST HTTPS POST używanego w żądaniu tokenu 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ę ta sama prośba, używając 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 token JWT i żądanie tokena dostępu są prawidłowo utworzone, a konto usługi ma uprawnienia do wykonania operacji, wówczas odpowiedź JSON z serwera autoryzacji 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
}

Tokeny dostępu można ponownie wykorzystać w okresie czasu określonym przez wartość expires_in .

Wywołanie interfejsów API Google

Jawa

Użyj obiektu GoogleCredential aby wywołać interfejsy API Google, wykonując następujące kroki:

1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać za pomocą obiektu GoogleCredential . Na przykład:

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

2. Wysyłaj żądania do usługi API, korzystając z interfejsu udostępnionego przez obiekt usługi . Na przykład, aby wyświetlić listę wystąpień baz danych Cloud SQL w projekcie ekscytujący przykład-123:

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

Pyton

Użyj autoryzowanego obiektu Credentials aby wywołać interfejsy API Google, wykonując następujące kroki:

1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Obiekt usługi tworzy się, wywołując funkcję build z nazwą i wersją interfejsu API oraz autoryzowanym obiektem Credentials . Na przykład, aby wywołać wersję 1beta3 interfejsu Cloud SQL Administration API:

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

2. Wysyłaj żądania do usługi API, korzystając z interfejsu udostępnionego przez obiekt usługi . Na przykład, aby wyświetlić instancje baz danych Cloud SQL w projekcie ekscytujący-przykład-123:

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

HTTP / REST

Gdy aplikacja uzyska token dostępu, możesz go używać do wykonywania wywołań interfejsu API Google w imieniu danego konta usługi lub konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez API. Aby to zrobić, należy dołączyć token dostępu w żądaniu API poprzez włączenie OSOBĄ access_token parametr zapytania lub Authorization HTTP nagłówek Bearer wartości. Jeśli to możliwe, preferowany jest nagłówek HTTP, ponieważ ciągi zapytań są zwykle widoczne w dziennikach serwera. W większości przypadków możesz użyć biblioteki klienckiej, aby skonfigurować 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 OAuth 2.0 Playground .

Przykłady HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) przy użyciu nagłówka HTTP Authorization: Bearer może wyglądać następująco. 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 przy użyciu parametru ciągu zapytania access_token :

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

curl przykłady

Możesz przetestować te polecenia za pomocą aplikacji wiersza poleceń curl . Oto przykład wykorzystujący opcję nagłówka HTTP (preferowana):

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

Lub alternatywnie opcja parametru ciągu zapytania:

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

Kiedy wygasają tokeny dostępu

Tokeny dostępu wydane przez serwer autoryzacji Google OAuth 2.0 wygasają po czasie określonym przez wartość expires_in . Po wygaśnięciu tokenu dostępu aplikacja powinna wygenerować kolejny token JWT, podpisać go i zażądać kolejnego tokenu dostępu.

Kody błędów JWT

pole error	pole error_description	Znaczenie	Jak rozwiązać
unauthorized_client	Unauthorized client or scope in request.	Jeśli próbujesz użyć przekazywania dostępu do całej domeny, konto usługi nie jest autoryzowane w konsoli administracyjnej domeny użytkownika.	Upewnij się, że konto usługi jest autoryzowane na stronie Przekazywanie uprawnień dla całej domeny w konsoli administracyjnej użytkownika w oświadczeniu sub (pole). Chociaż zwykle zajmuje to kilka minut, rozpowszechnienie autoryzacji wśród wszystkich użytkowników na Twoim koncie Google może zająć do 24 godzin.
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 przy użyciu adresu e-mail klienta, a nie identyfikatora klienta (numerycznego) w konsoli administracyjnej.	Na stronie Delegowanie dla całej domeny w konsoli administracyjnej usuń klienta i dodaj go ponownie, podając numeryczny identyfikator.
access_denied	(dowolna wartość)	Jeśli korzystasz z 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 Delegowanie dla całej domeny w konsoli administracyjnej dla użytkownika w roszczeniu sub (polu) i że zawiera wszystkie żądane zakresy w roszczeniu scope Twojego tokena JWT. Chociaż zwykle zajmuje to kilka minut, rozpowszechnienie autoryzacji wśród wszystkich użytkowników na Twoim koncie Google może zająć do 24 godzin.
invalid_grant	Not a valid email.	Użytkownik nie istnieje.	Sprawdź, czy adres e-mail w sub roszczenia (pole) jest prawidłowa.
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.	Zwykle oznacza to, że lokalny czas systemowy jest nieprawidłowy. Może się to również zdarzyć, jeśli wartość exp jest późniejsza niż 65 minut od wartości iat lub wartość exp jest niższa niż wartość iat .	Upewnij się, że zegar w systemie, w którym generowany jest token JWT, jest poprawny. W razie potrzeby zsynchronizuj swój czas z Google NTP .
invalid_grant	Invalid JWT Signature.	Asercja JWT jest podpisana kluczem prywatnym, który nie jest powiązany z kontem usługi zidentyfikowanym w wiadomości e-mail klienta. Alternatywnie, asercja JWT może być niepoprawnie zakodowana - musi być zakodowana w Base64, bez znaków nowej linii lub dopełnienia znaków równości.	Zdekoduj zestaw oświadczeń tokena JWT i sprawdź, czy klucz, który podpisał potwierdzenie, jest powiązany z kontem usługi. Spróbuj użyć biblioteki OAuth dostarczonej przez Google, aby upewnić się, że token JWT został wygenerowany poprawnie.
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).	Upewnij się, że roszczenie scope (pole) tokena JWT jest wypełnione i porównaj zakresy, które zawiera, z udokumentowanymi zakresami interfejsów API, których chcesz użyć, aby upewnić się, że nie ma błędów ani literówek. Zauważ, ż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 asercji JWT jest wyłączony.	Przejdź do Google API Console iw sekcji IAM & Admin> Service Accounts włącz konto usługi, które zawiera „Key ID” używany do podpisania potwierdzenia.

Dodatek: Autoryzacja konta usługi bez OAuth

W przypadku niektórych interfejsów API Google można wykonywać autoryzowane wywołania interfejsu API przy użyciu podpisanego tokena JWT bezpośrednio jako tokenu okaziciela zamiast tokena dostępu OAuth 2.0. Jeśli jest to możliwe, możesz uniknąć wysyłania żądania sieciowego do serwera autoryzacji Google przed wywołaniem interfejsu API.

Jeśli interfejs API, który chcesz wywołać, ma definicję usługi opublikowaną w repozytorium Google APIs na GitHubie , możesz wykonywać autoryzowane wywołania interfejsu API za pomocą tokena JWT zamiast tokena dostępu. Aby to zrobić:

1. Utwórz konto usługi zgodnie z powyższym opisem. Pamiętaj, aby zachować plik JSON, który otrzymałeś podczas tworzenia konta.
2. Korzystając z dowolnej standardowej biblioteki JWT, takiej jak ta znaleziona w 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 określ identyfikator klucza prywatnego konta usługi. Tę wartość można znaleźć w polu private_key_id w pliku JSON konta usługi.
• W polach iss i sub określ adres e-mail konta usługi. Tę wartość można znaleźć w polu client_email w pliku JSON konta usługi.
• W polu aud określ 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 dokładnie 3600 sekund później, kiedy token JWT wygaśnie.

Podpisz JWT za pomocą RSA-256, używając klucza prywatnego znajdującego się w pliku JSON konta usługi.

Na przykład:

Jawa

Korzystanie z 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 ...

Pyton

Korzystanie z 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 tokenu okaziciela:

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