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

Trójka Więcej informacji znajdziesz w dokumentacji uwierzytelniania w dokumentacji Google Cloud Platform.

System Google OAuth 2.0 obsługuje interakcje między serwerami, np. między aplikacją internetową a usługą Google. W tym przypadku potrzebujesz konta usługi, które należy do Twojej aplikacji, a nie do jednego 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 określany jako "dwustopniowy OAuth,""2LO." Powiązany termin "trzyskładnikowy OAuth" odnosi się do sytuacji, w których aplikacja wywołuje interfejsy API Google w imieniu użytkowników, a 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 zamiast danych użytkownika. Na przykład aplikacja, która przechowuje dane w Google Cloud Datastore, używa konta usługi do uwierzytelniania wywołań interfejsu Google Cloud Datastore API.

Administratorzy domeny Google Workspace mogą też przyznawać kontu usługi uprawnienia do całej domeny w celu uzyskiwania dostępu do danych użytkowników w imieniu użytkowników w domenie.

Ten dokument opisuje, jak aplikacja może zakończyć przepływ OAuth 2.0 między serwerami za pomocą biblioteki klienta interfejsów API Google (zalecane) lub HTTP.

Za pomocą niektórych interfejsów API Google możesz wykonywać autoryzowane wywołania interfejsu API za pomocą podpisanego tokena JWT, zamiast korzystać z protokołu OAuth 2.0, co pozwala zapisywać żądania sieciowe. Zobacz Dodatek: autoryzacja konta usługi bez protokołu OAuth.

Przegląd

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

Następnie aplikacja przygotowuje się do wykonania autoryzowanych wywołań interfejsu API przy użyciu danych logowania konta usługi, aby zażądać 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: Twoja aplikacja może wykonywać te zadania za pomocą biblioteki klienta interfejsów API Google dla danego języka lub przez bezpośrednią interakcję z systemem OAuth 2.0 przez HTTP. Mechanika interakcji uwierzytelniania serwer-serwer wymaga jednak, aby aplikacje tworzyły i kryptograficzne tokeny internetowe JSON (JWT) oraz mogły łatwo wprowadzać poważne błędy, które mogą mieć istotny wpływ na bezpieczeństwo aplikacji.

Zdecydowanie zalecamy używanie bibliotek takich jak biblioteki klienta Google API, 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 i zawiera co najmniej 1 parę publiczny/prywatny. Jeśli włączono przekazywanie dostępu w całej domenie, identyfikator klienta jest też częścią danych logowania na konto usługi.

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

Jeśli Twoja aplikacja działa w Google Compute Engine, konto usługi jest też konfigurowane automatycznie podczas tworzenia projektu, ale musisz określić zakresy, do których aplikacja musi mieć dostęp podczas tworzenia instancji Google Compute Engine. 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 albo wygenerować dodatkowe pary kluczy publicznych/prywatnych. Więcej informacji o danych logowania na konto usługi w pliku API Consoleznajdziesz w sekcji Konta usługi w pliku pomocy API Console.

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

Uwaga: klucze prywatne musisz bezpiecznie przechowywać zarówno w środowiskach programistycznych, jak i produkcyjnych. Google nie przechowuje kopii Twoich kluczy prywatnych, tylko Twoich kluczy publicznych. Więcej informacji znajdziesz w sekcji Bezpieczne korzystanie z danych logowania klienta na stronie Zasady OAuth 2.0.

Przekazywanie dostępu do konta usługi w ramach całej domeny

Jeśli masz konto Google Workspace, administrator organizacji może autoryzować aplikację do uzyskiwania dostępu 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 w celu uzyskiwania dostępu do danych w imieniu użytkowników w domenie jest czasami nazywana „przekazywaniem uprawnień w całej domenie” do konta usługi.

Uwaga: gdy używasz Google Workspace Marketplace do instalowania aplikacji w Twojej domenie, wymagane uprawnienia są przyznawane automatycznie podczas instalacji. Nie musisz ręcznie autoryzować kont usługi, których używa aplikacja.

Uwaga: kont usługi możesz używać w aplikacjach działających z domeny Google Workspace, ale nie są one częścią Twojego konta Google Workspace i nie podlegają zasadom domeny skonfigurowanym przez administratorów Google Workspace. Na przykład zasady skonfigurowane w konsoli administracyjnej Google Workspace w celu ograniczenia możliwości udostępniania dokumentów poza domenę przez użytkowników Google Workspace nie będą miały zastosowania na kontach usługi.

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

