Ta strona została przetłumaczona przez Cloud Translation API.

Korzystanie z OAuth z interfejsami API danych Google

Eric Bidelman, zespół Google Data API
wrzesień 2008 r.

Wprowadzenie

To ekscytujący czas dla deweloperów. W internecie zaczynamy stosować szereg standardów otwartych. Jak wiesz, Google stale faworyzuje standardy i pielęgnuje społeczność open source.

Niedawno wszystkie interfejsy API danych Google przyjęły otwarty protokół OAuth, który ma ustandaryzować sposób, w jaki aplikacje internetowe i aplikacje internetowe uzyskują dostęp do prywatnych danych użytkownika. Protokół OAuth umożliwia przeprowadzenie uwierzytelniania API w standardowy i bezpieczny sposób. Jako deweloperzy uczymy się wykorzystywać kod w miarę możliwości. Protokół OAuth ułatwia programistom zmniejszenie ilości powtarzającego się kodu i ułatwia tworzenie narzędzi, które współpracują z wieloma usługami różnych dostawców.

Odbiorcy

W tym artykule zakładamy, że znasz co najmniej jeden interfejs API danych Google, ale niekoniecznie pojęcia związane z OAuth. Jeśli dopiero zaczynasz korzystać z protokołu OAuth lub chcesz się po prostu dowiedzieć, więcej na ten temat nie ma. W tym artykule znajdziesz podstawowe informacje na ten temat. Omówię też szczegóły implementacji protokołu OAuth w Google.

Ten dokument jest też przeznaczony dla programistów, którzy potrafią korzystać z AuthSub, szczególnie w trybie zarejestrowanym w trybie zwiększonego bezpieczeństwa. W tym miejscu spróbuję podkreślić podobieństwa i różnice między nimi. Jeśli masz aplikacje korzystające z AuthSub, możesz wykorzystać te informacje do przejścia na protokół OAuth, który jest bardziej otwartym i nowoczesnym protokołem.

Trochę terminologia

Znajomość protokołu OAuth polega na poznaniu jego terminologii. Specyfikacja OAuth i dokumentacja uwierzytelniania OAuth w aplikacjach internetowych Google w znacznym stopniu bazują na niektórych definicjach, więc wyjaśnijmy ich znaczenie w kontekście implementacji Google OAuth.

„Taniec OAuth”
Mój nieoficjalny termin opisujący pełny proces uwierzytelniania/autoryzacji OAuth.
(OAuth) Token żądania
Wstępny token informujący Google, że prosi o dostęp do jednego z interfejsów API danych Google. Drugim etapem implementacji protokołu OAuth jest zapewnienie przez użytkownika ręcznego dostępu do jego danych. Jeśli ten krok się powiedzie, token żądania stanie się autoryzowany.
(OAuth) Token dostępu
Ostatnim etapem tańca jest wymiana autoryzowanego tokena żądania na token dostępu. Gdy aplikacja zdobędzie ten token, użytkownik nie będzie musiał ponownie tańczyć OAuth, chyba że token zostanie unieważniony.

Podobieństwo do AuthSub:
Token dostępu OAuth to to samo co bezpieczny token sesji AuthSub.

(OAuth) Punkty końcowe

To identyfikatory URI niezbędne do uwierzytelniania aplikacji i uzyskania tokena dostępu. Istnieją 3 warunki – po jednym dla każdego kroku w procesie OAuth. Punkty końcowe Google OAuth:

Uzyskiwanie tokena żądania:	`https://www.google.com/accounts/OAuthGetRequestToken`
Autoryzuj token żądania:	`https://www.google.com/accounts/OAuthAuthorizeToken`
Przejdź na token dostępu:	`https://www.google.com/accounts/OAuthGetAccessToken`

