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.
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.
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:
- Otwórz Service accounts page.
- If prompted, select a project, or create a new one.
- Kliknij Utwórz konto usługi .
- W obszarze Szczegóły konta usługi wpisz nazwę, identyfikator i opis konta usługi, a następnie kliknij Utwórz i kontynuuj .
- Opcjonalnie: w obszarze Przyznaj temu kontu usługi dostęp do projektu wybierz role uprawnień, które chcesz przyznać kontu usługi.
- Kliknij Kontynuuj .
- 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.
- Kliknij Gotowe .
Następnie utwórz klucz konta usługi:
- Kliknij adres e-mail utworzonego konta usługi.
- Kliknij kartę Klucze .
- Z listy rozwijanej Dodaj klucz wybierz opcję Utwórz nowy klucz .
- 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.
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.
Aby delegować dostęp do konta usługi w całej domenie, superadministrator domeny Google Workspace musi wykonać te czynności:
- W konsoli administracyjnej domeny Google Workspace kliknij Menu główne > Zabezpieczenia > Kontrola dostępu i dane > Dostęp do interfejsów API.
- W panelu Przekazywanie dostępu w całej domenie wybierz Zarządzaj przekazywaniem dostępu w całej domenie.
- Kliknij Dodaj nowy.
- 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 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.
- 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ć.
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("user@example.com");
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:
- 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.
- 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 obiektuServiceAccountCredentials
. Na przykład:delegated_credentials = credentials.with_subject('user@example.org')
Użyj obiektu danych logowania, aby wywołać interfejsy API Google w swojej aplikacji.
HTTP/REST
Gdy uzyskasz identyfikator klienta i klucz prywatny z API Console, 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.
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": "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 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": "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 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": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "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":"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 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:
- 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();
- 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:
- 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 obiektemCredentials
. 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)
- 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 ( 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 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 |
|
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 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. |
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ć:
- Utwórz konto usługi w sposób opisany powyżej. Pamiętaj, aby zachować plik JSON otrzymany podczas tworzenia konta.
- 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": "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 prywatnego 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
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 poluexp
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("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