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:
- 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ą.
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:
- 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.
- W panelu Przekazywanie dostępu w całej domenie kliknij Zarządzaj przekazywaniem dostępu w całej domenie.
- Kliknij Dodaj nowy.
- W polu Identyfikator klienta wpisz identyfikator klienta konta usługi. Więcej identyfikatora klienta swojego konta usługi w Service accounts page
- 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.
- 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:
- 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.
- 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ącejServiceAccountCredentials
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:
- Utwórz token internetowy JSON (JWT, wymawiany, „jot”), który zawiera nagłówek, zbiór deklaracji oraz podpis.
- Poproś o token dostępu z serwera autoryzacji Google OAuth 2.0.
- 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.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/oauth2/images/flows/jwt.png?authuser=19&hl=pl)
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:
- 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();
- 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:
- 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 obiektCredentials
. Na przykład, aby wywołać wersję 1beta3 Cloud SQL Administration API:import googleapiclient.discovery sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
- 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 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 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 |
|
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 Pamiętaj, że lista zakresów w deklaracji |
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ć:
- Utwórz konto usługi w sposób opisany powyżej. Koniecznie zachować plik JSON otrzymany przy tworzeniu konta.
- 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 poluprivate_key_id
na koncie usługi Plik JSON. - W polach
iss
isub
podaj adres e-mail konta usługi adresu. Tę wartość znajdziesz w poluclient_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 orazexp
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')
- 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ń.