OAuth 2.0 dla aplikacji mobilnych i komputerowych

Ten dokument wyjaśnia, w jaki sposób aplikacje zainstalowane na urządzeniach, takich jak telefony, tablety i komputery, wykorzystują punkty końcowe 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, a jednocześnie chroni ich nazwy użytkowników, hasła i inne informacje. Aplikacja może na przykład używać protokołu OAuth 2.0 do uzyskiwania od użytkowników uprawnień do przechowywania plików na Dyskach Google.

Zainstalowane aplikacje są rozpowszechniane na poszczególnych urządzeniach i zakładamy, że nie mogą one być tajne. Mają dostęp do interfejsów API Google, gdy użytkownik jest obecny w aplikacji lub gdy działa w tle.

Ten proces autoryzacji jest podobny do procesu aplikacji serwera WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otworzyć przeglądarkę systemową i podać lokalny identyfikator URI przekierowania, aby obsługiwać odpowiedzi z serwera autoryzacji Google.

Alternatywy

W przypadku aplikacji mobilnych zalecamy korzystanie z logowania przez Google na Androidzie lub iOS. Biblioteki klienta logowania przez Google obsługują uwierzytelnianie i autoryzację użytkowników. Ich implementacja może być prostsza niż opisanych poniżej protokołu.

W przypadku aplikacji działających na urządzeniach, które nie obsługują przeglądarki systemowej lub mających ograniczone funkcje wejściowe (np. telewizory, konsole do gier, kamery czy drukarki), przeczytaj artykuł OAuth 2.0 dla telewizorów i urządzeń lub Logowanie się na telewizorach i urządzeniach z ograniczonym dostępem.

Biblioteki i próbki

Zalecamy skorzystanie z tych bibliotek i przykładów, które pomogą Ci wdrożyć procedurę OAuth 2.0 opisaną w tym dokumencie:

• Biblioteka AppAuth na Androida
• Biblioteka AppAuth na iOS
• OAuth dla aplikacji: przykłady w systemie Windows

Wymagania wstępne

Włącz interfejsy API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć je w API Console.

Aby włączyć interfejs API w projekcie:

1. Open the API Library w: Google API Console.
2. If prompted, select a project, or create a new one.
3. Na liście API Library znajdują się wszystkie dostępne interfejsy API pogrupowane według rodziny usług i popularności. Jeśli interfejsu API, który chcesz włączyć, nie ma na liście, użyj wyszukiwarki, aby go znaleźć, lub kliknij Wyświetl wszystkie w rodzinie usług, do której należy.
4. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Tworzenie danych logowania

Każda aplikacja, która używa OAuth 2.0 do korzystania z 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 w Twoim projekcie. Twoje aplikacje mogą następnie używać danych logowania do uzyskiwania dostępu do interfejsów API włączonych w tym projekcie.

1. Go to the Credentials page.
2. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
3. Sekcje poniżej opisują typy klientów i metody przekierowania obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nazwij swojego klienta OAuth i ustaw odpowiednio inne pola w formularzu.

Określ zakresy dostępu

Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, jednocześnie umożliwiając użytkownikom kontrolę nad poziomem dostępu, który przyznają aplikacji. W związku z tym może wystąpić 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ć dostępu.

Dokument Zakresy OAuth 2.0 API 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 znajdziesz opis interakcji Twojej aplikacji z serwerem OAuth 2.0 Google w celu uzyskania zgody użytkownika na przesłanie żądania do interfejsu API w jego imieniu. Aplikacja musi mieć tę zgodę, zanim będzie mogła wykonać żądanie interfejsu API Google, które wymaga autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikatora kodu i wyzwanie

Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo zainstalowanej aplikacji. Dla każdego żądania autoryzacji tworzony jest unikalny weryfikator kodów, a jego wartość przekształcona o nazwie „code_challenge” jest wysyłana do serwera autoryzacji w celu uzyskania kodu autoryzacji.

Tworzenie weryfikatora kodu

