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

System Google OAuth 2.0 obsługuje interakcje między serwerami, na przykład te między aplikacji i usługi Google. W tym scenariuszu potrzebujesz konta usługi, które jest kontem należącym do Twojej aplikacji, a nie do indywidualnego użytkownika końcowego. Twoje aplikacja wywołuje interfejsy API Google w imieniu konta usługi, więc użytkownicy nie zaangażowane. Ten scenariusz jest czasami nazywany „dwuetapową autoryzację OAuth”, lub „2LO”. (Pokrewne hasło „trzyetapowa autoryzacja OAuth” odnosi się do scenariuszy, w których aplikacja wywołuje interfejsy API Google w imieniu użytkowników i w przypadku których czasami wymagana jest zgoda użytkownika).

Zazwyczaj aplikacja korzysta z konta usługi, gdy do pracy wykorzystuje interfejsy API Google z własnymi danymi, a nie danymi użytkownika. Na przykład aplikacja, która korzysta z Google Cloud, Datastore umożliwiający zachowanie trwałości danych używa konta usługi do uwierzytelniania wywołań Interfejs Google Cloud Datastore API.

Administratorzy domeny Google Workspace mogą też przyznaj kontom usługi uprawnienia dostępu do użytkowników w całej domenie w imieniu użytkowników domeny.

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

Omówienie

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

Następnie aplikacja przygotowuje się do autoryzowanych wywołań interfejsu API przy użyciu dane logowania, aby zażądać tokena dostępu z serwera uwierzytelniania OAuth 2.0.

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

Tworzę konto usługi

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

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

Jeśli Twoja aplikacja działa w Google Compute Engine, skonfigurowane zostanie również konto usługi. automatycznie podczas tworzenia projektu. Trzeba jednak określić zakresy, aplikacja potrzebuje dostępu podczas tworzenia instancji Google Compute Engine. Więcej Więcej informacji zawiera Przygotowuję instancję do użycia kont usługi.

Jeśli Twoja aplikacja nie działa w Google App Engine ani Google Compute Engine, te dane logowania w Google API Console. Generowanie konta usługi dane logowania lub aby wyświetlić wygenerowane przez siebie publiczne dane logowania, wykonaj następujące 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ą.

Możesz wrócić do API Console w dowolnym momencie, aby wyświetlić adres e-mail, publiczny odciski cyfrowe kluczy i inne informacje, a także generowanie dodatkowych par kluczy publiczny/prywatny. Dla: więcej informacji o danych logowania do konta usługi znajdziesz w API Console, zobacz Konta usługi w API Console pliku pomocy.

Zanotuj adres e-mail konta usługi i przechowuj klucz prywatny konta usługi w lokalizacji dostępnej dla Twojej aplikacji. Aplikacja wymaga, aby autoryzowane wywołania interfejsu API.

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

Za pomocą konta Google Workspace administrator Workspace organizacji może autoryzować aplikacji do uzyskiwania dostępu do danych użytkowników Workspace w imieniu użytkowników z domeny Google Workspace. Przykład: aplikacja korzystająca z interfejsu API Kalendarza Google w celu dodawania wydarzeń do kalendarzy wszystkich użytkowników domena Google Workspace używa konta usługi do uzyskiwania dostępu do interfejsu Google Calendar API użytkowników. Autoryzowanie konta usługi do uzyskiwania dostępu do danych w imieniu użytkowników w domenie jest czasem nazywane „przekazywaniem uprawnień dotyczących całej domeny”. z kontem usługi.