Podobieństwo do AuthSub:
Wymiana autoryzowanego tokena żądania tokena dostępu jest analogiczna do uaktualnienia tokena jednorazowego tokena AuthSub odpowiednio do https://www.google.com/accounts/AuthSubRequestToken i https://www.google.com/accounts/AuthSubSessionToken. Różnica polega na tym, że w tokenie AuthSub nie ma koncepcji początkowego tokena żądania. Zamiast tego użytkownik rozpoczyna proces tokena na stronie autoryzacji AuthSubRequestToken.

Dostawca usług OAuth
W przypadku interfejsów API danych Google dostawcą jest firma Google. Ogólnie dostawca usług określa witrynę lub usługę internetową, która udostępnia punkty końcowe OAuth. Innym przykładem dostawcy usługi OAuth jest MySpace.
(OAuth) Konsument
Program żądający uprawnień dostępu do danych użytkownika (czyli aplikacji). Protokół OAuth jest elastyczny, ponieważ umożliwia obsługę wielu różnych typów klientów (internetowych, zainstalowanych, stacjonarnych i mobilnych).

Uwaga: chociaż protokół OAuth obsługuje przypadki użycia aplikacji na komputery i zainstalowane aplikacje, obsługuje je tylko w przypadku aplikacji internetowych.

Pierwsze kroki

Rejestracja

Zanim zaczniesz korzystać z protokołu OAuth za pomocą interfejsów API danych Google, musisz przeprowadzić niewielką konfigurację. Ponieważ wszystkie żądania OAuth muszą być podpisane cyfrowo, musisz najpierw zarejestrować swoją domenę i przesłać publiczny certyfikat do Google. Więcej informacji na ten temat znajdziesz w artykułach Rejestracja w aplikacjach internetowych oraz Generowanie kluczy i certyfikatów do użytku w trybie zarejestrowanym.

Prośby o podpis

Po zarejestrowaniu domeny możesz rozpocząć podpisywanie żądań. Jednym z najtrudniejszych aspektów protokołu OAuth jest poprawne skonstruowanie tagu oauth_signature i ciągu tekstowego podpisu podstawowego. Ciąg bazowy to dane, które podpisujesz kluczem prywatnym (za pomocą RSA_SHA1). Wynikiem jest wartość ustawiona dla oauth_signature.

Przykładowe żądanie

GET listę kalendarzy Google użytkownika http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

Podstawowy format ciągu znaków	`base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters`
Przykładowy ciąg podstawowy	`GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime`
Przykładowe żądanie HTTP	GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Uwaga: należy tylko reprezentować użytkownika. oauth_signature będzie znacznie dłuższy.

Uwagi dotyczące ciągu bazowego:

Parametr zapytania orderby=starttime jest sortowany wraz z pozostałymi parametrami oauth_* w kolejności leksykograficznej bajtów.
Ten ciąg nie zawiera znaku „?”
Część base-http-request-url zawiera tylko podstawowy adres URL zakodowany w adresie URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
oauth_token jest podwójnie zakodowany.

Uwagi w nagłówku Authorization:

Kolejność parametrów oauth_* nie ma znaczenia w nagłówku Authorization.
Nagłówek nie zawiera ciągu orderby=starttime, tak jak w przypadku ciągu bazowego. Ten parametr zapytania jest częścią adresu URL żądania.

Więcej informacji o podpisywaniu żądań przez OAuth znajdziesz w artykule Podpisywanie żądań OAuth.

Różnica względem AuthSub:
W przykładach porównawczych użycie bezpiecznego protokołu AuthSub to:

Podstawowy format ciągu znaków base_string = http-method http-request-URL timestamp nonce

Przykładowy ciąg podstawowy

Podstawowy format ciągu znaków	`base_string = http-method http-request-URL timestamp nonce`
Przykładowy ciąg podstawowy	GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Przykładowe żądanie HTTP	GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d

Przykładowe żądanie HTTP

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Więcej informacji o podpisywaniu żądań przy użyciu AuthSub znajdziesz w artykule Podpisywanie żądań AuthSub.

Narzędzie OAuth Playground

Wypróbuj!

Cel

