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

Więcej informacji znajdziesz w artykule Omówienie uwierzytelniania w dokumentacji Google Cloud Platform.

System Google OAuth 2.0 umożliwia interakcję między serwerami, na przykład między aplikacją internetową a usługą Google. W tym scenariuszu potrzebujesz konta usługi, które należy do Twojej aplikacji, a nie do określonego użytkownika. 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 czasem nazywany „dwukierunkową 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, w przypadku których 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 Google Cloud Datastore API.

Administratorzy domen Google Workspace mogą też przyznawać kontu usługi uprawnienia obejmujące całą domenę, aby uzyskiwać dostęp do danych użytkowników w imieniu użytkowników w domenie.

Ten dokument opisuje, w jaki sposób aplikacja może zakończyć proces OAuth 2.0 między serwerami, korzystając z biblioteki klienta interfejsów API Google (zalecane) lub HTTP.

W przypadku niektórych interfejsów API Google możesz tworzyć autoryzowane wywołania interfejsu API przy użyciu podpisanego tokena JWT, a nie przez OAuth 2.0, co pozwala zapisywać żądania sieciowe. Zobacz Dodatek: 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 aplikacja przygotowuje się do autoryzowania wywołań interfejsu API przy użyciu danych logowania konta usługi w celu zażądania tokena dostępu z serwera uwierzytelniania OAuth 2.0.

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

Zalecenie: te zadania możesz wykonać przy użyciu biblioteki klienta interfejsów Google API w swoim języku lub bezpośredniej interakcji z systemem OAuth 2.0 za pomocą HTTP. Mechanika interakcji uwierzytelniania serwer-serwer wymaga jednak, aby aplikacje tworzyły i kryptograficznie podpisywały tokeny sieciowe JSON (JWT). Poważne błędy mogą mieć duży wpływ na bezpieczeństwo aplikacji.

Z tego powodu gorąco zachęcamy do korzystania z bibliotek, takich jak biblioteki klienta interfejsów API Google, które wyodrębniają kryptografię od kodu aplikacji.

Tworzę konto usługi

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

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

Jeśli Twoja aplikacja działa w Google Compute Engine, podczas tworzenia projektu konto usługi jest też konfigurowane automatycznie, ale przy tworzeniu 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 już zostały 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 obszarze Szczegóły konta usługi wpisz nazwę, identyfikator i opis konta usługi, a następnie kliknij Utwórz i kontynuuj .
5. Opcjonalnie: w obszarze Przyznaj temu kontu usługi dostęp do projektu wybierz role uprawnień, które chcesz przyznać kontu usługi.
6. Kliknij Kontynuuj .
7. Opcjonalnie: w obszarze Przyznaj użytkownikom dostęp do tego konta usługi dodaj użytkowników lub grupy, które mogą używać konta usługi i zarządzać nim.
8. Kliknij Gotowe .

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

1. Kliknij adres e-mail utworzonego konta usługi.
2. Kliknij kartę Klucze .
3. Z listy rozwijanej Dodaj klucz wybierz opcję Utwórz nowy klucz .
4. Kliknij Utwórz .

Twoja nowa para kluczy publiczny/prywatny jest generowana i pobierana 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 lub wygenerować dodatkowe pary kluczy publiczny/prywatny. Więcej informacji o danych logowania do konta usługi w API Consoleznajdziesz w artykule 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 wymaga 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 Twoich kluczy prywatnych; tylko Twoje klucze publiczne. Więcej informacji znajdziesz w sekcji Obsługa bezpiecznych danych logowania klienta w zasadach OAuth 2.0.

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

Jeśli masz konto Google Workspace, administrator organizacji może zezwolić aplikacji na dostęp do danych użytkowników w imieniu użytkowników w domenie 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 w imieniu użytkowników. Autoryzacja konta usługi do uzyskiwania dostępu do danych w imieniu użytkowników w domenie jest czasem określana jako „przekazywanie uprawnień w całej domenie” do konta usługi.

Uwaga: gdy zainstalujesz aplikację w swojej domenie za pomocą Google Workspace Marketplace, wymagane uprawnienia zostaną przyznane jej automatycznie podczas instalacji. Nie musisz ręcznie autoryzować kont usługi używanych przez aplikację.