Aby przekazać uprawnienia w całej domenie do konta usługi, superadministrator Google W przypadku domeny Workspace należy wykonać te czynności:

  1. Z domeny Google Workspace konsolę administracyjną, kliknij Menu główne; Bezpieczeństwo > Dostęp do danych i kontrola nad nimi > Dostęp do interfejsów API.
  2. W panelu Przekazywanie dostępu w całej domenie kliknij Zarządzaj przekazywaniem dostępu w całej domenie.
  3. Kliknij Dodaj nowy.
  4. W polu Identyfikator klienta wpisz identyfikator klienta konta usługi. Więcej identyfikatora klienta swojego konta usługi w Service accounts page
  5. W polu Zakresy protokołu OAuth (rozdzielone przecinkami) wpisz listę zakresów, które aplikacji powinna mieć dostęp do. Jeśli na przykład aplikacja wymaga dostępu do całej domeny, pełny dostęp 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żytkownicy w domenie Workspace (do „podszywać się pod inne osoby” użytkowników). Przygotowując się do wykonania tych delegowanych wywołań interfejsu API, musisz wyraźnie wskazać użytkownika, przyjmować tożsamość.

Przygotowuję do wywołania delegowanego interfejsu API

Java

Gdy uzyskasz adres e-mail klienta i klucz prywatny z API Console, użyj Biblioteka klienta interfejsów API Google do języka Java aby utworzyć obiekt GoogleCredential na podstawie danych logowania konta usługi, Zakresy, 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 skorzystać z interfejsu domyślne dane logowania aplikacji co może uprościć proces.

Przekazywanie uprawnień w całej domenie

Jeśli delegujesz dostęp do konta usługi w całej domenie i chcesz przyjmować tożsamość konta użytkownika, podaj adres e-mail tego konta z atrybutem Metoda createDelegated obiektu GoogleCredential. Dla: przykład:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

Powyższy kod wykorzystuje obiekt GoogleCredential do wywoływania funkcji createDelegated() . Argumentem metody createDelegated() musi być użytkownik należący do Konto Workspace. Twój kod tworzący żądanie będzie używał tych danych logowania, aby wywoływać Google Interfejsy API korzystające z konta usługi.

Python

Gdy uzyskasz adres e-mail klienta i klucz prywatny z API Console, użyj Biblioteka klienta interfejsów API Google do języka Python aby wykonać te czynności:

  1. Utwórz obiekt Credentials na podstawie danych logowania konta usługi oraz Zakresy, 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 skorzystać z interfejsu domyślne dane logowania aplikacji co może uprościć 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ącej ServiceAccountCredentials obiekt. Na przykład:

    delegated_credentials = credentials.with_subject('user@example.org')

Użyj obiektu Credentials do wywoływania interfejsów API Google w swojej aplikacji.

HTTP/REST

Gdy uzyskasz identyfikator klienta i klucz prywatny z API Console, Twoja aplikacja musi wypełnić następujące kroki:

  1. Utwórz token internetowy JSON (JWT, wymawiany, „jot”), który zawiera nagłówek, zbiór deklaracji oraz podpis.
  2. Poproś o token dostępu z serwera autoryzacji Google OAuth 2.0.
  3. Przetwórz odpowiedź JSON zwracaną przez serwer autoryzacji.

W sekcjach poniżej opisujemy, jak to zrobić.

Jeśli odpowiedź zawiera token dostępu, możesz go użyć do wywołać interfejs API Google. (Jeśli odpowiedź nie zawiera informacji o dostępie , żądanie tokena JWT i tokena mogą mieć nieprawidłowy format lub konto usługi może nie masz uprawnień dostępu do żądanych zakresów).

Gdy token dostępu wygaśnie, aplikacja wygeneruje kolejny JWT, podpisuje go i wysyła żądanie innego tokena dostępu.

Aplikacja serwera używa tokena JWT, aby zażądać tokena od Google
                  serwera autoryzacji, a następnie używa tokena do wywołania punktu końcowego interfejsu API Google. Nie
                  użytkownika końcowego.

W pozostałej części tej sekcji znajdziesz szczegółowe informacje na temat tworzenia i podpisywania tokena JWT, tworzenia żądania tokena dostępu i obsługi odpowiedzi.

Tworzenie tokena JWT