Niektórzy użytkownicy sugerują, że protokół OAuth ma wysoką krzywą uczenia się. W porównaniu z innymi interfejsami API do uwierzytelniania Google Zaleta protokołu OAuth będzie widoczna po rozwinięciu aplikacji, tak aby korzystały z innych usług firm innych niż Google. Pisanie w chmurze kodu, który sprawdza się u różnych dostawców usług, i ich interfejsy API wydaje mi się bardzo przydatne. Podziękujesz później za naukę korzystania z tego protokołu.

OAuth Playground to narzędzie, które utworzyliśmy, aby pomóc deweloperom naprawić problemy OAuth. Możesz korzystać z Playground, aby łatwiej rozwiązywać problemy, sprawdzać własną implementację lub eksperymentować z interfejsami API danych Google.

Na czym to polega?

Ilustruje proces uwierzytelniania OAuth: pobieranie tokena żądania, autoryzację go i przekształcanie w token dostępu.
Wyświetla prawidłowy ciąg podstawowy podpisu dla każdego żądania.
Wyświetla prawidłowy nagłówek Authorization każdego żądania.
Pokazuje, jak używać oauth_token do interakcji z uwierzytelnionym plikiem danych Google. Dane: GET/POST/PUT/DELETE.
Uwierzytelnić kanał bezpośrednio w przeglądarce.
Umożliwia przetestowanie własnego oauth_consumer_key (zarejestrowanej domeny) i klucza prywatnego.
Sprawdź, jakie usługi danych Google są dostępne na urządzeniu oauth_token.

Uruchomiono wersję demonstracyjną

Krok 1. Wybierz zakresy Najpierw zdecyduj, których interfejsów API chcesz używać, wybierając co najmniej 1 zakres. W tym przykładzie żądam tokena, który będzie działał z Bloggerem i Kontaktami Google. Podobieństwo do AuthSub: AuthSub wymaga też parametru `scope`, aby kontrolować zakres danych, do których token ma dostęp. Parametr ten został zaimplementowany przez Google w sposób podany w specyfikacji OAuth.
Krok 2. Zmień parametry i ustawienia OAuth Na razie nie zmieniaj żadnych ustawień w polu „Zmodyfikuj parametry OAuth”. Później możesz przeprowadzić test z użyciem własnego klucza prywatnego, zmieniając `oauth_consumer_key` na zarejestrowaną domenę i wpisując klucz prywatny, klikając „Użyj własnego klucza prywatnego”. Używaj tylko klucza prywatnego TEST. Uwaga: `oauth_signature_method` i `oauth_consumer_key` to jedyne pola, które można tu edytować. `oauth_timestamp`, `oauth_nonce` i `oauth_token` zostaną wygenerowane automatycznie. Oprócz `RSA-SHA1` możesz używać `HMAC-SHA1` jako `oauth_signature_method`. W takim przypadku w Playground będą widoczne dodatkowe pola, w których będzie trzeba wpisać własny `oauth_consumer_key` i tajny klucz klienta. Te wartości możesz znaleźć na stronie https://www.google.com/accounts/ManageDomains zarejestrowanej domeny. Różnica od AuthSub: W bezpiecznym AuthSub nie ma parametru, który mógłby jednoznacznie określić nazwę domeny. Domena jest częścią parametru adresu URL `next`. W OAuth jest taki parametr: `oauth_consumer_key`. Ustaw ją na zarejestrowaną.
Krok 3–5. Uzyskaj token dostępu Aby uzyskać token dostępu OAuth, musisz wykonać 3 kroki. Pierwszym krokiem jest pobranie tokena żądania. Dzięki temu Google wie, że aplikacja rozpoczyna taniec OAuth. Najpierw w polu „Pobierz token” kliknij przycisk „Poproś o token”. Niektóre pola zostaną wypełnione danymi. W polu „Ciąg bazowy podpisu” wyświetlana jest prawidłowa postać ciągu bazowego użytego do utworzenia parametru `oauth_signature`. W sekcji „Nagłówek autoryzacji” wyświetla się odpowiedni nagłówek żądania `Authorization`. Pole „Zmodyfikuj parametry OAuth” wypełnione przez wartości `oauth_nonce` i `oauth_timestamp` wysłane w żądaniu. Dane wejściowe `oauth_token` zostały wypełnione odpowiednią wartością zwracaną w treści odpowiedzi. Playground pokazuje też obecny typ `oauth_token`. W tej chwili jest to token żądania.
Następnie w polu „Uzyskaj token” kliknij przycisk „Autoryzuj”. Na tej stronie autoryzacji kliknij przycisk „Przyznaj dostęp”, aby autoryzować token żądania i powrócić do OAuth OAuthground. Podobieństwo do AuthSub: Ta strona autoryzacji jest taka sama w przypadku AuthSub. Różnica od wartości AuthSub: Parametr adresu URL `next` w AuthSub jest podobny do parametru `oauth_callback`. Różnica polega na tym, że w protokole OAuth właściwość `oauth_callback` jest opcjonalna. Gdy użytkownik kliknie przycisk „Przyznaj dostęp”, token żądania zostanie autoryzowany, a token można uaktualnić do `https://www.google.com/accounts/OAuthGetAccessToken`. Wskazówka: określenie adresu URL `oauth_callback` jest preferowane, jeśli tworzysz aplikację internetową, ponieważ zwiększa to wygodę użytkowników.
Na koniec kliknij przycisk „Token dostępu” w polu „Uzyskaj token”. To działanie uaktualnia autoryzowany token żądania (jak wskazuje czerwona etykieta „token dostępu”). Jeśli chcesz pobrać nowy token, kliknij „Zacznij od nowa”, aby ponownie rozpocząć taniec OAuth. Teraz możemy zrobić coś ciekawego.

