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

OAuth for Data Plan Agent API

Powiązane dokumenty

Protokół OAuth 2.0 jest znormalizowany w dokumencie RFC 6749. Szczegółowy dokument jest dostępny na stronie https://oauth.net/2. Podstawowe uwierzytelnianie HTTP jest zdefiniowane w sekcji 2 standardu RFC 2617.

Przegląd

Zwykle, aby umożliwić aplikacjom innych firm dostęp do zasobów o ograniczonym dostępie, takich jak dane pakietu internetowego i szczegóły portfela, użytkownik (właściciel zasobu) musi udostępnić swoje dane logowania firmie zewnętrznej. Powoduje to kilka problemów i ograniczeń, takich jak przechowywanie danych logowania, uwierzytelnianie za pomocą hasła, szeroki dostęp do zasobów użytkownika końcowego i wyciek hasła itp. Protokół OAuth 2.0 rozwiązuje te problemy, wprowadzając warstwę autoryzacji, a tym samym zabezpieczając i ograniczając dostęp do chronionych zasobów użytkownika końcowego.

Zamiast używać danych logowania użytkownika do uzyskiwania dostępu do chronionych zasobów, takich jak szczegóły pakietu danych, GTAF pobiera token dostępu. Tokeny dostępu są wydawane usłudze GTAF w imieniu jej danych logowania. Następnie GTAF używa tokena dostępu do uzyskiwania szczegółów planu danych hostowanego przez DPA.

Na rysunku poniżej przedstawiono ogólny przepływ informacji:

Rysunek 1. Abstrakcyjny proces OAuth.

Tokeny dostępu

Tokeny dostępu to dane logowania używane przez GTAF do uzyskiwania dostępu do szczegółów pakietu danych z DPA operatora. Token dostępu to ciąg znaków reprezentujący autoryzację wydaną na rzecz GTAF. Ciąg tekstowy jest zwykle nieprzejrzysty dla GTAF. Tokeny reprezentują określone zakresy i czas trwania dostępu przyznanego przez użytkownika operatorowi i egzekwowanego przez DPA oraz serwer OAuth operatora.

Token dostępu zapewnia warstwę abstrakcji, zastępując różne konstrukcje autoryzacji (np. nazwę użytkownika i hasło) jednym tokenem rozpoznawanym przez dostawcę platformy danych. Ta abstrakcja umożliwia wydawanie tokenów dostępu o bardziej restrykcyjnych uprawnieniach niż przyznane uprawnienia autoryzacji użyte do ich uzyskania, a także eliminuje konieczność poznania przez dostawcę platformy danych szerokiego zakresu metod uwierzytelniania.

Tokeny dostępu mogą mieć różne formaty, struktury i metody wykorzystania (np. właściwości kryptograficzne) w zależności od wymagań operatora dotyczących bezpieczeństwa. GTAF obsługuje tylko tokeny dostępu typu bearer zdefiniowane w [RFC6750].

Uwierzytelnianie klienta

GTAF działa jako „klient poufny” i może chronić hasła. GTAF obsługuje obecnie tylko uwierzytelnianie podstawowe HTTP do uwierzytelniania w DPA. Identyfikator klienta jest kodowany za pomocą algorytmu kodowania „application/x-www-form-urlencoded”, a zakodowana wartość jest używana jako nazwa użytkownika. Hasło jest kodowane za pomocą tego samego algorytmu i używane jako hasło.

Klienci poufni, np. GTAF, którym wydano dane logowania klienta, uwierzytelniają się na serwerze OAuth operatora podczas wysyłania żądań do punktu końcowego tokena. Uwierzytelnianie klienta jest używane do:

Odzyskiwanie dostępu do przejętego klienta przez wyłączenie go lub zmianę jego danych logowania, co uniemożliwia atakującemu wykorzystanie skradzionych tokenów odświeżania. Zmiana jednego zestawu danych logowania klienta jest znacznie szybsza niż cofnięcie całego zestawu tokenów odświeżania.
wdrażanie sprawdzonych metod zarządzania uwierzytelnianiem, które wymagają okresowej zmiany danych logowania;

GTAF używa parametru żądania „client_id”, aby identyfikować się podczas wysyłania żądań do punktu końcowego tokena.

Szczególnie ważna jest możliwość rotacji danych logowania klienta. Serwer OAuth musi obsługiwać 2 pary danych logowania jednocześnie podczas rotacji i musi mieć możliwość wyłączania danych logowania. W typowym procesie rotacji danych logowania:

Operator tworzy nowe dane logowania na serwerze OAuth i bezpiecznie przekazuje je menedżerowi konta technicznego.
Google testuje nowe dane logowania i zmienia konfigurację GTAF, aby używać nowych danych logowania.
Google powiadamia operatora, że stare dane logowania mogą zostać wyłączone.
Operator wyłącza dane logowania i powiadamia o tym Google.
Google sprawdza, czy stare dane logowania nie działają już prawidłowo.

Serwer OAuth musi obsługiwać powyższy proces rotacji.

Punkt końcowy tokena