Uwaga: kont usługi można używać w aplikacjach działających w domenie Google Workspace, ale nie należą one do konta Google Workspace i nie podlegają zasadom domeny określonym przez administratorów Google Workspace. Na przykład zasady ustawione w konsoli administracyjnej Google Workspace, które ograniczają możliwość udostępniania dokumentów poza domenę przez użytkowników Google Workspace, nie mają zastosowania do kont usługi.

Aby delegować dostęp do konta usługi w całej domenie, superadministrator domeny Google Workspace musi wykonać te czynności:

1. W konsoli administracyjnej domeny Google Workspace kliknij Menu główne > Zabezpieczenia > Kontrola dostępu i dane > Dostęp do interfejsów API.
2. W panelu Przekazywanie dostępu w całej domenie wybierz Zarządzaj przekazywaniem dostępu w całej domenie.
3. Kliknij Dodaj nowy.
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 aplikacja potrzebuje pełnego dostępu do interfejsów 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 interfejsu API jako użytkowników w Twojej domenie (czyli do „podszywania się”). Przygotowując się do wykonywania autoryzowanych wywołań interfejsu API, określasz użytkownika, pod którego chcesz się podszywać.

Uwaga: przyznanie tożsamości dostępu zajmuje zwykle kilka minut po dodaniu identyfikatora klienta, ale w niektórych przypadkach może minąć do 24 godzin, zanim zmiany będą widoczne na kontach wszystkich użytkowników konta Google.

Przygotowywanie do przeprowadzenia autoryzowanego wywołania interfejsu API

Java

Gdy pozyskasz adres e-mail klienta i klucz prywatny z API Console, uż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. 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 użyć domyślnych danych logowania, co może uprościć ten 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 metodą createDelegated obiektu GoogleCredential. Na przykład:

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

Używaj obiektu GoogleCredential do wywoływania interfejsów API Google w swojej aplikacji.

Python

Gdy pozyskasz adres e-mail klienta i klucz prywatny z API Console, skorzystaj z biblioteki klienta interfejsów API Google dla Pythona, aby wykonać te czynności:

1. Utwórz obiekt Credentials z danych logowania 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 użyć domyślnych danych logowania, co może uprościć ten proces.

2. 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, użyj metody with_subject istniejącego obiektu ServiceAccountCredentials. Na przykład:

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

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

HTTP/REST

Zalecenie: chociaż aplikacja może wykonywać te zadania przez bezpośrednią interakcję z systemem OAuth 2.0 przez HTTP, mechanizm interakcji uwierzytelniania serwer-serwer wymaga, aby aplikacje tworzyły i kryptograficznie podpisywały tokeny sieciowe JSON (JWT). Pamiętaj, że łatwo jest dokonać poważnych błędów, które mogą mieć poważny wpływ na bezpieczeństwo aplikacji.

Z tego powodu gorąco zachęcamy do korzystania z bibliotek, takich jak biblioteki klienta Google API, które wyodrębniają kryptografię od kodu aplikacji.

Gdy uzyskasz identyfikator klienta i klucz prywatny z API Console, 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.

Poniżej znajdziesz instrukcje wykonywania tych czynności.

