Używanie protokołu OAuth z interfejsami Google Data API

Wprowadzenie

To ekscytujący czas dla deweloperów. W internecie zaczyna się pojawiać coraz więcej otwartych standardów. Jak wiesz, Google zawsze było wielkim zwolennikiem standardów i wspierania społeczności open source.

Niedawno wszystkie interfejsy Google Data API zaczęły obsługiwać OAuth, otwarty protokół, który ma na celu ujednolicenie sposobu, w jaki aplikacje na komputery i w internecie uzyskują dostęp do prywatnych danych użytkownika. OAuth umożliwia uwierzytelnianie interfejsu API w standardowy i bezpieczny sposób. Jako programiści uczymy się, że w miarę możliwości należy ponownie wykorzystywać kod. OAuth pomoże deweloperom ograniczyć ilość powielanego kodu i ułatwi tworzenie narzędzi, które działają z wieloma usługami różnych dostawców.

Odbiorcy

W tym artykule zakładamy, że znasz co najmniej jeden z interfejsów Google Data API, ale niekoniecznie pojęcia związane z OAuth. Jeśli dopiero zaczynasz lub po prostu interesujesz się OAuth, nie musisz szukać dalej. W tym artykule znajdziesz podstawowe informacje o tych pojęciach. Omówię też szczegóły implementacji protokołu OAuth w Google.

Ten dokument jest również przeznaczony dla deweloperów, którzy znają AuthSub, zwłaszcza w trybie zarejestrowanym z rozszerzonymi zabezpieczeniami. W trakcie prezentacji będę zwracać uwagę na podobieństwa i różnice między tymi dwoma protokołami. Jeśli masz aplikacje, które korzystają z AuthSub, możesz użyć tych informacji, aby przeprowadzić migrację do OAuth, czyli bardziej otwartego i nowoczesnego protokołu.

Trochę terminologii

Aby zrozumieć OAuth, musisz poznać jego terminologię. Specyfikacja OAuth i dokumentacja Google Uwierzytelnianie OAuth w aplikacjach internetowych w dużej mierze opierają się na określonych definicjach, dlatego wyjaśnimy, co każda z nich oznacza w kontekście implementacji OAuth w Google.

1. „Proces OAuth”

   Nieoficjalne określenie pełnego procesu uwierzytelniania i autoryzacji OAuth.

2. (OAuth) Poproś o token

   Początkowy token, który informuje Google, że Twoja aplikacja prosi o dostęp do jednego z interfejsów Google Data API. Drugi etap procesu OAuth polega na ręcznym przyznaniu dostępu do danych. Jeśli ten krok się powiedzie, token żądania zostanie autoryzowany.

3. Token dostępu (OAuth)

   Ostatnim krokiem jest wymiana autoryzowanego tokena żądania na token dostępu. Gdy aplikacja otrzyma ten token, użytkownik nie będzie musiał ponownie przechodzić procesu autoryzacji OAuth, chyba że token zostanie unieważniony.

   Podobieństwo do AuthSub:
   Token dostępu OAuth jest tym samym co bezpieczny token sesji AuthSub.

4. Punkty końcowe (OAuth)

   Są to identyfikatory URI wymagane do uwierzytelnienia aplikacji i uzyskania tokena dostępu. Łącznie są 3 – po jednym na każdy etap procesu OAuth. Punkty końcowe OAuth Google to:

   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 na token dostępu jest analogiczna do przekształcenia jednorazowego tokena AuthSub w długotrwały token sesji odpowiednio w przypadku https://www.google.com/accounts/AuthSubRequestToken i https://www.google.com/accounts/AuthSubSessionToken. Różnica polega na tym, że AuthSub nie ma koncepcji początkowego tokena żądania. Zamiast tego użytkownik rozpoczyna proces tokena na AuthSubRequestTokenstronie autoryzacji.

5. Dostawca usług (OAuth)

   W przypadku interfejsów Google Data API tym dostawcą jest Google. Ogólnie rzecz biorąc, dostawca usług to witryna lub usługa internetowa, która udostępnia punkty końcowe OAuth. Innym przykładem dostawcy usług OAuth jest MySpace.

6. (OAuth) Konsument

   Program, który prosi o dostęp do danych użytkownika (czyli Twoja aplikacja). Protokół OAuth jest elastyczny, ponieważ umożliwia korzystanie z wielu różnych typów klientów (internetowych, zainstalowanych, na komputery, mobilnych).

Uwaga: chociaż protokół OAuth obsługuje przypadek użycia aplikacji na komputery lub zainstalowanych, Google obsługuje OAuth tylko w przypadku aplikacji internetowych.

Pierwsze kroki

Rejestracja