1. W konsoli administracyjnej Google Workspace otwórz Menu główne > Security > Access and data Control > API Control.
2. W panelu Przekazywanie dostępu w całej domenie wybierz Zarządzaj przekazywaniem dostępu w całej domenie.
3. Kliknij Dodaj domenę.
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 wykonywania wywołań interfejsu API jako użytkowników w Twojej domenie (do: "impersonate" użytkowników). Przygotowując się do wykonywania autoryzowanych wywołań interfejsu API, określasz użytkownika, pod który chcesz się podszywać.

Uwaga: przyznawanie dostępu do tożsamości może potrwać kilka minut po dodaniu identyfikatora klienta, ale w niektórych przypadkach zastosowanie tych zmian na kontach wszystkich użytkowników konta Google może potrwać do 24 godzin.

Przygotowuję do wywołania autoryzowanego interfejsu API

Java

Po otrzymaniu adresu e-mail i klucza prywatnego klienta w API Consoleużyj Biblioteki klienta Google APIs for Java, aby utworzyć obiekt GoogleCredential z danych logowania konta usługi i zakresów, do których aplikacja musi mieć dostęp. 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 upraszcza ten proces.

Przekazywanie uprawnień w całej domenie

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

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

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

Python

Po otrzymaniu adresu e-mail i klucza prywatnego klienta w API Consoleużyj Biblioteki klienta Google APIs for Python, aby wykonać te czynności:

1. Utwórz obiekt Credentials na podstawie danych logowania do konta usługi i zakresów, do których aplikacja musi mieć dostęp. 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 upraszcza ten proces.

2. Przekazywanie uprawnień w całej domenie

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

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

Używaj obiektów danych logowania do wywoływania interfejsów API Google w swojej aplikacji.

HTTP/REST

Zalecenie: chociaż aplikacja może wykonywać te zadania bezpośrednio przez system OAuth 2.0 za pomocą HTTP, mechanika interakcji uwierzytelniania serwer-serwer wymaga, aby aplikacje tworzyły i szyfrowały tokeny internetowe JSON (JWT) i łatwo zgłaszałyby poważne błędy, które mogą mieć istotny wpływ na bezpieczeństwo aplikacji.

Zdecydowanie zalecamy używanie bibliotek takich jak biblioteki klienta Google API, które wyodrębniają kryptografię od kodu aplikacji.

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