Jeśli odpowiedź zawiera token dostępu, możesz go użyć, by wywołać interfejs API Google. (Jeśli odpowiedź nie zawiera tokena dostępu, żądanie tokena JWT i tokenu 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 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. Kodowanie zapewnia odporność na zmiany w kodowaniu spowodowane powtarzanymi operacjami kodowania. Nagłówek, zestaw roszczeń i podpis są połączone znakiem kropki (.).

Token JWT wygląda tak:

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

Podstawowy ciąg podpisu wygląda tak:

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

Tworzenie nagłówka JWT

Nagłówek składa się z 2 pól wskazujących 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 używają algorytmu RSA SHA-256 i formatu tokena JWT. W związku z tym nagłówek JSON wygląda tak:

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

Reprezentacja pola Base64url wygląda tak:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Tworzenie zbioru deklaracji tokena JWT

Zestaw deklaracji JWT zawiera informacje o tokenie JWT, w tym o żądanych uprawnieniach (zakresach), miejscu docelowym tokena, wydawcy, czasie wydania tokena i czasie jego życia. Większość pól jest obowiązkowa. Podobnie jak nagłówek JWT, zestaw deklaracji JWT jest obiektem JSON i jest używany przy obliczaniu podpisu.

Wymagane roszczenia

Poniżej znajdziesz listę wymaganych deklaracji w zbiorze JWT. Mogą one pojawiać się w dowolnej kolejności w zbiorze roszczeń.

Nazwa	Opis
iss	Adres e-mail konta usługi.
scope	Lista rozdzielonych spacjami uprawnień, o które prosi aplikacja.
aud	Deskryptor docelowego komunikatu. Gdy żądasz tokena dostępu, ta wartość to zawsze https://oauth2.googleapis.com/token.
exp	Czas wygaśnięcia potwierdzenia podany w sekundach od 00:00:00 czasu UTC, 1 stycznia 1970 roku. Wartość ta może przypadać nie wcześniej niż godzinę po wydaniu.
iat	Czas wysłania potwierdzenia podany w sekundach od 00:00:00 czasu UTC, 1 stycznia 1970 roku.

Plik JSON przedstawiający wymagane pola 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 w imieniu określonego użytkownika w organizacji. Aby aplikacja mogła przyjąć taką tożsamość, użytkownik musi otrzymać odpowiednie uprawnienia. Zazwyczaj musi to zrobić superadministrator. Więcej informacji znajdziesz w artykule Kontrola nad dostępem przez interfejs API przy użyciu 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ść w polu sub.

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

Jeśli aplikacja nie ma uprawnień do odgrywania roli użytkownika, odpowiedzią na żądanie tokena dostępu zawierające pole sub będzie 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 zbioru deklaracji tokena JWT

Podobnie jak w przypadku nagłówka JWT zestaw deklaracji JWT powinien być zserializowany za pomocą kodowania UTF-8 i Base64url-safe-safe. Poniżej znajdziesz przykładowy kod JSON reprezentujący zestaw deklaracji JWT:

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

Obliczanie podpisu

JWS to specyfikacja, która podaje mechanizm generowania podpisu JWT. Dane wejściowe podpisu to bajtowa bajt tej treści:

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

Podczas obliczania podpisu należy użyć algorytmu podpisywania w nagłówku JWT. Jedyny algorytm podpisywania obsługiwany przez serwer autoryzacji Google OAuth 2.0 to RSA z algorytmem szyfrowania SHA-256. Wynik jest wyrażony jako RS256 w polu alg w nagłówku JWT.

Podpisz dane wejściowe UTF-8 za pomocą algorytmu SHA256withRSA (nazywanego też RSASSA-PKCS1-V1_5-SIGN z funkcją skrótu SHA-256) kluczem prywatnym uzyskanym z Google API Console. Wynik to tablica bajtów.

Podpis musi być zakodowany w standardzie Base64url. Nagłówek, zestaw roszczeń i podpis są połączone znakiem kropki (.). Efektem jest token JWT. Prawidłowo:

{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 znajdziesz przykładowy token JWT, który został podpisany i jest gotowy do przesyłania:

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 to żądanie HTTPS POST, a 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	W razie potrzeby użyj tego ciągu znaków: z kodowaniem adresu URL: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	Token JWT, w tym podpis.

Poniżej znajdziesz nieprzetworzony zrzut żądania HTTPS POST używanego 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 widać to samo żądanie z użyciem atrybutu 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 żądanie JWT i token dostępu są poprawnie utworzone, a konto usługi ma uprawnienia do wykonania tej operacji, odpowiedź JSON z serwera autoryzacji zawiera token dostępu. 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ływanie interfejsów API Google

Java

Wykorzystaj obiekt GoogleCredential do wywoływania interfejsów API Google, wykonując te czynności:

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

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

2. Wysyłanie żądań 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 eksplorowanym projekcie example-123:

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

Python

Użyj autoryzowanego obiektu Credentials do wywoływania interfejsów API Google, wykonując te czynności:

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

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

2. Wysyłanie żądań 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 eksplorowanym projekcie 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 Google API w imieniu danego konta usługi lub konta użytkownika, jeśli zakresy dostępu wymagane przez ten interfejs API zostały przyznane. W tym celu umieść w żądaniu żądanie do interfejsu API token dostępu, podając w zapytaniu parametr access_token lub wartość nagłówka HTTP Authorization Bearer. W miarę możliwości zalecamy używanie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków możesz użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (np. podczas wywoływania interfejsu Drive Files API).

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w Play 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ć 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 uwierzytelnionego użytkownika używającego 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 użycia opcji nagłówka HTTP (zalecane):

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

Możesz też użyć opcji 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 wystawione przez serwer autoryzacji Google OAuth 2.0 wygasa po upływie czasu trwania podanego w wartości expires_in. Gdy token dostępu wygaśnie, aplikacja powinna wygenerować nowy 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 próbujesz użyć przekazywania dostępu w całej domenie, 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 dla użytkownika w polu (sub). Chociaż zazwyczaj zajmuje to kilka minut, rozpowszechnienie wszystkich użytkowników na koncie Google może potrwać 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 (liczby) w konsoli administracyjnej.	Na stronie Przekazywanie dostępu w całej domenie 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 1 z żądanych zakresów nie jest autoryzowany w konsoli administracyjnej.	Sprawdź, czy konto usługi jest autoryzowane na stronie Przekazywanie dostępu w całej domenie w konsoli administracyjnej dla użytkownika w polu sub (pole) i czy zawiera wszystkie zakresy, których potrzebujesz w deklaracji scope tokena JWT. Chociaż zazwyczaj zajmuje to kilka minut, rozpowszechnienie wszystkich użytkowników na koncie Google może potrwać do 24 godzin.
admin_policy_enforced	(dowolna wartość)	Z powodu zasad określonych przez administratora Google Workspace konto Google nie może autoryzować co najmniej 1 zakresu, o który prosisz.	Zapoznaj się z artykułem pomocy dla administratorów Google Workspace w artykule Kontrola nad tym, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace. Znajdziesz w nim więcej informacji o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczonym dostępem, dopóki dostęp do identyfikatora klienta OAuth nie zostanie jawnie przyznany.
invalid_client	(dowolna wartość)	Klient OAuth lub token JWT jest nieprawidłowy lub nieprawidłowo skonfigurowany. Więcej informacji znajdziesz w opisie błędu.	Sprawdź, czy token JWT jest prawidłowy i zawiera prawidłowe roszczenia. Sprawdź, czy klient i konto usługi OAuth są prawidłowo skonfigurowane i czy używasz prawidłowego adresu e-mail. Sprawdź, czy token JWT jest poprawny i został wydany dla identyfikatora klienta w żądaniu.
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.	Zwykle oznacza to, że czas lokalny w systemie jest nieprawidłowy. Może się tak również zdarzyć, jeśli wartość exp jest oddalona o ponad 65 minut od wartości iat lub wartość exp jest niższa niż iat.	Upewnij się, że zegar w systemie, w którym generowany jest token JWT, jest prawidłowy. W razie potrzeby zsynchronizuj czas z Google NTP.
invalid_grant	Invalid JWT Signature.	Potwierdzenie tokena JWT jest podpisane kluczem prywatnym niepowiązanym z kontem usługi wskazanym w adresie e-mail klienta lub użyty klucz został usunięty, wyłączony lub wygasł. Potwierdzenie JWT może też być nieprawidłowo zakodowane – musi być zakodowane w Base64, bez znaków nowego wiersza ani znaków równości.	Zdekoduj zestaw tokena JWT i sprawdź, czy klucz, który podpisał potwierdzenie, jest powiązany z kontem usługi. Użyj biblioteki OAuth udostępnionej przez Google, aby upewnić się, że token JWT jest generowany prawidłowo.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Nie poproszono o żadne zakresy (pusta lista zakresów) lub jeden z żądanych zakresów nie istnieje (tzn. jest nieprawidłowy).	Sprawdź, czy pole scope (pole) tokena JWT jest wypełnione i porównaj zakresy, które zawiera udokumentowane zakresy 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.	Otwórz Google API Consolei w sekcji Administracja > Konta usługi włącz konto usługi zawierające „Identyfikator klucza”, który służy do podpisywania potwierdzenia.
org_internal	This client is restricted to users within its organization.	Identyfikator klienta OAuth w żądaniu jest częścią projektu ograniczającego dostęp do kont Google w określonej organizacji Google Cloud.	Do uwierzytelniania użyj konta usługi organizacji. Potwierdź konfigurację typu użytkownika aplikacji OAuth.

Dodatek: autoryzacja konta usługi bez protokołu OAuth

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

Jeśli interfejs API, który chcesz wywołać, został opublikowany w repozytorium GitHub Google API, możesz utworzyć autoryzowane wywołania interfejsu API, używając 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 podczas tworzenia konta.
2. Korzystając ze standardowej biblioteki JWT, takiej jak ta w jwt.io, utwórz token JWT z nagłówkiem i ładunkiem w następujący sposób:

   {
     "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 prywatnego 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 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 podaj godzinę, o której token JWT wygaśnie dokładnie 3600 sekund.

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

Na przykład:

Java

Za pomocą 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