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.
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.
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:
- Otwórz Service accounts page.
- If prompted, select a project, or create a new one.
- Kliknij Utwórz konto usługi.
- W ramach serwisu szczegóły konta, wpisz nazwę, ID, i opis dla konta usługi, a następnie kliknij przycisk Utwórz i kontynuować.
- Opcjonalnie: W Grant to konto usługa dostępu do projektu, wybierz role IAM do przyznania się do konta usługi.
- Kliknij Kontynuuj.
- 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.
- Kliknij Gotowe.
- Kliknij Tworzenie klucza, a następnie kliknij przycisk Utwórz.
Następnie utwórz klucz konta usługi:
- Kliknij adres e-mail utworzonego konta usługi.
- Kliknij kartę kluczy.
- Na liście rozwijanej dodać klucz, wybierz Utwórz nowy klucz.
- 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.
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.
Aby przekazać uprawnienia do całej domeny kontu usługi, superadministrator domeny Google Workspace musi wykonać te czynności:
- W konsoli administracyjnej Google Workspace otwórz Menu główne > Zabezpieczenia > Dostęp i kontrola danych > Dostęp do interfejsów API.
- W okienku Przekazywanie dostępu w całej domenie wybierz Zarządzaj przekazywaniem dostępu w całej domenie.
- Kliknij Dodaj nową.
- W polu Identyfikator klienta wpisz identyfikator klienta konta usługi. Identyfikator klienta konta usługi znajdziesz w Service accounts page.
- 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.
- 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ć.
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("user@example.com");
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:
- 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.
- 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 obiektuServiceAccountCredentials
. Przykład:delegated_credentials = credentials.with_subject('user@example.org')
Obiekt danych logowania umożliwia wywoływanie interfejsów API Google w aplikacji.
HTTP/REST
Gdy uzyskasz identyfikator klienta i klucz prywatny z API Console, Twoja aplikacja musi wykonać te czynności:
- Utwórz token sieciowy JSON (JWT, wymowa, "jot"), który zawiera nagłówek, zestaw roszczeń i podpis.
- Poproś o token dostępu z serwera autoryzacji Google OAuth 2.0.
- 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": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "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": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "sub": "some.user@example.com", "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": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "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":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "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:
- 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();
- 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
:
- 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 obiektCredentials
. 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)
- 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 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 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 |
|
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 Pamiętaj, że lista zakresów w roszczeniu |
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ć:
- Utwórz konto usługi w sposób opisany powyżej. Pamiętaj, aby zachować plik JSON otrzymany po utworzeniu konta.
- 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": "123456-compute@developer.gserviceaccount.com", "sub": "123456-compute@developer.gserviceaccount.com", "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 poluprivate_key_id
pliku JSON konta usługi. - W polach
iss
isub
podaj adres e-mail konta usługi. Tę wartość znajdziesz w poluclient_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 poluexp
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("123456-compute@developer.gserviceaccount.com") .withSubject("123456-compute@developer.gserviceaccount.com") .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': '123456-compute@developer.gserviceaccount.com', 'sub': '123456-compute@developer.gserviceaccount.com', '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')
- 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