1. Utwórz token sieciowy JSON (JWT, wymowa i &ott;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.

Sekcje poniżej opisują, jak wykonać te czynności.

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

Gdy token dostępu wygaśnie, aplikacja generuje kolejny token JWT, podpisuje go i wysyła prośbę o kolejny token dostępu.

W dalszej części tej sekcji znajdziesz szczegółowe informacje o tworzeniu tokena JWT, podpisywaniu tokena JWT, tworzeniu żądania tokena dostępu i obsłudze odpowiedzi.

Tworzenie tokena JWT

Token JWT składa się z 3 części: nagłówka, zestawu roszczeń i podpisu. Nagłówek i zbiór deklaracji to obiekty JSON. Te obiekty JSON są serializowane do bajtów UTF-8, a następnie zakodowane przy użyciu kodowania Base64url. Kodowanie jest odporne na zmiany kodu spowodowane wielokrotnymi operacjami kodowania. Nagłówek, zestaw roszczeń i podpis są łączone z kropką (.).

Token JWT składa się z tych elementów:

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

Podstawowy ciąg podpisu:

{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 ma tylko jedną wartość. W miarę wprowadzania dodatkowych algorytmów i nagłówków 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 wygląda tak:

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

Reprezentacja Base64url wygląda tak:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Tworzenie roszczenia JWT

Zestaw deklaracji JWT zawiera informacje o tokenie JWT, w tym wymagane uprawnienia (zakresy), miejsce docelowe tokena, wydawcę, czas wydania tokena oraz czas życia tokena. Większość pól jest obowiązkowa. Podobnie jak w przypadku nagłówka JWT, zestaw deklaracji JWT to obiekt JSON i jest używany przy obliczaniu podpisu.

Wymagane roszczenia

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

Nazwa	Opis
iss	Adres e-mail konta usługi.
scope	Lista rozdzielonych spacjami uprawnień, o które prosi aplikacja.
aud	Deskryptor celu intencji asercji. Podczas tworzenia 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 UTC 1 stycznia 1970 roku. Wartość ma maksymalnie 1 godzinę od wydania.
iat	Czas potwierdzenia potwierdzenia podany w sekundach od 00:00:00 UTC 1 stycznia 1970 roku.

Poniżej znajdziesz reprezentację wymaganych pól JSON w zestawie 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 konkretnego użytkownika w organizacji. Aby aplikacja mogła podszywać się pod innego użytkownika, musisz przyznać odpowiednie uprawnienia. Taki komunikat jest zwykle obsługiwany przez superadministratora. Więcej informacji znajdziesz w artykule Kontrolowanie dostępu do interfejsów 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 roszczeniu JWT ustawionym jako wartość w polu sub.

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

Jeśli aplikacja nie ma uprawnień do podszywania się pod użytkownika, odpowiedź na żądanie tokena dostępu zawierające pole sub będzie traktowane jako błąd.

Poniżej znajdziesz przykładowy zestaw deklaracji JWT zawierający pole sub:

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

Kodowanie zestawu tokenów JWT

Podobnie jak w przypadku nagłówka JWT, zestaw tokenów JWT powinien być zserializowany za pomocą kodowania UTF-8 i Base64url-safe-safe. Poniżej znajduje się przykład pliku JSON reprezentującego zestaw deklaracji JWT:

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

Przetwarzanie podpisu

Podpis podpisu JSON (JWS) to specyfikacja przedstawiająca mechanizm generowania podpisu tokena JWT. Dane wejściowe podpisu to bajt:

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

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

Podpisz kodowanie UTF-8 zgodnie z wartością SHA256withRSA (znaną też pod nazwą RSASSA-PKCS1-V1_5-SIGN z funkcją skrótu SHA-256) kluczem prywatnym uzyskanym z pola Google API Console. Dane wyjściowe będą tablicą bajtów.

Podpis musi być zakodowany w formacie Base64url. Nagłówek, zestaw roszczeń i podpis są łączone z kropką (.). Efektem jest token JWT. Powinien wyglądać tak (fragmenty wiersza dodane dla jasności):

{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]

Oto przykład tokena JWT, który został podpisany i jest gotowy do przesłania:

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

Wysyłam żądanie tokena dostępu

Po wygenerowaniu podpisanego tokena JWT aplikacja może go użyć, aby poprosić o token 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, zakodowanego w adresie URL: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	Token JWT wraz z podpisem.

Poniżej znajdziesz nieprzetworzony zrzut żądania HTTPS POST używany 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 to samo żądanie z użyciem znacznika 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 tokena JWT i tokena dostępu jest poprawnie utworzone, a konto usługi ma uprawnienia do wykonania 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 czasie trwania określonym w wartości expires_in.

Wywołanie interfejsów API Google

Java

Skorzystaj z obiektu GoogleCredential, aby wywoływać interfejsy API Google, wykonując te czynności:

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

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

2. wysyłać żądania do usługi API za pomocą interfejsu podanego przez obiekt usługi; Aby np. wyświetlić listę baz danych Cloud SQL w eksploracyjnym 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ć. Obiekt usługi tworzysz przez wywołanie funkcji build z nazwą i wersją interfejsu API oraz autoryzowanym obiektem Credentials. Aby na przykład wywoływać interfejs API Cloud SQL Administration w wersji 1 beta3:

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

2. wysyłać żądania do usługi API za pomocą interfejsu podanego przez obiekt usługi; Aby np. wyświetlić listę baz danych Cloud SQL w eksploracyjnym projekcie example-123:

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

HTTP/REST

Gdy aplikacja otrzyma 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. Aby to zrobić, dołącz do żądania do interfejsu API token dostępu, podając parametr zapytania access_token lub wartość nagłówka Authorization HTTP Bearer. W miarę możliwości preferowany jest nagłówek HTTP, ponieważ ciągi zapytania są zazwyczaj widoczne w dziennikach serwera. W większości przypadków biblioteki klienta możesz skonfigurować w wywołaniach 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 użycia HTTP GET

Wywołanie punktu końcowego drive.files (interfejs Drive Files API) z użyciem nagłówka HTTP Authorization: Bearer może wyglądać tak: 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 w przypadku uwierzytelnionego użytkownika za pomocą 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, który korzysta z 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

Kiedy tokeny dostępu wygasają

Tokeny dostępu wystawione przez serwer autoryzacji Google OAuth 2.0 tracą ważność po czasie określonym przez wartość expires_in. Po wygaśnięciu tokena dostępu aplikacja powinna wygenerować kolejny token JWT, podpisać go i poprosić o kolejny token dostępu.

Kody błędów JWT

Pole error	Pole error_description	Znaczenie	Rozwiązanie
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. Choć zwykle zajmuje to kilka minut, rozpowszechnienie ich na wszystkich kontach 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 zautoryzowane przy użyciu adresu e-mail klienta zamiast identyfikatora klienta (numerycznego) w konsoli administracyjnej.	Na stronie Przekazywanie dostępu w całej domenie w konsoli administracyjnej usuń klienta i dodaj go ponownie z identyfikatorem liczbowym.
access_denied	(dowolna wartość)	Jeśli używasz przekazywania dostępu w całej domenie, co najmniej 1 z wymaganych zakresów 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, w przypadku użytkownika (w polu sub), i że zawiera ono wszystkie zakresy, o które prosisz w deklaracji tokena JWT scope. Choć zwykle zajmuje to kilka minut, rozpowszechnienie ich na wszystkich kontach użytkowników na koncie Google może potrwać do 24 godzin.
invalid_grant	Not a valid email.	Użytkownik nie istnieje.	Sprawdź, czy adres e-mail podany w polu 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 jest nieprawidłowy. Może się tak też zdarzyć, jeśli wartość exp przypada w przyszłości o więcej niż 65 minut od wartości iat lub gdy wartość exp jest niższa niż wartość iat.	Upewnij się, że zegar w systemie, w którym został wygenerowany 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, który nie jest powiązany z kontem usługi określonym w adresie e-mail klienta, lub użyty klucz został usunięty, wyłączony lub wygasł. Potwierdzenie tokena JWT może być nieprawidłowo zakodowane – musi być zakodowane w formacie Base64 bez znaków nowego wiersza i znaków równości.	Zdekoduj ustawiony token JWT i sprawdź, czy klucz podpisany przez potwierdzenie jest powiązany z kontem usługi. Spróbuj użyć biblioteki OAuth udostępnionej przez Google, aby sprawdzić, czy token JWT jest poprawnie wygenerowany.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Nie zażądano żadnych zakresów (pusta lista) lub jeden z żądanych zakresów nie istnieje (tj. jest nieprawidłowy).	Sprawdź, czy roszczenie scope (pole) tokena JWT jest wypełnione, i porównaj zakresy zawarte w udokumentowanych zakresach interfejsów API, których chcesz użyć. Dzięki temu nie wystąpią błędy ani literówki. Pamiętaj, że lista zakresów w roszczeniu scope musi być oddzielona spacjami, a nie przecinkami.
disabled_client	The OAuth client was disabled.	Klucz używany do podpisywania potwierdzenia tokena JWT jest wyłączony.	Przejdź do Google API Consolei w sekcji Administracja &g; administratora igt; konta usługi włącz konto usługi zawierające &"klucz klucza" używany do podpisywania asercji.

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

W przypadku niektórych interfejsów API Google możesz wykonywać autoryzowane wywołania interfejsu API, używając podpisanego tokena JWT jako okaziciela, a nie tokena dostępu OAuth 2.0. W miarę możliwości możesz uniknąć wysyłania żądań sieciowych do serwera autoryzacji Google, zanim wywołasz interfejs API.

Jeśli interfejs API, który chcesz wywołać, ma publikację usługi w repozytorium GitHub Google API, możesz wykonywać autoryzowane wywołania API za pomocą 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, np. dostępnej w jwt.io, utwórz token JWT z nagłówkiem i ładunkiem jak w tym przykładzie:

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

• W polu kid w nagłówku podaj identyfikator klucza prywatnego konta usługi. Możesz ją znaleźć w polu private_key_id pliku JSON konta usługi.
• W polach iss i sub podaj adres e-mail konta usługi. Możesz ją znaleźć w polu client_email pliku JSON konta usługi.
• W polu aud podaj punkt końcowy interfejsu API. Na przykład: https://SERVICE.googleapis.com/.
• W polu iat podaj bieżący czas w systemie Unix, a w polu exp podaj godzinę, po której token JWT wygaśnie.

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

Przykład:

Java

Korzystanie z plików 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