code_verifier to entropijny ciąg kryptograficzny składający się z losowych znaków [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", o minimalnej długości 43 znaków i maksymalnie 128 znaków.

Weryfikator kodu powinien mieć wystarczająco dużo entropii, aby nie mógł odgadnąć wartości.

Tworzenie testu zabezpieczającego kod

Obsługiwane są 2 metody tworzenia kodu zabezpieczającego.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

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 w aktywnej sesji, uwierzytelnia użytkownika i uzyskuje zgodę użytkownika. Punkt końcowy jest dostępny tylko przez SSL i odrzuca połączenia HTTP (bez SSL).

Serwer autoryzacji obsługuje te parametry ciągu zapytania w przypadku zainstalowanych aplikacji:

Przykładowe adresy URL autoryzacji

Poniższe karty pokazują przykładowe adresy URL autoryzacji dla różnych opcji identyfikatora URI przekierowania.

Adresy URL są identyczne z wartością parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id, a także opcjonalny parametr state. Każdy URL zawiera podziały wierszy i spacje, aby zwiększyć ich czytelność.

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

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 wymagane uprawnienia dostępu. Na tym etapie Google wyświetla okno z prośbą o zgodę na wykorzystanie danych zawierające nazwę aplikacji i usług interfejsu API Google, do których prosi się o dostęp, podając dane logowania użytkownika, a także podsumowanie zakresów dostępu. Użytkownik może następnie udzielić dostępu do co najmniej 1 zakresu zgłoszonego przez aplikację lub odrzucić prośbę.

Twoja aplikacja nie musi nic robić na tym etapie, ponieważ czeka na odpowiedź serwera OAuth 2.0 Google, a następnie wskazuje, czy przyznano dostęp. Tę odpowiedź wyjaśniamy w następnym kroku.

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacyjną, zależy od wykorzystywanego 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 wskazuje, że użytkownik odrzucił żądanie.

Jeśli użytkownik przyzna Twojej aplikacji dostęp, możesz wymienić kod autoryzacji dla tokena dostępu i tokena odświeżania zgodnie z opisem w następnym kroku.

Krok 5. Wymień kod autoryzacji na tokeny odświeżania i dostępu

Aby wymienić kod autoryzacji tokena dostępu, wywołaj punkt końcowy https://oauth2.googleapis.com/token i ustaw te parametry:

Ten fragment zawiera przykładowe żądanie:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

W odpowiedzi na to żądanie Google zwraca obiekt JSON zawierający token dostępu przez krótki czas i token odświeżania.

Odpowiedź zawiera następujące pola:

Ten fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Wywoływanie interfejsów API Google

Gdy aplikacja otrzyma token dostępu, możesz go używać do wywoływania interfejsu Google API w imieniu danego konta użytkownika, jeśli zakresy dostępu wymagane przez ten interfejs API zostały przyznane. W tym celu umieść w żądaniu żądanie do interfejsu API token dostępu, podając w zapytaniu parametr access_token lub wartość nagłówka HTTP Authorization Bearer. W miarę możliwości zalecamy używanie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków możesz użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (np. podczas wywoływania interfejsu Drive Files API).

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w Play 2.0 Playground.

Przykłady HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) przy użyciu nagłówka HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz określić własny token dostępu:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API uwierzytelnionego użytkownika używającego parametru ciągu zapytania access_token:

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

Przykłady zapytań z operatorem curl

Te polecenia możesz przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład użycia opcji nagłówka HTTP (zalecane):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Możesz też użyć opcji parametru ciągu zapytania:

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

Odświeżanie tokena dostępu

Tokeny dostępu okresowo tracą ważność i stają się nieprawidłowe dane logowania dla powiązanego żądania interfejsu API. Jeśli prośba o dostęp offline do zakresów powiązanych z tokenem została wysłana, możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (także wtedy, gdy go nie ma).

Aby odświeżyć token dostępu, aplikacja wysyła żądanie HTTPS POST do serwera autoryzacji Google (https://oauth2.googleapis.com/token), który zawiera te parametry:

Ten fragment zawiera przykładowe żądanie:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Dopóki użytkownik nie unieważni dostępu przyznanego aplikacji, serwer tokenów zwróci obiekt JSON zawierający nowy token dostępu. Ten fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Istnieją limity liczby tokenów odświeżania: jeden limit dla każdej kombinacji klienta i użytkownika i jeden dla każdego klienta. Tokeny odświeżania należy zapisywać w pamięci długoterminowej i używać ich tak długo, jak długo są ważne. Jeśli aplikacja poprosi o zbyt wiele tokenów odświeżania, może dojść do tych limitów. W takim przypadku starsze tokeny odświeżania przestaną działać.

Unieważnianie tokena

W niektórych przypadkach użytkownik może odwołać dostęp do aplikacji. Użytkownik może cofnąć dostęp, korzystając z ustawień konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu witryn lub aplikacji do stron i aplikacji innych firm z dostępem do Twojego konta.

Aplikacja może też automatycznie anulować przyznany jej dostęp. Automatyczne unieważnienie jest ważne wtedy, gdy użytkownik anuluje subskrypcję, usunie aplikację lub zmienią się zasoby interfejsu API wymagane przez aplikację. Inaczej mówiąc, część procesu usuwania może obejmować żądanie do interfejsu API, aby zapewnić uprawnienia przyznane wcześniej aplikacji.

Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i zawiera token jako parametr:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Może to być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma odpowiedni token odświeżania, zostanie on też unieważniony.

Jeśli odwołanie zostało przetworzone, kod stanu HTTP odpowiedzi będzie miał wartość 200. W przypadku warunków błędu zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

Więcej informacji

Sprawdzone metody IETF (OAuth 2.0 for Native Apps) uwzględniają wiele sprawdzonych metod opisanych tutaj.