Punkt końcowy tokena jest używany przez GTAF do uzyskiwania tokena dostępu przez przedstawienie udzielonego pozwolenia na autoryzację lub tokena odświeżania. Punkt końcowy tokena jest używany w przypadku każdego uwierzytelnienia, z wyjątkiem uwierzytelnienia implicit (ponieważ token dostępu jest wydawany bezpośrednio).

Podczas konfigurowania punktu końcowego tokena należy wziąć pod uwagę te kwestie:

Lokalizacja punktu końcowego tokena powinna być podana w dokumentacji usługi.
Identyfikator URI punktu końcowego może zawierać komponent zapytania w formacie „application/x-www-form-urlencoded”, który należy zachować podczas dodawania dodatkowych parametrów zapytania. Identyfikator URI punktu końcowego nie może zawierać komponentu fragmentu.
Ponieważ żądania wysyłane do punktu końcowego tokena powodują przesyłanie danych logowania w postaci zwykłego tekstu (w żądaniu i odpowiedzi HTTP), serwer OAuth operatora musi używać protokołu TLS do wysyłania żądań do punktu końcowego tokena.
GTAF używa metody HTTP „POST”, gdy wysyła żądanie tokena dostępu.
Parametry wysłane bez wartości muszą być traktowane jako pominięte w żądaniu. Serwer OAuth musi ignorować nierozpoznane parametry żądania. Parametry żądania i odpowiedzi nie mogą być uwzględniane więcej niż raz.
GTAF obsługuje tylko tokeny dostępu typu bearer.

Zakres tokena dostępu

Punkty końcowe autoryzacji i tokena umożliwiają klientowi określenie zakresu żądania dostępu za pomocą parametru żądania „scope”. Serwer autoryzacji używa parametru odpowiedzi „scope”, aby poinformować klienta o zakresie wydanego tokena dostępu.

Wartość parametru scope jest wyrażona jako lista ciągów znaków rozdzielonych spacjami, w których wielkość liter ma znaczenie. Ciągi znaków są definiowane przez serwer autoryzacji. Jeśli wartość zawiera kilka ciągów znaków rozdzielonych spacjami, ich kolejność nie ma znaczenia, a każdy ciąg znaków dodaje do żądanego zakresu dodatkowy zakres dostępu.

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF nie wymaga wdrożenia tego zakresu, ale obsługuje tę funkcję. Więcej informacji znajdziesz w sekcji 3.3 dokumentu RFC 6749.

Wydawanie tokena dostępu

Jeśli żądanie tokena dostępu wysłane przez GTAF jest prawidłowe i autoryzowane, serwer OAuth wydaje token dostępu i opcjonalny token odświeżania. Jeśli uwierzytelnianie klienta lub żądanie się nie powiedzie, serwer OAuth zwraca odpowiedź o błędzie zgodnie z opisem w następnej sekcji.

Odpowiedź pomyślna

Gdy GTAF wysyła żądanie, serwer OAuth wydaje token dostępu i opcjonalny token odświeżania oraz tworzy odpowiedź, dodając te parametry do treści odpowiedzi HTTP z kodem stanu 200 (OK):

access_token: WYMAGANY. Token dostępu wydany przez serwer OAuth. GTAF oczekuje, że punkt końcowy tokena zwróci token dostępu.
expires_in: WYMAGANY. Okres ważności tokena dostępu w sekundach. Na przykład wartość „3600” oznacza, że token dostępu wygaśnie godzinę po wygenerowaniu odpowiedzi. Jeśli ten parametr zostanie pominięty, serwer OAuth powinien podać czas wygaśnięcia w inny sposób lub udokumentować wartość domyślną.
token_type: WYMAGANY. Typ wydanego tokena. Więcej informacji o różnych typach tokenów znajdziesz w sekcji 7.1 dokumentu RFC 6749. Wielkość liter w wartości nie ma znaczenia. W momencie pisania tego artykułu GTAF obsługuje tylko tokeny dostępu.
refresh_token: OPCJONALNY. Token odświeżania, którego można użyć do uzyskania nowych tokenów dostępu przy użyciu tego samego uprawnienia do autoryzacji.
scope: OPCJONALNE, jeśli jest zaimplementowane i identyczne z zakresem żądanym przez GTAF; w przeciwnym razie wymagane.

Parametry są uwzględniane w treści odpowiedzi HTTP przy użyciu typu „application/json”. Parametry są serializowane do struktury JSON (JavaScript Object Notation) przez dodanie każdego parametru na najwyższym poziomie struktury. Nazwy parametrów i wartości ciągów znaków są uwzględniane jako ciągi JSON. Wartości liczbowe są uwzględniane jako liczby JSON. Kolejność parametrów nie ma znaczenia i może się różnić.

Serwer autoryzacji MUSI uwzględniać w każdej odpowiedzi zawierającej tokeny, dane logowania lub inne informacje poufne pole nagłówka HTTP „Cache-Control” o wartości „no-store”, a także pole nagłówka odpowiedzi „Pragma” o wartości „no-cache”.

Przykład:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

Oto kilka ważnych kwestii, które warto wziąć pod uwagę:

GTAF ignoruje w odpowiedzi nazwy nierozpoznanych wartości.
Rozmiary tokenów i innych wartości otrzymanych z serwera OAuth pozostają niezdefiniowane.
GTAF nie powinien zakładać, jakie są rozmiary wartości. Serwer OAuth powinien dokumentować rozmiar każdej wydawanej wartości.

Odpowiedź z błędem

Jeśli żądanie autoryzacji nie powiedzie się z jakiegokolwiek powodu, np. z powodu braku, nieprawidłowego lub niezgodnego identyfikatora URI przekierowania albo braku lub nieprawidłowego identyfikatora klienta, serwer OAuth powinien odpowiedzieć kodem stanu HTTP 400 (Bad Request) (chyba że określono inaczej) i zawierać co najmniej jeden z parametrów wymienionych w sekcji Odpowiedź i kody błędów.

Przyznanie autoryzacji w GTAF

Grant autoryzacji to dane logowania reprezentujące autoryzację użytkownika (do uzyskiwania dostępu do chronionych zasobów, takich jak informacje o salda danych), które są używane przez GTAF do uzyskiwania tokena dostępu.

GTAF używa typu uwierzytelnienia client_credentials. W przypadku typu autoryzacji client_credentials GTAF wysyła żądanie tokena za pomocą żądania HTTP POST i podstawowego uwierzytelniania HTTP. Wszystkie żądania są wysyłane przez protokół TLS (czyli HTTPS), a GTAF nie może zintegrować się z serwerem OAuth bez prawidłowego certyfikatu TLS. GTAF może przekazywać konfigurowalny zakres tokena. Jeśli nie jest on skonfigurowany, przekazuje pusty zakres.

GTAF oczekuje, że token dostępu zostanie zwrócony wraz z wartością „expires_in” (czas życia). Wartość expires_in powinna wynosić co najmniej 900 sekund i nie powinna przekraczać kilku godzin. Żądanie nowego tokena nie może powodować wcześniejszego wygaśnięcia istniejących tokenów.

Więcej informacji o różnych typach autoryzacji znajdziesz w sekcji 1.3 dokumentu RFC 6749.

Przykładowe żądanie i odpowiedź

Załóżmy, że GTAF ma taką konfigurację serwera OAuth:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

Uwaga: tajny klucz klienta w przypadku prawdziwego dostawcy platformy danych musi być znacznie bezpieczniejszy niż ten pokazany w przykładzie.

Aby utworzyć ciąg autoryzacji, połącz identyfikator klienta, znak „:” i hasło, a następnie zakoduj je w formacie base64. Możesz to zrobić w interfejsie wiersza poleceń w ten sposób:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

GTAF wysyła następnie żądanie HTTPS POST do serwera OAuth, używając tych danych logowania, typu uprawnień client_credentials i skonfigurowanego zakresu. W tym przykładzie żądanie GTAF jest podobne do żądania wygenerowanego przez:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

Nagłówki używane przez GTAF nie będą zgodne z nagłówkami wysyłanymi przez curl, chociaż nagłówek autoryzacji będzie identyczny.

GTAF oczekuje odpowiedzi w formacie:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

Oto przykład prawidłowej odpowiedzi:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

Uwaga: odpowiedź musi być prawidłowym ciągiem znaków JSON.

Odpowiedź na błąd i kody

Jeśli żądanie autoryzacji z GTAF nie powiedzie się z któregokolwiek z powodów wymienionych w sekcji Odpowiedź z błędem, serwer OAuth musi odpowiedzieć kodem stanu HTTP 400 (Bad Request) (chyba że określono inaczej) i dołączyć do odpowiedzi jeden z tych parametrów:

Przykład:

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF oczekuje, że serwer OAuth będzie obsługiwać te odpowiedzi o błędach:

Kod błędu	Odpowiedź	Uzasadnienie
HTTP 400	invalid_request	W żądaniu brakuje wymaganego parametru, zawiera ono nieobsługiwaną wartość parametru (inną niż typ uprawnień), powtarza parametr, zawiera wiele danych logowania, korzysta z więcej niż jednego mechanizmu uwierzytelniania w GTAF lub jest w inny sposób nieprawidłowe.
HTTP 401	invalid_client	Uwierzytelnianie klienta nie powiodło się (np. nieznany klient, brak uwierzytelniania klienta lub nieobsługiwana metoda uwierzytelniania). Serwer OAuth może zwrócić kod stanu HTTP 401 (Brak autoryzacji), aby wskazać obsługiwane schematy uwierzytelniania HTTP. Jeśli klient próbował uwierzytelnić się za pomocą pola nagłówka żądania „Authorization”, serwer OAuth musi odpowiedzieć kodem stanu HTTP 401 (Unauthorized) i uwzględnić pole nagłówka odpowiedzi „WWW-Authenticate” pasujące do schematu uwierzytelniania używanego przez klienta.
HTTP 500	Awaria serwera OAuth

Szczegółowe informacje o innych odpowiedziach, których można używać do debugowania, znajdziesz w sekcji 5.2 dokumentu RFC 6749.

OAuth for Data Plan Agent API Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.