Ten dokument wyjaśnia, jak aplikacje komputerowe (np. aplikacje działające w systemie Windows, macOS lub Linux albo narzędzia interfejsu wiersza poleceń) używają punktów końcowych OAuth 2.0 Google do autoryzowania dostępu do interfejsów API Google.
Protokół OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy jednoczesnym zachowaniu poufności nazw, haseł i innych informacji. Na przykład aplikacja może używać protokołu OAuth 2.0, aby uzyskać od użytkowników uprawnienia do przechowywania plików na ich Dyskach Google.
Aplikacje komputerowe są instalowane lokalnie na komputerze użytkownika (np. samodzielne oprogramowanie komputerowe, narzędzia CLI dla programistów, narzędzia do synchronizacji w tle lub skrypty). Ponieważ te aplikacje są rozpowszechniane na poszczególnych urządzeniach, zakłada się, że nie mogą one zachować poufności (są to klienci publiczni). Mogą uzyskiwać dostęp do interfejsów API Google, gdy użytkownik aktywnie korzysta z aplikacji lub gdy aplikacja działa w tle.
Ten proces autoryzacji jest podobny do tego, który jest używany w aplikacjach serwera WWW. Główna różnica polega na tym, że aplikacje komputerowe muszą otwierać przeglądarkę systemową i podawać lokalny identyfikator URI przekierowania (np. adres IP pętli zwrotnej), aby obsługiwać odpowiedzi z serwera autoryzacji Google.
Biblioteki i przykłady
Podczas wdrażania protokołu OAuth 2.0 w aplikacjach komputerowych zalecamy korzystanie z bibliotek klienta interfejsów API Google w wybranym języku programowania (np. Python, Java, Node.js, Go, .NET). Biblioteki klienta obsługują autoryzację użytkowników i zarządzanie tokenami, dzięki czemu implementacja jest prostsza i mniej podatna na błędy niż bezpośrednie korzystanie z punktów końcowych HTTP/REST niższego poziomu.
W przypadku aplikacji mobilnych zapoznaj się z przewodnikami po autoryzacji na Android i iOS.
W przypadku aplikacji działających na urządzeniach, które nie obsługują przeglądarki systemowej lub mają ograniczone możliwości wprowadzania danych, takich jak telewizory, konsole do gier, aparaty fotograficzne czy drukarki, zapoznaj się z artykułem OAuth 2.0 na telewizorach i urządzeniach lub Logowanie się na telewizorach i urządzeniach z ograniczoną możliwością wpisywania.
Wymagania wstępne
Włączanie interfejsów API w projekcie
Każda aplikacja, która wywołuje interfejsy API Google, musi mieć je włączone w Konsoli interfejsów API.
Aby włączyć interfejs API w projekcie:
- Otwórz Bibliotekę interfejsów API w Konsoli interfejsów API Google.
- Jeśli pojawi się taka prośba, wybierz projekt lub utwórz nowy.
- Biblioteka interfejsów API zawiera listę wszystkich dostępnych interfejsów API pogrupowanych według rodziny usług i popularności. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny na liście, wyszukaj go lub kliknij Wyświetl wszystkie w rodzinie usług, do której należy.
- Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
- Jeśli pojawi się taka prośba, włącz płatności.
- Jeśli pojawi się taka prośba, przeczytaj i zaakceptuj Warunki korzystania z interfejsu API.
Tworzenie danych uwierzytelniających
Każda aplikacja, która używa protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google, musi mieć dane uwierzytelniające, które identyfikują ją na serwerze OAuth 2.0 Google. Poniżej znajdziesz instrukcje tworzenia danych logowania do projektu. Twoje aplikacje mogą następnie używać danych logowania, aby uzyskać dostęp do interfejsów API, które zostały włączone w tym projekcie.
- Otwórz stronę Klienci.
- Kliknij Utwórz klienta.
- Wybierz typ aplikacji Aplikacja komputerowa.
- W polu Nazwa wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana na stronie Klientów projektu, aby umożliwić identyfikację klienta.
- Kliknij Utwórz.
Identyfikator klienta i tajny klucz klienta zostaną wygenerowane i wyświetlone w konsoli Google Cloud. Aplikacje komputerowe są klientami publicznymi i nie mogą zachować poufności tajnych kluczy. Zawsze używaj PKCE (Proof Key for Code Exchange) podczas żądania kodów autoryzacji.
Identyfikowanie zakresów dostępu
Zakresy umożliwiają aplikacji żądanie dostępu tylko do tych zasobów, których potrzebuje, a użytkownikom – kontrolowanie zakresu dostępu, który przyznają aplikacji. W związku z tym może istnieć odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.
Zanim zaczniesz wdrażać autoryzację OAuth 2.0, zalecamy określenie zakresów, do których aplikacja będzie potrzebować uprawnień dostępu.
Dokument Zakresy interfejsów API OAuth 2.0 zawiera pełną listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google.
Uzyskiwanie tokenów dostępu OAuth 2.0
Poniżej opisujemy, jak aplikacja współdziała z serwerem OAuth 2.0 Google, aby uzyskać zgodę użytkownika na wysłanie żądania do interfejsu API w jego imieniu. Aplikacja musi uzyskać tę zgodę, zanim będzie mogła wykonać żądanie do interfejsu API Google, które wymaga autoryzacji użytkownika.
Krok 1. Wygeneruj weryfikator kodu i wyzwanie
Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo przepływu aplikacji instalowanej. Dla każdego żądania autoryzacji tworzony jest unikalny weryfikator kodu, a jego przekształcona wartość, zwana „code_challenge”, jest wysyłana do serwera autoryzacji w celu uzyskania kodu autoryzacji.
Tworzenie weryfikatora kodu
code_verifier to losowy ciąg kryptograficzny o wysokiej entropii, który składa się z niezastrzeżonych znaków [A-Z] / [a-z] / [0-9] / „-” / „.” / „_” / „~” i ma długość od 43 do 128 znaków.
Weryfikator kodu powinien mieć wystarczającą entropię, aby odgadnięcie wartości było niemożliwe.
Tworzenie kodu
Obsługiwane są 2 metody tworzenia wyzwania kodu.
| Metody generowania kodu dynamicznego | |
|---|---|
| S256 (zalecane) | Wyzwanie kodu to skrót SHA256 weryfikatora kodu zakodowany w standardzie Base64URL (bez dopełnienia).
|
| plain | Wyzwanie kodu ma taką samą wartość jak wygenerowany powyżej weryfikator kodu.
|
Krok 2. Wyślij żądanie do serwera OAuth 2.0 Google
Aby uzyskać autoryzację użytkownika, wyślij żądanie do serwera autoryzacji Google na adres https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy obsługuje wyszukiwanie aktywnej sesji, uwierzytelnia użytkownika i uzyskuje jego zgodę. Punkt końcowy jest dostępny tylko przez SSL i odrzuca połączenia HTTP (inne niż SSL).
Serwer autoryzacji obsługuje te parametry ciągu zapytania w przypadku zainstalowanych aplikacji:
| Parametry | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Wymagany
Identyfikator klienta aplikacji. Tę wartość znajdziesz na stronie Klientów w konsoli Cloud. |
||||||
redirect_uri |
Wymagany
Określa, jak serwer autoryzacji Google wysyła odpowiedź do aplikacji. W przypadku aplikacji instalowanych dostępnych jest kilka opcji przekierowania. Dane logowania do autoryzacji należy skonfigurować z myślą o konkretnej metodzie przekierowania. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0, które zostały skonfigurowane na stronie Klienty w konsoli Cloud klienta. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI, pojawi się błąd W tabeli podano odpowiednią wartość parametru
|
||||||
response_type |
Wymagany
Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. W przypadku zainstalowanych aplikacji ustaw wartość parametru na |
||||||
scope |
Wymagany
Rozdzielona spacjami lista zakresów, które identyfikują zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości są wyświetlane na ekranie zgody, który Google pokazuje użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu tylko do tych zasobów, których potrzebuje, a użytkownikom – kontrolowanie zakresu dostępu, który przyznają aplikacji. Istnieje więc odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika. |
||||||
code_challenge |
Zalecane
Określa zakodowany ciąg |
||||||
code_challenge_method |
Zalecane
Określa metodę, która została użyta do zakodowania parametru |
||||||
state |
Zalecane
Określa dowolną wartość ciągu znaków, której aplikacja używa do utrzymania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.
Serwer zwraca dokładną wartość, którą wysyłasz jako parę Możesz używać tego parametru do różnych celów, takich jak kierowanie użytkownika do odpowiedniego zasobu w aplikacji, wysyłanie liczb jednorazowych i ograniczanie ryzyka sfałszowania żądania z innej witryny. Ponieważ wartość |
||||||
login_hint |
Opcjonalny
Jeśli Twoja aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby przekazać podpowiedź serwerowi uwierzytelniania Google. Serwer używa wskazówki, aby uprościć proces logowania przez wstępne wypełnienie pola z adresem e-mail w formularzu logowania lub wybranie odpowiedniej sesji wielokrotnego logowania. Ustaw wartość parametru na adres e-mail lub identyfikator |
||||||
Przykładowe adresy URL autoryzacji
Na kartach poniżej znajdziesz przykładowe adresy URL autoryzacji dla różnych opcji identyfikatorów URI przekierowania.
Adresy URL są identyczne z wyjątkiem wartości parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id oraz opcjonalny parametr state. Każdy adres URL zawiera podziały wiersza i spacje, aby był bardziej czytelny.
Niestandardowy schemat URI
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Adres IP pętli zwrotnej
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Krok 3. Google prosi użytkownika o zgodę
W tym kroku użytkownik decyduje, czy przyznać aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody, które zawiera nazwę aplikacji i usługi interfejsów API Google, do których aplikacja prosi o dostęp, wraz z danymi uwierzytelniającymi użytkownika i podsumowaniem zakresów dostępu, które mają zostać przyznane. Użytkownik może wtedy wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu, o który prosi aplikacja, lub odrzucić prośbę.
Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź z serwera OAuth 2.0 Google, która wskazuje, czy dostęp został przyznany. Odpowiedź została wyjaśniona w następnym kroku.
Błędy
Żądania wysyłane do punktu końcowego autoryzacji OAuth 2.0 Google mogą wyświetlać komunikaty o błędach dla użytkownika zamiast oczekiwanych procesów uwierzytelniania i autoryzacji. Typowe kody błędów i sugerowane rozwiązania:
admin_policy_enforced
Konto Google nie może autoryzować co najmniej jednego żądanego zakresu ze względu na zasady administratora Google Workspace. Więcej informacji o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów poufnych i ograniczonych, dopóki nie zostanie on wyraźnie przyznany Twojemu identyfikatorowi klienta OAuth, znajdziesz w artykule pomocy dla administratorów Google Workspace Określanie, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace.
disallowed_useragent
Punkt końcowy autoryzacji jest wyświetlany w ramach wbudowanego klienta użytkownika, który jest niedozwolony przez zasady Google dotyczące protokołu OAuth 2.0.
Deweloperzy aplikacji na iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView.
Deweloperzy powinni zamiast tego używać bibliotek iOS, takich jak Logowanie przez Google na iOS lub AppAuth na iOS od OpenID Foundation.
Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy we wbudowanym kliencie użytkownika, a użytkownik przechodzi z Twojej witryny do punktu końcowego autoryzacji protokołu OAuth 2.0 Google. Deweloperzy powinni zezwalać na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który obejmuje zarówno moduły obsługi uniwersalnych linków, jak i domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka SFSafariViewController.
org_internal
Identyfikator klienta OAuth w żądaniu jest częścią projektu, który ogranicza dostęp do kont Google w określonej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji Typ użytkownika w artykule pomocy dotyczącym konfigurowania ekranu zgody OAuth.
deleted_client
Klient OAuth używany do wysyłania żądania został usunięty. Usunięcie może nastąpić ręcznie lub automatycznie w przypadku nieużywanych klientów. Usuniętych klientów można przywrócić w ciągu 30 dni od usunięcia. Więcej informacji
invalid_grant
Jeśli używasz weryfikatora i wyzwania kodu, parametr code_challenge jest nieprawidłowy lub go brakuje. Sprawdź, czy parametr code_challenge jest prawidłowo ustawiony.
Podczas odświeżania tokena dostępu token mógł wygasnąć lub zostać unieważniony. Ponownie uwierzytelnij użytkownika i poproś go o zgodę użytkownika na uzyskanie nowych tokenów. Jeśli ten błąd nadal występuje, sprawdź, czy aplikacja została prawidłowo skonfigurowana i czy w żądaniu używasz prawidłowych tokenów i parametrów. W przeciwnym razie konto użytkownika mogło zostać usunięte lub wyłączone.
redirect_uri_mismatch
Parametr redirect_uri przekazany w żądaniu autoryzacji nie pasuje do autoryzowanego identyfikatora URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania na stronie Klientów w konsoli Google Cloud.
Przekazany parametr redirect_uri może być nieprawidłowy dla typu klienta.
Parametr redirect_uri może odnosić się do procesu OAuth poza pasmem (OOB), który został wycofany i nie jest już obsługiwany. Aby zaktualizować integrację, zapoznaj się z przewodnikiem po migracji.
invalid_request
Wystąpił błąd w Twoim żądaniu. Może to wynikać z kilku powodów:
- Żądanie nie zostało prawidłowo sformatowane.
- W żądaniu brakowało wymaganych parametrów.
- Żądanie używa metody autoryzacji, której Google nie obsługuje. Sprawdzanie, czy integracja OAuth korzysta z zalecanej metody integracji
- W identyfikatorze URI przekierowania użyto nieobsługiwanego schematu niestandardowego. Jeśli pojawi się komunikat o błędzie Niestandardowy schemat URI nie jest obsługiwany w aplikacjach na Androida ani w aplikacjach Chrome, dowiedz się więcej o alternatywach dla niestandardowego schematu URI.
Krok 4. Przetwórz odpowiedź serwera OAuth 2.0
Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacji, zależy od używanego przez nią schematu identyfikatora URI przekierowania. Niezależnie od schematu odpowiedź będzie zawierać kod autoryzacji (code) lub błąd (error). Na przykład error=access_denied oznacza, że użytkownik odrzucił prośbę.
Jeśli użytkownik przyzna dostęp do aplikacji, możesz wymienić kod autoryzacji na token dostępu i token odświeżania, jak opisano w następnym kroku.
Krok 5. Wymień kod autoryzacji na tokeny odświeżania i dostępu
Aby wymienić kod autoryzacji na token dostępu, wywołaj punkt końcowy https://oauth2.googleapis.com/token i ustaw te parametry:
| Pola | |
|---|---|
client_id |
Identyfikator klienta uzyskany na stronie Klienci w konsoli Cloud. |
client_secret |
Opcjonalny
Tajny klucz klienta uzyskany na stronie Klienci w konsoli Cloud. |
code |
Kod autoryzacji zwrócony z początkowego żądania. |
code_verifier |
Weryfikator kodu utworzony w kroku 1. |
grant_type |
Zgodnie ze specyfikacją OAuth 2.0 wartość tego pola musi być ustawiona na authorization_code. |
redirect_uri |
Jeden z identyfikatorów URI przekierowania wymienionych dla Twojego projektu na stronie Klienci w konsoli Cloud dla danego client_id. |
Chociaż użycie DPoP jest opcjonalne, zalecamy je ze względu na zwiększone bezpieczeństwo. Bezpieczeństwo DPoP zależy od tego, czy klucz prywatny jest ograniczony do jednego urządzenia. Zalecamy przechowywanie go w sposób uniemożliwiający skopiowanie poza urządzenie, na przykład przy użyciu modułów TPM, bezpiecznych enklaw lub innych magazynów kluczy wspieranych sprzętowo. Aby korzystać z DPoP, aplikacja musi wygenerować nowy, unikalny token JWT potwierdzający DPoP dla każdego żądania do punktu końcowego tokena i dodać go jako nagłówek żądania HTTP.
| Nagłówek | Wymagane | Opis |
|---|---|---|
DPoP |
Opcjonalny | Dowód DPoP to token JWT, który potwierdza posiadanie klucza prywatnego. To jest nagłówek, a nie parametr. Jeśli go podasz, zwrócone tokeny zostaną powiązane z tym kluczem. Dla każdego żądania należy wygenerować nowy, unikalny dowód, który musi zawierać oświadczenia htm (metoda HTTP) i htu (identyfikator URI HTTP) zgodne z żądaniem. |
Poniższy fragment kodu pokazuje przykładowe żądanie:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiVkM5MXk5WllkZlNXYUR2OEphSTZneDVpZk93MnJuM1lkcWtBQjUxVXU2RSIsInkiOiJpa1BqT3RlYTRrN2ZXUFZyUll3YUE0V3c2aVZZM3BPT0lDb3RId3dHVjNvIn19.eyJqdGkiOiJvMjlDTjhMSVkwbF9OOGl5NS1pbG9uMWd1YWQ5TkZRSEZPZFhUenJCTmNrIiwiaHRtIjoiUE9TVCIsImh0dSI6Imh0dHBzOi8vb2F1dGgyLmdvb2dsZWFwaXMuY29tL3Rva2VuIiwiaWF0IjoxNzg0ODIyMDI1fQ.OSdQCmqTng_uZmGK5UXf8hcEMtoOu7ucmYtl5mx4901RXnj6fJRJQmIeTqfhprRBTG_RSJv2fPcWDqvQbDW7YA code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Tworzenie dowodu DPoP
Poniżej opisujemy, jak utworzyć dowód DPoP za pomocą OpenSSL z wiersza poleceń:
- Wygeneruj parę kluczy EC P-256:
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- Utwórz nagłówek DPoP:
Nagłówek musi zawierać oświadczenia
typ,algijwk(klucz publiczny). Wartościxiyto współrzędne klucza publicznego EC zakodowane w formacie Base64Url. Zakoduj ten obiekt JSON w formacie Base64Url:{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - Utwórz ładunek DPoP:
Ładunek musi zawierać
jti(unikalny identyfikator żądania),htm(metoda HTTP, np.POST),htu(identyfikator URI HTTP, np.https://oauth2.googleapis.com/token) iiat(czas wydania). Jeśli w odpowiedzi na poprzednie żądanie serwer przesłał liczbę jednorazową w nagłówkuDPoP-Nonce, musisz uwzględnić tę wartość w deklaracjinonce. Deklaracja liczby jednorazowej jest opcjonalna w przypadku wymiany kodów autoryzacji i jest używana tylko wtedy, gdy wcześniej otrzymano nagłówek DPoP-Nonce. Zakoduj ten obiekt JSON w formacie Base64Url:{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }Wartość
jtizależy od typu wymiany:- W przypadku wymiany kodów autoryzacji parametr
jtimusi być zakodowanym w formacie Base64Url skrótem SHA256 kodu autoryzacji:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - W przypadku wymiany tokenów odświeżania parametr
jtimusi być unikalnym identyfikatorem żądania:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- W przypadku wymiany kodów autoryzacji parametr
- Podpisywanie dowodu:
Połącz zakodowany nagłówek i ładunek za pomocą kropki (
.), a następnie podpisz wynik kluczem prywatnym za pomocą algorytmu ES256. Pamiętaj, że JWS wymaga, aby podpis był w nieprzetworzonym formacie połączonymR | S(64 bajty dla P-256). Jeśli używasz bezpośrednio OpenSSL, musisz przekonwertować domyślny podpis zakodowany w formacie ASN.1 DER na ten format nieprzetworzony.
Pomyślna wymiana jest sygnalizowana odpowiedzią 200 OK zawierającą tokeny. Jeśli podczas wymiany zostanie użyty prawidłowy dowód DPoP, token odświeżania zwrócony przez Google będzie powiązany z Twoim kluczem za pomocą DPoP, ale tokeny dostępu nie będą powiązane z DPoP. Tokeny dostępu zachowają token_type Bearer, a nie DPoP.
Dodatkowo Google zwraca w odpowiedzi nagłówek HTTP DPoP-Nonce.
Klient musi zapisać tę liczbę jednorazową w pamięci podręcznej i uwzględnić ją w oświadczeniu nonce dowodu DPoP w kolejnych żądaniach (np. podczas wymiany tokena odświeżania na nowy token dostępu lub wywoływania interfejsów API chronionych przez DPoP). Używając tej wcześniej wydanej liczby jednorazowej, możesz uniknąć dodatkowego błędu komunikacji (use_dpop_nonce) przy następnym żądaniu.
W przypadku żądań wymiany tokenów wysyłanych z tokenami odświeżania powiązanymi z DPoP należy dołączyć dowody DPoP.
Nieudana wymiana ma miejsce, gdy nagłówek DPoP jest nieobecny, mimo że jest oczekiwany, jest nieprawidłowy lub gdy dowód używa innego klucza niż ten powiązany z tokenem. W takich przypadkach serwer zwraca błąd 400 Bad Request.
Jeśli dowód DPoP zawiera niezgodne oświadczenia htm lub htu, wygasły parametr iat, nieprawidłowy parametr jti lub nieprawidłowy podpis, Google zwraca kod błędu invalid_dpop_proof.
Jeśli wymagana jest liczba jednorazowa DPoP, np. podczas wymiany tokena odświeżania, a w dowodzie DPoP brakuje deklaracji nonce lub wartość liczby jednorazowej jest nieakceptowalna dla serwera (np. wygasła lub jest nieprawidłowa), Google zwraca kod błędu use_dpop_nonce wraz z nagłówkiem HTTP DPoP-Nonce zawierającym nową liczbę jednorazową, której możesz użyć w kolejnym żądaniu.
Inne błędy mogą zwracać invalid_grant.
Google odpowiada na to żądanie, zwracając obiekt JSON zawierający krótkotrwały token dostępu i token odświeżania.
Odpowiedź zawiera te pola:
| Pola | |
|---|---|
access_token |
Token wysyłany przez aplikację w celu autoryzacji żądania do interfejsu API Google. |
expires_in |
Pozostały czas ważności tokena dostępu w sekundach. |
id_token |
Uwaga: ta właściwość jest zwracana tylko wtedy, gdy żądanie zawiera zakres tożsamości, taki jak openid, profile lub email. Wartością jest token sieciowy JSON (JWT), który zawiera cyfrowo podpisane informacje o tożsamości użytkownika. |
refresh_token |
Token, którego możesz użyć do uzyskania nowego tokena dostępu. Tokeny odświeżania są ważne, dopóki użytkownik nie unieważni dostępu lub token odświeżania nie wygaśnie. Jeśli użyto DPoP, token odświeżania jest powiązany z kluczem prywatnym użytym do podpisania dowodu DPoP. Pamiętaj, że tokeny odświeżania są zawsze zwracane w przypadku zainstalowanych aplikacji. |
refresh_token_expires_in |
Pozostały czas ważności tokena odświeżania w sekundach. Ta wartość jest ustawiana tylko wtedy, gdy użytkownik przyzna dostęp na określony czas. |
scope |
Zakresy dostępu przyznane przez access_token, wyrażone jako lista ciągów znaków rozdzielonych spacjami, z uwzględnieniem wielkości liter. |
token_type |
Typ zwracanego tokena. Ta wartość zawsze wynosi Bearer, nawet gdy używany jest protokół DPoP. |
Poniższy fragment kodu pokazuje przykładowe nagłówki i treść odpowiedzi, gdy używany jest DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Krok 6. Sprawdź, które zakresy przyznali użytkownicy
Gdy poprosisz o kilka uprawnień (zakresów), użytkownicy mogą nie przyznać aplikacji dostępu do wszystkich z nich. Aplikacja musi sprawdzić, które zakresy zostały faktycznie przyznane, i odpowiednio obsłużyć sytuacje, w których niektóre uprawnienia zostały odrzucone, zwykle przez wyłączenie funkcji, które opierają się na tych odrzuconych zakresach.
Są jednak wyjątki. Aplikacje Google Workspace Enterprise z przekazywaniem dostępu w całej domenie lub aplikacje oznaczone jako Zaufane pomijają ekran zgody na uprawnienia szczegółowe. W przypadku tych aplikacji użytkownicy nie zobaczą ekranu zgody na szczegółowe uprawnienia. Zamiast tego aplikacja otrzyma wszystkie żądane zakresy lub nie otrzyma żadnego.
Więcej informacji znajdziesz w artykule Jak postępować z uprawnieniami szczegółowymi.
Aby sprawdzić, czy użytkownik przyznał aplikacji dostęp do określonego zakresu, sprawdź pole scope w odpowiedzi tokena dostępu. Zakresy dostępu przyznane przez parametr access_token, wyrażone jako lista ciągów znaków rozdzielonych spacjami, z uwzględnieniem wielkości liter.
Na przykład ta przykładowa odpowiedź z tokenem dostępu wskazuje, że użytkownik przyznał aplikacji uprawnienia do odczytu aktywności na Dysku i wydarzeń w Kalendarzu:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Wywoływanie interfejsów API Google
Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania interfejsu API Google w imieniu danego konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez interfejs API. Aby to zrobić, dołącz token dostępu do żądania do interfejsu API, podając parametr zapytania access_token lub wartość Bearer nagłówka HTTP Authorization. Jeśli to możliwe, lepiej używać nagłówka HTTP, ponieważ ciągi zapytań są zwykle widoczne w logach serwera. W większości przypadków możesz użyć biblioteki klienta, aby skonfigurować wywołania interfejsów API Google (na przykład podczas wywoływania interfejsu Drive Files API).
Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w OAuth 2.0 Playground.
Przykłady HTTP GET
Wywołanie punktu końcowego
drive.files (interfejs Drive Files API) za pomocą nagłówka HTTP Authorization: Bearer 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 z użyciem parametru ciągu zapytania access_token:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl przykładu
Możesz przetestować te polecenia za pomocą aplikacji wiersza poleceń curl. Oto przykład użycia opcji nagłówka HTTP (preferowanej):
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
Odświeżanie tokena dostępu
Tokeny dostępu okresowo wygasają i stają się nieprawidłowymi danymi logowania w przypadku powiązanego żądania do interfejsu API. Możesz odświeżyć token dostępu bez proszenia użytkownika o zgodę (nawet jeśli użytkownik nie jest obecny), jeśli poprosisz o dostęp offline do zakresów powiązanych z tokenem.
Aby odświeżyć token dostępu, aplikacja wysyła żądanie HTTPS POST do serwera autoryzacji Google (https://oauth2.googleapis.com/token), które zawiera w treści te parametry:
| Nazwa | Wartość |
|---|---|
client_id |
Identyfikator klienta uzyskany z Konsoli interfejsów API. |
client_secret |
Opcjonalny
Tajny klucz klienta uzyskany z Konsoli interfejsów API.
(Parametr |
grant_type |
Zgodnie z definicją w specyfikacji OAuth 2.0 wartość tego pola musi być ustawiona na refresh_token. |
refresh_token |
Token odświeżania zwrócony z wymiany kodu autoryzacji. |
Chociaż użycie DPoP jest opcjonalne, zalecamy je ze względu na zwiększone bezpieczeństwo. Aby używać DPoP z tokenem odświeżania, aplikacja musi wygenerować nowy, unikalny token JWT potwierdzający DPoP dla każdego żądania wysyłanego do punktu końcowego tokena. To potwierdzenie musi być podpisane tym samym kluczem prywatnym, który został użyty podczas początkowej wymiany kodu autoryzacji. Aplikacja dodaje dowód jako nagłówek żądania HTTP.
| Nagłówek | Wymagane | Opis |
|---|---|---|
DPoP |
Opcjonalny | Dowód DPoP to token JWT, który potwierdza posiadanie klucza prywatnego. To jest nagłówek, a nie parametr. Jeśli go podasz, zwrócone tokeny zostaną powiązane z tym kluczem. Dla każdego żądania należy wygenerować nowy, unikalny dowód, który musi zawierać oświadczenia htm (metoda HTTP) i htu (identyfikator URI HTTP) zgodne z żądaniem. |
Poniższy fragment kodu pokazuje przykładowe żądanie:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Aby używać DPoP z tokenem odświeżania, musisz wygenerować nowy, unikalny token JWT potwierdzający DPoP dla żądania. Szczegółowe instrukcje generowania pary kluczy i tworzenia tokena JWT znajdziesz w artykule Tworzenie dowodu DPoP.
Pomyślna wymiana jest sygnalizowana odpowiedzią 200 OK zawierającą nowy token dostępu. Gdy używany jest protokół DPoP, token_type to Bearer. Odpowiedź z powodzeniem potwierdza, że dowód DPoP dla tokena odświeżania został zaakceptowany. Google może też zwrócić w odpowiedzi nowy nagłówek HTTP DPoP-Nonce. Jeśli zostanie zwrócony, klient musi zapisać tę liczbę jednorazową w pamięci podręcznej i uwzględnić ją w oświadczeniu nonce dowodu DPoP w kolejnych żądaniach.
Nieudana wymiana ma miejsce, gdy brakuje nagłówka DPoP, jest on nieprawidłowy lub używa nieprawidłowego klucza. Szczegółowe informacje o konkretnych kodach błędów DPoP i obsłudze liczb jednorazowych znajdziesz w sekcji Nieudana wymiana.
Poniższy fragment kodu pokazuje przykładowe nagłówki i treść odpowiedzi, gdy używany jest DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"token_type": "Bearer"
}Pamiętaj, że istnieją limity liczby tokenów odświeżania, które zostaną wydane: jeden limit na kombinację klienta i użytkownika oraz inny na użytkownika we wszystkich klientach. Tokeny odświeżania należy zapisywać w pamięci długoterminowej i używać ich, dopóki są ważne. Jeśli aplikacja żąda zbyt wielu tokenów odświeżania, może przekroczyć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.
Unieważnienie tokena
W niektórych przypadkach użytkownik może chcieć anulować dostęp przyznany aplikacji. Użytkownik może cofnąć dostęp w ustawieniach konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu witryny lub aplikacji w dokumencie pomocy „Aplikacje i witryny innych firm mające dostęp do Twojego konta”.
Aplikacja może też programowo unieważnić przyznany jej dostęp. Programowe unieważnianie jest ważne w przypadkach, gdy użytkownik anuluje subskrypcję, usunie aplikację lub zasoby interfejsu API wymagane przez aplikację ulegną znacznej zmianie. Innymi słowy, część procesu usuwania może obejmować żądanie do interfejsu API, aby upewnić się, że uprawnienia wcześniej przyznane aplikacji zostały usunięte.
Aby programowo unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i dołącza token jako parametr:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Token może być tokenem dostępu lub tokenem odświeżania. Jeśli token jest tokenem dostępu i ma odpowiadający mu token odświeżania, token odświeżania również zostanie unieważniony.
Jeśli unieważnienie zostanie przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędów zwracany jest kod stanu HTTP 400 wraz z kodem błędu.
Metody przekierowania do aplikacji
Niestandardowy schemat URI
Niestandardowe schematy URI to forma precyzyjnych linków, które używają niestandardowego schematu do otwierania aplikacji.
Alternatywa dla niestandardowych schematów URI w aplikacjach Chrome
Użyj interfejsu Chrome Identity API, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując potrzebę używania identyfikatora URI przekierowania.
Adres IP pętli zwrotnej (macOS, Linux, Windows na komputerze)
Aby otrzymać kod autoryzacji za pomocą tego adresu URL, aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach, ale nie na wszystkich. Jeśli jednak Twoja platforma obsługuje tę metodę, jest to zalecany sposób uzyskiwania kodu autoryzacji.
Gdy aplikacja otrzyma odpowiedź autoryzacyjną, dla najlepszej użyteczności powinna wyświetlić stronę HTML z instrukcją, aby użytkownik zamknął przeglądarkę i wrócił do aplikacji.
| Zalecane użycie | aplikacje komputerowe na systemy macOS, Linux i Windows; |
| Wartości formularza | Jako typ aplikacji wybierz Aplikacja komputerowa. |
Ręczne kopiowanie i wklejanie (wycofane)
Ochrona aplikacji
Potwierdzanie własności aplikacji w Chrome
Możesz potwierdzić własność aplikacji, aby zmniejszyć ryzyko podszywania się pod nią.
Aby dokończyć proces weryfikacji, użyj konta dewelopera w Chrome Web Store. Aby weryfikacja przebiegła pomyślnie, muszą zostać spełnione te wymagania:
- Musisz mieć zarejestrowany produkt w Panelu dewelopera Chrome Web Store o tym samym identyfikatorze produktu co klient OAuth rozszerzenia do Chrome, którego dotyczy weryfikacja.
- Musisz być wydawcą produktu w Chrome Web Store. Więcej informacji o zarządzaniu dostępem w Panelu dewelopera Chrome Web Store.
W sekcji Weryfikacja własności aplikacji klienta rozszerzenia do Chrome kliknij przycisk Potwierdź własność, aby zakończyć proces weryfikacji.
Uwaga: po przyznaniu dostępu do konta odczekaj kilka minut, zanim przejdziesz proces weryfikacji.
Jeśli weryfikacja się powiedzie, wyświetli się powiadomienie z potwierdzeniem pomyślnego zakończenia procesu weryfikacji. W przeciwnym razie pojawi się komunikat o błędzie.
Jeśli weryfikacja się nie powiedzie, wykonaj te czynności:
- Upewnij się, że w panelu dewelopera Chrome Web Store jest zarejestrowany element o tym samym identyfikatorze produktu co klient OAuth rozszerzenia do Chrome, którego dotyczy weryfikacja.
- Upewnij się, że jesteś wydawcą aplikacji, czyli wydawcą indywidualnym lub członkiem wydawcy grupowego aplikacji. Dowiedz się więcej o zarządzaniu dostępem w Panelu dewelopera Chrome Web Store.
- Jeśli lista wydawców grupy została właśnie zaktualizowana, sprawdź, czy lista członków grupy wydawców jest zsynchronizowana w panelu dewelopera Chrome Web Store. Dowiedz się więcej o synchronizowaniu listy subskrybentów wydawcy.
Dostęp zależny od czasu
Dostęp czasowy umożliwia użytkownikowi przyznanie aplikacji dostępu do jego danych na ograniczony czas w celu wykonania działania. Dostęp czasowy jest dostępny w wybranych usługach Google podczas procesu wyrażania zgody, co daje użytkownikom możliwość przyznania dostępu na ograniczony czas. Przykładem jest interfejs Data Portability API, który umożliwia jednorazowe przeniesienie danych.
Gdy użytkownik przyzna Twojej aplikacji dostęp na określony czas, token odświeżania wygaśnie po upływie tego czasu. Pamiętaj, że w określonych okolicznościach tokeny odświeżania mogą zostać unieważnione wcześniej. Szczegółowe informacje znajdziesz w tych przypadkach. W takich przypadkach pole refresh_token_expires_in zwracane w odpowiedzi na wymianę kodu autoryzacji reprezentuje czas pozostały do wygaśnięcia tokena odświeżania.
Więcej informacji
Wiele sprawdzonych metod opisanych w tym dokumencie zostało określonych w dokumencie IETF Best Current Practice OAuth 2.0 for Native Apps (OAuth 2.0 dla aplikacji natywnych).
Wdrażanie ochrony wszystkich kont
Dodatkowym krokiem, który należy podjąć, aby chronić konta użytkowników, jest wdrożenie ochrony wszystkich kont za pomocą usługi ochrony wszystkich kont Google. Ta usługa umożliwia subskrybowanie powiadomień o zdarzeniach związanych z bezpieczeństwem, które dostarczają aplikacji informacji o ważnych zmianach na koncie użytkownika. Możesz następnie wykorzystać te informacje, aby podjąć działania w zależności od tego, jak chcesz zareagować 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
Więcej informacji o wdrażaniu ochrony wszystkich kont oraz pełną listę dostępnych zdarzeń znajdziesz na stronie Chroń konta użytkowników za pomocą ochrony wszystkich kont .