Token JWT składa się z 3 części: nagłówka, zestawu deklaracji i podpis. Zestaw nagłówków i roszczeń to obiekty JSON. Te obiekty JSON są zserializowane do UTF-8, a następnie zakoduj z użyciem kodowania Base64url. To kodowanie zapewnia odporność przed zmianami w kodowaniu powodowanymi powtarzającymi się operacjami kodowania. nagłówek, zestaw twierdzeń oraz podpis są połączone kropką (.).

Token JWT składa się w następujący sposób:

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

Podstawowy ciąg podpisu jest taki:

{Base64url encoded header}.{Base64url encoded claim set}
Tworzenie nagłówka JWT

Nagłówek składa się z trzech pól, które wskazują algorytm podpisywania, format oraz [identyfikator klucza konta usługi] key](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) użytego do podpisania tokena JWT. Algorytm i format są wymagane, a każde pole ma tylko jedną wartość. W miarę wprowadzania dodatkowych algorytmów i formatów ten nagłówek ulegnie zmianie. odpowiednio się zmienia. Identyfikator klucza jest opcjonalny. Jeśli zostanie podany nieprawidłowy, GCP spróbuje ponownie wszystkie klucze powiązane z kontem usługi w celu weryfikacji tokena i odrzucenia go, jeśli: nie znaleziono prawidłowego klucza. Google zastrzega sobie prawo do odrzucenia tokenów z nieprawidłowymi identyfikatorami. w przyszłości.

Konta usługi korzystają z algorytmu SHA-256 RSA i formatu tokena JWT. W rezultacie format JSON nagłówka:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

Reprezentacja tego parametru w Base64url jest taka:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=
Tworzenie zbioru deklaracji JWT

Zbiór deklaracji JWT zawiera informacje o tokenie JWT, w tym o uprawnieniach żądaną (zakresy), obiekt docelowy tokena, wydawca, czas wydania tokena; i okres ważności tokena. Większość pól jest obowiązkowa. Podobnie jak w przypadku nagłówka JWT, Zbiór deklaracji JWT to obiekt JSON używany do obliczania podpisu.

Wymagane roszczenia

Poniżej znajdują się wymagane deklaracje w zbiorze deklaracji JWT. Mogą być wyświetlane w dowolnej kolejności w zestawu reklam.

Nazwa Opis
iss Adres e-mail konta usługi.
scope Lista rozdzielonych spacjami uprawnień, których żąda aplikacja.
aud Deskryptor zamierzonego celu asercji. Podczas tworzenia tokena dostępu żądana jest zawsze wartość https://oauth2.googleapis.com/token.
exp czas do wygaśnięcia potwierdzenia wyrażony w sekundach od 00:00:00 czasu UTC, 1 stycznia 1970 roku. Ta wartość może przypadać maksymalnie 1 godzinę po dacie.
iat czas wystawienia potwierdzenia (w sekundach od 00:00:00 czasu UTC), 1 stycznia 1970 roku.

Poniżej znajduje się przykładowa reprezentacja wymaganych pól w zbiorze deklaracji JWT w formacie JSON:

{
  "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 biznesowych aplikacja może używać przekazywania dostępu w całej domenie do działania w imieniu użytkownika. określonego użytkownika w organizacji. Uprawnienie do wykonywania tego typu przyjmowania innej tożsamości musi zostać przyznany, aby aplikacja mogła przyjmować tożsamość użytkownika. Zazwyczaj jest obsługiwana superadministratora. Więcej informacji: Kontrola dostępu do interfejsów API przy użyciu przekazywania dostępu w całej domenie

Aby uzyskać token dostępu, który przyznaje aplikacji dostęp do zasobu, umieść adres e-mail użytkownika w deklaracji JWT ustawionej jako wartość klucza sub.

Nazwa Opis
sub Adres e-mail użytkownika, którego dotyczy prośba o przekazanie dostępu dostęp.

Jeśli aplikacja nie ma uprawnień do przyjmowania tożsamości użytkownika, odpowiedź na żądanie tokena dostępu zawierające pole sub zostanie wysłane błąd.

Przykładowy zestaw deklaracji JWT zawierający pole sub poniżej:

{
  "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 JWT

Podobnie jak nagłówek JWT, zbiór deklaracji JWT powinien być zserializowany w formacie UTF-8 i Base64url-safe zakodowany. Poniżej znajduje się przykładowa reprezentacja zestawu deklaracji 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
}
Obliczanie podpisu

Podpis internetowy JSON (JWS) to specyfikacja, która zarządza mechaniką generowania podpisu dla JWT. Dane wejściowe podpisu to tablica bajtów tej treści:

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

Podczas obliczania podpisu należy używać algorytmu podpisywania w nagłówku JWT. tylko algorytm podpisywania Google OAuth 2.0 obsługiwany przez serwer autoryzacji Google OAuth 2.0 to RSA korzystający z Algorytm szyfrowania SHA-256. Jest to RS256 w alg w nagłówku JWT.

Podpisz reprezentację danych wejściowych UTF-8 za pomocą algorytmu SHA256withRSA (znanego też jako RSASSA-PKCS1-V1_5-SIGN z funkcją skrótu SHA-256) kluczem prywatnym pobranym z Google API Console. Wynikiem będzie tablica bajtów.

Podpis musi być następnie zakodowany w standardzie Base64url. Nagłówek, zestaw deklaracji i podpis to połączone kropką (.). Wynik to token JWT. it powinny wyglądać następująco (dodane podziały wierszy w celu uniknięcia wątpliwości):

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

Oto przykład tokena JWT przed zakodowaniem 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ładowy token JWT, który został podpisany i jest gotowy do przesł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 za jego pomocą zażądać tokena dostępu. To żądanie tokena dostępu to żądanie HTTPS POST, a treść to URL zakodowany. 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 w razie potrzeby następującego ciągu zakodowanego na potrzeby adresu URL: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion Token JWT z podpisem.

Poniżej znajduje się nieprzetworzony zrzut danych żądania HTTPS POST użytego w tokenie dostępu żądanie:

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 przy użyciu parametru curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Obsługa odpowiedzi

Jeśli token JWT i żądanie tokena dostępu mają prawidłowy format, a konto usługi zawiera uprawnienia do wykonania tej operacji, a następnie odpowiedź JSON z serwera autoryzacji zawiera token dostępu. Oto przykładowa odpowiedź:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokenów dostępu można używać wielokrotnie przez okres określony przez Wartość: expires_in.

Wywoływanie interfejsów API Google

Java

Użyj obiektu GoogleCredential do wywoływania interfejsów API Google, wypełniając następujące kroki:

  1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywoływać za pomocą metody GoogleCredential obiekt. Na przykład:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Wysyłaj żądania do usługi interfejsu API za pomocą interfejsu udostępnianego przez obiekt usługi. Aby na przykład wyświetlić listę instancji baz danych Cloud SQL w pliku w stylu ekscytującym-example-123 projekt:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

Python

Użyj autoryzowanego obiektu Credentials do wywoływania interfejsów API Google, wypełniając następujące kroki:

  1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywoływać. Tworzysz obiekt usługi przez wywołanie funkcji build z nazwą i wersją interfejsu API oraz autoryzowano obiekt Credentials. Na przykład, aby wywołać wersję 1beta3 Cloud SQL Administration API:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Wysyłaj żądania do usługi interfejsu API za pomocą interfejsu udostępnianego przez obiekt usługi. Aby na przykład wyświetlić listę instancji baz danych Cloud SQL w pliku w stylu ekscytującym-example-123 projekt:
    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 w imieniu danego konta usługi lub konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez interfejs API. Aby to zrobić, dołącz token dostępu w żądaniu wysyłanym do interfejsu API przez dodanie zapytania access_token; lub wartość nagłówka HTTP Authorization Bearer. Jeśli to możliwe, preferowany jest nagłówek HTTP, ponieważ ciągi zapytań są zwykle widoczne w dziennikach serwera. Najwięcej można użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (na przykład wywołaniem interfejsu Drive Files API).

Wszystkie interfejsy API Google możesz wypróbować i przejrzeć ich zakresy na stronie OAuth 2.0 Playground.

Przykłady żądań HTTP GET

Wywołanie funkcji drive.files (interfejs Drive Files API) korzystający z protokołu HTTP Authorization: Bearer nagłówek może wyglądać tak: Pamiętaj, że musisz podać 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 za pomocą interfejsu access_token parametr ciągu zapytania:

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

curl przykładu

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

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

Termin ważności tokenów dostępu

Tokeny dostępu wystawione przez serwer autoryzacji Google OAuth 2.0 wygasają po upłynięciu okresu ma wartość expires_in. Gdy token dostępu wygaśnie, aplikacja powinna wygenerować kolejny token JWT, podpisać go i poprosić o nowy token dostępu.

Kody błędów JWT

error pole error_description pole 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, konto usługi nie ma autoryzacji w konsoli administracyjnej domeny użytkownika.

Upewnij się, że konto usługi jest autoryzowane w stronie Przekazywanie dostępu w całej domenie w konsoli administracyjnej dla użytkownika Roszczenie sub (pole).

Zwykle zajmuje to kilka minut, ale może potrwać do 24 godzin. została rozpowszechniona wśród wszystkich użytkowników na Twoim 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 przy użyciu adresu e-mail klienta, a nie identyfikatora klienta (liczbowe) w konsoli administracyjnej. W stronę Przekazywanie dostępu w całej domenie w konsoli administracyjnej, usuń klienta i dodaj go ponownie. identyfikatorem liczbowym.
access_denied (dowolna wartość) Jeśli używasz przekazywania dostępu w całej domenie, co najmniej 1 żądany zakres nie jest autoryzowany w konsoli administracyjnej.

Upewnij się, że konto usługi jest autoryzowane w stronie Przekazywanie dostępu w całej domenie w konsoli administracyjnej dla użytkownika deklaracje sub (pole) oraz że obejmuje ono wszystkie żądane zakresy w deklaracji scope Twojego tokena JWT.

Zwykle zajmuje to kilka minut, ale może potrwać do 24 godzin. została rozpowszechniona wśród wszystkich użytkowników na Twoim koncie Google.

admin_policy_enforced (dowolna wartość) Konto Google nie może autoryzować co najmniej jednego żądanego zakresu z powodu zasadami administratora Google Workspace.

Przeczytaj artykuł pomocy dla administratorów Google Workspace Określ, które zewnętrzne aplikacje wewnętrzne uzyskują dostęp do danych Google Workspace, aby dowiedzieć się więcej o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczeniami do identyfikator klienta OAuth jest jawnie przyznany.

invalid_client (dowolna wartość)

Klient OAuth lub token JWT jest nieprawidłowy lub nieprawidłowo skonfigurowany.

Szczegółowe informacje znajdziesz w opisie błędu.

Sprawdź, czy token JWT jest prawidłowy i zawiera prawidłowe deklaracje.

Upewnij się, że klient i konto usługi OAuth został poprawnie skonfigurowany i używasz prawidłowego adresu e-mail.

Sprawdź, czy token JWT jest prawidłowy i został wydany dla identyfikatora klienta w użytkownika.

invalid_grant Not a valid email. Użytkownik nie istnieje. Sprawdź, czy adres e-mail w polu roszczenia sub 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 lokalny czas systemowy jest nieprawidłowy. Może się to również stać, jeśli Wartość exp przypada o ponad 65 minut w przyszłości z wartości iat, lub wartość exp jest mniejsza niż wartość iat.

Sprawdź, czy zegar w systemie, w którym został wygenerowany token JWT, jest prawidłowy. Jeśli Jeśli to konieczne, zsynchronizuj swój czas z NTP Google.

invalid_grant Invalid JWT Signature.

Potwierdzenie JWT jest podpisane kluczem prywatnym niepowiązanym z kontem usługi zidentyfikowany przez adres e-mail klienta lub użyty klucz został usunięty, wyłączony lub wygasła.

Potwierdzenie JWT może też być nieprawidłowo zakodowane – musi Zakodowany w standardzie Base64, bez znaków nowego wiersza i dopełnienia znaków równości.

Zdekoduj zbiór deklaracji JWT i sprawdź, z którym kluczem podpisano potwierdzenie z kontem usługi.

Użyj udostępnionej przez Google biblioteki OAuth, aby sprawdzić, czy token JWT został wygenerowany 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 (tzn. jest nieprawidłowy).

Sprawdź, czy pole deklaracji scope tokena JWT jest wypełnione i porównaj zawarte w nim zakresy z udokumentowanymi zakresami interfejsów API, których chcesz używać, upewnij się, że nie ma błędów ani literówek.

Pamiętaj, że lista zakresów w deklaracji scope musi być rozdzielona znakami spacje, a nie przecinki.

disabled_client The OAuth client was disabled. Klucz używany do podpisywania potwierdzenia JWT jest wyłączony.

Otwórz Google API Console, a następnie w sekcji Uprawnienia Administracja > kont usługi, włącz konto usługi, które zawiera „identyfikator klucza”. w użyciu do podpisania asercji.

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 Google Konta w określonej lokalizacji Organizacja Google Cloud.

Użyj konta usługi organizacji do uwierzytelnienia. Potwierdź typ użytkownika konfiguracji aplikacji OAuth.

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

Niektóre interfejsy API Google umożliwiają wykonywanie autoryzowanych wywołań interfejsu API przy użyciu podpisanego tokena JWT bezpośrednio jako zamiast tokena dostępu OAuth 2.0. Jeśli to możliwe, można uniknąć konieczności , aby wysłać żądanie sieciowe do serwera autoryzacji Google przed wywołaniem interfejsu API.

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

  1. Utwórz konto usługi w sposób opisany powyżej. Koniecznie zachować plik JSON otrzymany przy tworzeniu konta.
  2. Używanie dowolnej standardowej biblioteki JWT, np. biblioteki jwt.io, utwórz token JWT z nagłówkiem i ładunek jak w tym 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 klucz prywatny konta usługi ID. Tę wartość znajdziesz w polu private_key_id na koncie usługi Plik JSON.
    • W polach iss i sub podaj adres e-mail konta usługi adresu. Tę wartość znajdziesz w polu client_email swojej usługi plik JSON konta.
    • W polu aud określ punkt końcowy API. Na przykład: https://SERVICE.googleapis.com/
    • W polu iat podaj bieżący czas systemu Unix oraz exp należy określić dokładnie 3600 sekund później, kiedy token JWT tracą ważność.

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

Na przykład:

Java

Zastosowanie 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

Użycie 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')
  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

Wdrażanie Ochrony wszystkich kont

Dodatkowy krok, który musisz wykonać, aby chronić użytkowników Liczba kont, na których jest zaimplementowane kilka kont ochrony dzięki korzystaniu z oferowanej przez Google usługi ochrony wszystkich kont. Ta usługa pozwala subskrybować powiadomienia o zdarzeniach związanych z bezpieczeństwem, które dostarczają do aplikacji informacje na temat: na koncie użytkownika. Następnie możesz wykorzystać te informacje do podjęcia działań w zależności od tego, podejmowania decyzji o reagowaniu na zdarzenia.

Oto kilka przykładów typów zdarzeń wysyłanych do Twojej aplikacji przez usługę ochrony wszystkich kont Google:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

Zobacz Ochrona kont użytkowników za pomocą strony Ochrona wszystkich kont . , aby dowiedzieć się więcej o wdrażaniu Ochrony wszystkich kont i pełnej listy dostępnych zdarzeń.