Używanie tokena dostępu

Teraz możesz przesyłać zapytania dotyczące kanałów, wstawiać, aktualizować i usuwać dane. Zwróć uwagę na działanie tych 3 ostatnich metod HTTP, gdy pracujesz z rzeczywistymi danymi.

Wskazówka: aby znaleźć kanały dostępne dla Twojego tokena dostępu, kliknij przycisk „Dostępne pliki danych”.

Przykładowe zapytanie: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Ten przykład zwraca nie więcej niż 3 posty na danym blogu. Zwrócony kanał/wpis można też wyświetlić bezpośrednio w przeglądarce, klikając link „Wyświetl w przeglądarce” pod zaznaczonym obszarem składni.

Przykład: jak zaktualizować post

Znajdź element <link> z elementem rel="edit" w poście, który chcesz zaktualizować. Powinien wyglądać mniej więcej tak:
```
<link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>
```
Wklej URL href w polu „Wpisz plik danych Google”.
Skopiuj kod XML istniejącego wpisu, klikając „Wyświetl zwykły” u góry panelu podświetlonego składni. Skopiuj tylko treść odpowiedzi – nie nagłówki.
Zmień opcję metody HTTP na PUT.
Kliknij „wpisz dane posta” pod tym menu i wklej kod XML aplikacji <entry> w wyskakującym okienku.
Kliknij przycisk „Wykonaj”.

Serwer odpowie 200 OK.

Wskazówka: zamiast ręcznie kopiować link do pliku edit, odznacz pole wyboru „Składnia podświetlenia?”. Po wykonaniu zapytania możesz kliknąć linki w treściach odpowiedzi XML.

Podsumowanie

Technologie takie jak AtomPub/Atom Publishing Protocol (protokół bazowy interfejsów Google Data API) i OAuth przyczyniają się do rozwoju internetu. Coraz więcej witryn przestrzega tych standardów i wygrywamy więc deweloperów. Tworzenie aplikacji dla zabójców nagle staje się mniej trudne.

Jeśli masz pytania lub uwagi dotyczące protokołu OAuth w Playground lub używasz protokołu OAuth w połączeniu z interfejsami API Google, odwiedź nasze forum pomocy dotyczące interfejsów API G Suite i Marketplace.