Zanim zaczniesz używać OAuth z interfejsami Google Data API, musisz wykonać kilka czynności konfiguracyjnych. Ponieważ wszystkie żądania OAuth muszą być podpisane cyfrowo, najpierw musisz zarejestrować domenę i przesłać do Google certyfikat publiczny. Więcej informacji o tym, jak to zrobić, znajdziesz w artykułach Rejestracja aplikacji internetowych i Generowanie kluczy i certyfikatów do użycia w trybie zarejestrowanym.

Prośby o podpisanie

Po zarejestrowaniu domeny możesz zacząć podpisywać żądania. Jednym z najtrudniejszych aspektów protokołu OAuth jest prawidłowe tworzenie oauth_signature i pojęcie ciągu bazowego podpisu. Ciąg podstawowy to dane, które podpisujesz kluczem prywatnym (za pomocą RSA_SHA1). Wynikiem jest wartość, którą ustawiasz dla parametru oauth_signature.

Przykładowe żądanie

GET lista kalendarzy Google użytkownika na stronie http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime;

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: to tylko przykład. 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 porządku leksykograficznym wartości bajtów.
• Ten ciąg nie zawiera też znaku „?”.
• Część base-http-request-url zawiera tylko zakodowany adres URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
• Parametr oauth_token jest dwukrotnie zakodowany w adresie URL.

Uwagi dotyczące nagłówka Authorization:

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

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

Różnica w porównaniu z AuthSub:
Dla porównania podajemy ten sam przykład z użyciem bezpiecznego AuthSub:

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

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ń za pomocą AuthSub znajdziesz w artykule Podpisywanie żądań AuthSub.

Narzędzie OAuth Playground

Wypróbuj

Cel

Niektórzy użytkownicy twierdzą, że OAuth jest trudny do opanowania. W porównaniu z innymi interfejsami API Google do uwierzytelniania, tak. Zalety protokołu OAuth staną się widoczne, gdy rozszerzysz aplikację o inne usługi (nie Google). Napisanie jednego fragmentu kodu uwierzytelniania, który działa u różnych dostawców usług i ich interfejsów API, brzmi całkiem nieźle. Później podziękujesz sobie za to, że teraz poznajesz protokół.

OAuth Playground to narzędzie, które stworzyłem, aby pomóc deweloperom w rozwiązywaniu problemów z OAuth. Możesz używać środowiska testowego do debugowania problemów, sprawdzania własnej implementacji lub eksperymentowania z interfejsami Google Data API.

Na czym to polega?

1. Ilustracja procesu uwierzytelniania OAuth: pobieranie tokena żądania, autoryzowanie tokena i przekształcanie go w token dostępu.
2. Wyświetla prawidłowy ciąg bazowy podpisu dla każdego żądania.
3. Wyświetla prawidłowy nagłówek Authorization dla każdego żądania.
4. Pokazuje, jak za pomocą oauth_token wchodzić w interakcje z uwierzytelnionym plikiem danych Google. Możesz GET/POST/PUT/DELETE dane.
5. Wyświetl uwierzytelniony plik danych bezpośrednio w przeglądarce.
6. Umożliwia przetestowanie własnej oauth_consumer_key (zarejestrowanej domeny) i klucza prywatnego.
7. Dowiedz się, jakie usługi związane z plikami danych Google są dostępne w przypadku Twojego konta oauth_token.

Uruchomienie demonstracyjne

Krok 1. Wybierz zakresy Najpierw zdecyduj, których interfejsów API chcesz używać, wybierając co najmniej 1 zakres. W tym przykładzie proszę o token, który będzie działać w przypadku Blogera i Kontaktów Google. Podobieństwo do AuthSub: AuthSub również wymaga parametru scope, aby kontrolować zakres danych, do których token może uzyskać dostęp. Google zaimplementowało ten parametr zgodnie z zaleceniami w specyfikacji OAuth.
Krok 2. Zmień parametry i ustawienia OAuth Na razie nie zmieniaj żadnych ustawień w polu „Modify the OAuth Parameters” (Modyfikuj parametry OAuth). Później możesz przetestować działanie narzędzia za pomocą własnego klucza prywatnego. W tym celu zmień oauth_consumer_key na zarejestrowaną domenę i wpisz klucz prywatny, klikając „Użyj własnego klucza prywatnego”. Używaj tylko klucza prywatnego TEST. Uwaga: tylko pola oauth_signature_method i oauth_consumer_key można tu edytować. Wartości oauth_timestamp, oauth_nonce i oauth_token zostaną wygenerowane automatycznie. Oprócz RSA-SHA1 możesz użyć HMAC-SHA1 w przypadku oauth_signature_method. W takim przypadku w Playgroundzie pojawią się dodatkowe pola, w których musisz wpisać własny klucz oauth_consumer_key i klucz tajny klienta. Te wartości znajdziesz na stronie https://www.google.com/accounts/ManageDomains zarejestrowanej domeny. Różnica w stosunku do AuthSub: W bezpiecznym AuthSub nie ma parametru, który umożliwiałby jawne ustawienie nazwy domeny. Domena jest uwzględniona w parametrze adresu URL next. W OAuth jest taki parametr: oauth_consumer_key. Ustaw ją na zarejestrowaną domenę.
Kroki 3–5. Uzyskiwanie tokena 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 proces OAuth. Najpierw kliknij przycisk „Request token” (Poproś o token) w polu „Get the Token” (Pobierz token). Niektóre pola zostaną wypełnione danymi. W sekcji „Ciąg bazowy podpisu” wyświetla się prawidłowa postać ciągu bazowego użytego do utworzenia parametru oauth_signature. W sekcji „Nagłówek autoryzacji” wyświetla się odpowiedni nagłówek Authorization dla żądania. Pole „Modify the OAuth Parameters” (Modyfikuj parametry OAuth) wypełnione wartościami oauth_nonce i oauth_timestamp przesłanymi w żądaniu. Pole wejściowe oauth_token zostało wypełnione odpowiednią wartością zwróconą w treści odpowiedzi. Plac zabaw wyświetla też typ oauth_token, który obecnie mamy. Obecnie jest to token żądania.
Następnie w polu „Uzyskaj token” kliknij przycisk „Authorize” (Autoryzuj). Na tej stronie autoryzacji kliknij przycisk „Grant Access” (Przyznaj dostęp), aby autoryzować token żądania i wrócić do narzędzia OAuth Playground. Podobieństwo do AuthSub: Ta strona autoryzacji jest taka sama jak w przypadku AuthSub. Różnica w stosunku do AuthSub: Parametr adresu URL next w AuthSub jest analogiczny do parametru oauth_callback. Różnica polega na tym, że w przypadku OAuth parametr oauth_callback jest opcjonalny. Gdy użytkownik kliknie przycisk „Przyznaj dostęp”, token żądania zostanie autoryzowany i można będzie asynchronicznie przeprowadzić uaktualnienie tokena do https://www.google.com/accounts/OAuthGetAccessToken. Wskazówka: jeśli piszesz aplikację internetową, zalecamy podanie adresu URL oauth_callback, ponieważ zapewnia to większy komfort użytkownikom.
Na koniec kliknij przycisk „Token dostępu” w polu „Uzyskaj token”. Ta czynność powoduje uaktualnienie autoryzowanego tokena żądania (oznaczonego czerwoną etykietą „token dostępu”). Jeśli chcesz pobrać nowy token, kliknij „Rozpocznij od nowa”, aby ponownie zainicjować proces OAuth. Teraz możemy zrobić coś ciekawego.

Używanie tokena dostępu

Teraz możesz wysyłać zapytania do plików danych, wstawiać, aktualizować i usuwać dane. Podczas wykonywania tych 3 ostatnich metod HTTP zachowaj ostrożność, ponieważ pracujesz z prawdziwymi danymi.

Wskazówka: aby wyświetlić pliki danych 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 maksymalnie 3 posty na określonym blogu. Możesz też wyświetlić zwrócony kanał lub wpis bezpośrednio w przeglądarce, klikając link „Wyświetl w przeglądarce” pod obszarem z podświetloną składnią.

Przykład: jak zaktualizować posta

1. W poście, który chcesz zaktualizować, znajdź element <link> z ikoną rel="edit". Powinien wyglądać podobnie do następującego:

   <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

   Wklej URL href w polu „Wpisz plik danych Google”.

2. Skopiuj XML istniejącego wpisu, klikając „view plain” (wyświetl zwykły tekst) u góry panelu z wyróżnioną składnią. Skopiuj tylko treść odpowiedzi, a nie nagłówki.
3. W menu Metoda HTTP wybierz PUT.
4. Pod tym menu kliknij „enter post data” (wpisz dane posta) i wklej w wyskakującym okienku kod <entry> XML.
5. Kliknij przycisk „Wykonaj”.

Serwer odpowie 200 OK.

Wskazówka: zamiast ręcznie kopiować link edit, odznacz pole wyboru „Podświetlanie składni?”. Po wysłaniu 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 pomagają rozwijać internet. W miarę jak coraz więcej witryn zaczyna stosować te standardy, my, deweloperzy, zyskujemy. Stworzenie przełomowej aplikacji staje się nagle mniej zniechęcające.

Jeśli masz pytania lub uwagi dotyczące OAuth Playground albo korzystania z OAuth w interfejsach API Google, odwiedź forum pomocy dotyczące interfejsów API G Suite i interfejsów API Marketplace.

Zasoby

• Uwierzytelnianie OAuth w aplikacjach internetowych
• Lista interfejsów Google Data API
• Forum dyskusyjne interfejsów Google Accounts API
• Specyfikacja podstawowa OAuth 1.0