Protokół OAuth

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X.
Informacje

Protokół OAuth jest najpopularniejszym protokołem autoryzacji dla interfejsów API. Wersję protokołu OAuth, która jest szczegółowo omówiona w tym temacie, zdefiniowano w specyfikacji OAuth 2.0.

OAuth to protokół, który umożliwia użytkownikom aplikacji autoryzowanie aplikacji do działania w ich imieniu. Aby to zrobić, aplikacje uzyskują tokeny dostępu od dostawców interfejsów API. Dostawca interfejsu API uwierzytelnia dane logowania użytkownika aplikacji, sprawdza, czy użytkownik autoryzował aplikację, a następnie wydaje jej token dostępu. Gdy aplikacja korzysta z chronionego interfejsu API, Apigee Edge sprawdza token dostępu, aby upewnić się, że jest on prawidłowy i nie stracił ważności. Jako dostawca interfejsu API musisz udostępnić punkty końcowe, które umożliwiają aplikacjom pobieranie tokenów dostępu.

Aby ułatwić Ci rozpoczęcie korzystania z protokołu OAuth, Apigee Edge umożliwia skonfigurowanie i wymuszanie protokołu OAuth za pomocą zasad bez konieczności pisania żadnego kodu. Z tej części dowiesz się, jak chronić swoje interfejsy API, jak uzyskiwać tokeny dostępu i jak używać ich do uzyskiwania dostępu do chronionych interfejsów API.

Domyślna konfiguracja OAuth w Twojej organizacji

Dla wygody wszystkie organizacje w Apigee Edge są wstępnie skonfigurowane z zestawem punktów końcowych OAuth 2.0, które implementują typ uwierzytelnienia danych logowania klienta. Typ przyznania danych logowania klienta określa procedurę wydawania tokenów dostępu w zamian za dane logowania do aplikacji. Te dane logowania do aplikacji to po prostu para klucza klienta i obiektu tajnego, które Apigee Edge powoduje w przypadku każdej aplikacji zarejestrowanej w organizacji. Pole „Dane logowania klienta” odnosi się do pary klucza klienta i obiektu tajnego.

Więcej informacji o przyznawaniu danych logowania do aplikacji za pomocą Edge Developer Services znajdziesz w artykule o rejestrowaniu aplikacji i zarządzaniu kluczami.

Z tego powodu można dość łatwo „zwiększyć” schemat zabezpieczeń interfejsu API, zmieniając weryfikację klucza interfejsu API na dane logowania klienta OAuth. Oba schematy używają tego samego klucza i tajnego klucza klienta do weryfikacji aplikacji klienta. Różnica polega na tym, że dane logowania klienta zapewniają dodatkową warstwę kontroli, ponieważ możesz łatwo unieważnić token dostępu w razie potrzeby bez konieczności unieważniania klucza klienta aplikacji. Aby pracować z domyślnymi punktami końcowymi OAuth, możesz pobrać tokeny dostępu z punktu końcowego tokena za pomocą dowolnego klucza klienta i obiektu tajnego dla aplikacji w Twojej organizacji. Możesz nawet włączyć dane logowania klienta w przypadku aplikacji, które mają już klucze klienta i obiekty tajne.

Pełną specyfikację uwierzytelniania klienta znajdziesz w specyfikacji OAuth 2.0.

Ochrona interfejsu API za pomocą zasad

Zanim zaczniesz korzystać z tokenów dostępu, musisz skonfigurować interfejsy API pod kątem weryfikowania tokenów dostępu OAuth w czasie działania. W tym celuskonfiguruj serwer proxy interfejsu API, aby validate tokeny dostępu. Oznacza to, że za każdym razem, gdy aplikacja wysyła żądanie wykorzystania jednego z interfejsów API, wraz z żądaniem do interfejsu API musi przedstawić prawidłowy token dostępu. Apigee Edge zajmuje się generowaniem, przechowywaniem i weryfikowaniem wyświetlanych tokenów dostępu.

Podczas tworzenia nowego serwera proxy API możesz łatwo dodać weryfikację OAuth do interfejsu API. Podczas tworzenia nowego serwera proxy interfejsu API możesz dodać funkcje. Jak pokazano poniżej, możesz dodać weryfikację tokenów dostępu OAuth 2.0, zaznaczając opcję Secure with OAuth v2.0 Access Tokens (Zabezpiecz za pomocą tokenów dostępu OAuth 2.0). Jeśli wybierzesz tę opcję, do nowo utworzonego serwera proxy interfejsu API zostaną dołączone 2 zasady: jedna do weryfikowania tokenów dostępu i druga do usuwania tokena dostępu po jego zweryfikowaniu.

Dodatkowo, gdy wybierzesz opcję Zabezpiecz za pomocą tokenów dostępu OAuth w wersji 2.0, pole wyboru Opublikuj produkt API będzie dostępne do wyboru i zostanie automatycznie zaznaczone. Zaznacz tę opcję, jeśli chcesz automatycznie generować usługę podczas tworzenia nowego serwera proxy interfejsu API. Zostanie utworzony automatycznie produkt powiązany z nowym serwerem proxy interfejsu API. Jeśli masz już usługę, z którą chcesz powiązać nowy interfejs API, usuń zaznaczenie tego pola wyboru, aby nie utworzyć zbędnego produktu. Informacje o usługach znajdziesz w artykule „Co to jest usługa API?”.

Jeśli chcesz włączyć weryfikację tokena dostępu dla istniejącego serwera proxy interfejsu API, musisz tylko dołączyć do interfejsu API, które chcesz chronić, zasadę typu OAuthV2. Zasady OAuthV2 działają przez określenie operacji. Aby zweryfikować tokeny dostępu, wskaż operację o nazwie VerifyAccessToken. (Inne typy operacji obsługiwane przez typ zasady OAuthV2 to GenerateAccessToken i GeneraterefreshToken. Informacje o tych operacjach poznasz po skonfigurowaniu punktów końcowych OAuth.

Zasada weryfikacji OAuthTokens typu OAuthV2

Przykładowa zasada weryfikacji tokenów dostępu wygląda poniżej. (Ustawienia zostały opisane w tabeli poniżej).

<OAuthV2 name="VerifyOAuthTokens"> 
  <Operation>VerifyAccessToken</Operation> 
</OAuthV2>

Ustawienia zasad

Nazwa Opis Domyślne Wymagana?
OAuthV2 Typ zasady
name Nazwa zasady, do której odwołuje się konfiguracja punktu końcowego serwera proxy interfejsu API. Nie dotyczy Tak
Operation Operacja do wykonania przez zasadę OAuthV2. Podając parametr VerificationAccessToken, konfigurujesz zasadę tak, aby sprawdzała żądania tokenów dostępu i czy token dostępu jest prawidłowy, nie wygasł i może wykorzystywać żądany zasób interfejsu API (identyfikator URI). (Aby to sprawdzić, zasada odczytuje usługę API, z której może korzystać aplikacja). Nie dotyczy Tak

Aby utworzyć tę zasadę w interfejsie zarządzania, kliknij Interfejsy API > Serwery proxy interfejsów API.

Z listy serwerów proxy API wybierz Weatherapi.

W sekcji Overview (Przegląd) dla pogody API wybierz widok Develop (Programowanie).

W menu wybierz Nowa zasada > OAuth v2.0.

Gdy wybierzesz zasadę OAuth 2.0, pojawi się menu konfiguracji Nowa zasada.

Nadaj zasadzie opisową nazwę oraz wybierz Attach Policy (Załącz zasadę), Flow PreFlow i Request (Żądanie) jako ustawienia załącznika zasad.

Wybierz Add (Dodaj). Zasada zostanie utworzona i dołączona do żądania PreFlow modułu meteorologicznego.

Gdy dodasz zasadę, w panelu Projekter pojawi się konfiguracja żądania PreFlow poniżej.

Jeśli pracujesz lokalnie w edytorze tekstu lub IDE, dołączasz zasady do żądania wstępnego przepływu serwera proxy interfejsu API, który chcesz chronić:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

Dołączając zasadę do żądania PreFlow, masz pewność, że będzie ona zawsze egzekwowana we wszystkich wiadomościach z żądaniami.

Udało Ci się zabezpieczyć interfejs API za pomocą danych logowania klienta OAuth 2.0. W następnym kroku się dowiesz, jak uzyskać token dostępu i jak wykorzystać go do uzyskania dostępu do bezpiecznego interfejsu API.

Uzyskiwanie dostępu do chronionego zasobu za pomocą tokena dostępu

Teraz gdy prognoza pogody jest zabezpieczona za pomocą protokołu OAuth 2.0, aplikacje muszą prezentować tokeny dostępu, aby móc korzystać z interfejsu API. Aby uzyskać dostęp do chronionego zasobu, aplikacja przedstawia token dostępu w żądaniu w postaci nagłówka HTTP „Authorization” w następujący sposób:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Ponieważ do interfejsu API jest dołączona zasada OAuthV2, Apigee Edge sprawdzi, czy przedstawiony token dostępu jest prawidłowy, a następnie przyzna dostęp do interfejsu API, zwracając raport o pogodzie do aplikacji, która wysłała żądanie.

Ale w jaki sposób aplikacje uzyskują tokeny dostępu? Omówimy to w następnej sekcji.

Jak wymienić dane logowania klienta na token dostępu

Aplikacje uzyskują tokeny dostępu przez przedstawianie swoich par klucz/klucz klienta w punkcie końcowym tokena. Punkt końcowy tokena jest skonfigurowany na serwerze proxy interfejsu API o nazwie oauth. Aby uzyskać token dostępu, aplikacje muszą wywołać interfejs API ujawniony przez serwer proxy interfejsu oauth API. Gdy aplikacja ma token dostępu, może wielokrotnie wywoływać Weatherapi, aż token dostępu wygaśnie lub zostanie unieważniony.

Teraz musisz zacząć myśleć o sobie jako deweloperze aplikacji. Chcesz wywołać funkcjęWeatherapi, więc musisz uzyskać token dostępu dla swojej aplikacji. Najpierw musisz uzyskać parę klucza klienta i obiektu tajnego (nazywanego też kluczem interfejsu API lub kluczem aplikacji).

Możesz uzyskać klucz klienta i obiekt tajny, rejestrując aplikację w organizacji w Apigee Edge.

Wszystkie aplikacje w organizacji są widoczne w interfejsie zarządzania Apigee Edge.

Pojawi się lista aplikacji zarejestrowanych w Twojej organizacji.

Jeśli nie wyświetlają się żadne aplikacje, więcej informacji o tym, jak zarejestrować aplikację, znajdziesz w temacie Rejestrowanie aplikacji i zarządzanie kluczami interfejsu API.

Wybierz aplikację z listy, aby wyświetlić jej szczegółowy profil.

W widoku szczegółów wybranej aplikacji zwróć uwagę na pola Klucz klienta i Tajny klucz klienta. Te 2 wartości to dane logowania klienta, których należy użyć, aby uzyskać token dostępu OAuth.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass 

To wywołanie zwraca listę aplikacji posortowaną według identyfikatora aplikacji.

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

Profil aplikacji możesz pobrać, wykonując proste wywołanie GET z identyfikatorem aplikacji:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass 

Na przykład:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass 

Wywołanie interfejsu API zwraca profil określonej aplikacji. Na przykład profil aplikacji pogodaaplikacja ma taką reprezentację w formacie JSON:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

Zapisz wartości consumerKey i consumerSecret. Te dane logowania pozwalają uzyskać token dostępu, przedstawiając je w żądaniu HTTP jako dane uwierzytelniające podstawowe, jak pokazano poniżej. Typ uwierzytelnienia jest przedstawiony w żądaniu jako parametr zapytania. (pamiętaj, aby zmienić wartość zmiennej {org_name} tak, aby odzwierciedlała nazwę Twojej organizacji w Apigee Edge).

Utwórz żądanie uzyskania tokena dostępu

W poniższym żądaniu zastąp wartość consumerKey wartością client_id. Zamień wartość powiązanego elementu consumerSecret na client_secret.

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Usługi API weryfikują klucz i tajny klucz klienta, a następnie generują odpowiedź zawierającą token dostępu dla tej aplikacji:

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Zwróć uwagę na wartość access_token w odpowiedzi powyżej. To token dostępu, za pomocą którego aplikacja uzyska dostęp w środowisku wykonawczym do chronionych zasobów. Token dostępu tej aplikacji to ylSkZIjbdWybfs4fUQe9BqP0LH5Z.

Masz teraz prawidłowy token dostępu (ylSkZIjbdWybfs4fUQe9BqP0LH5Z), który umożliwia dostęp do chronionych interfejsów API.

Praca z domyślną konfiguracją OAuth

Każda organizacja (nawet organizacja bezpłatnego okresu próbnego) w Apigee Edge ma udostępniony punkt końcowy tokena OAuth. Punkt końcowy jest już skonfigurowany z użyciem zasad na serwerze proxy interfejsu API o nazwie oauth. Możesz zacząć korzystać z punktu końcowego tokena, gdy tylko utworzysz konto w Apigee Edge.

Domyślny punkt końcowy OAuth ujawnia ten identyfikator URI punktu końcowego:

/oauth/client_credential/accesstoken

Opublikuj ten identyfikator URI deweloperom, którzy muszą uzyskać tokeny dostępu. Deweloperzy aplikacji konfigurują w aplikacjach wywoływanie tego punktu końcowego, przedstawiając swoje pary klucza i tajnego klucza klienta w celu uzyskania tokenów dostępu.

Domyślny punkt końcowy tokena danych logowania klienta jest widoczny w sieci pod tym adresem URL:

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

Jeśli na przykład nazwa Twojej organizacji to „apimakers”, adres URL będzie miał postać:

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

To adres URL, który programiści wywołują, aby uzyskać tokeny dostępu.

Konfiguracje trzyetapowej autoryzacji OAuth

Konfiguracje trzyetapowej autoryzacji OAuth (kod autoryzacji, niejawne i typy uwierzytelnienia hasła) wymagają uwierzytelniania użytkowników aplikacji przez Ciebie jako dostawcę interfejsu API. Każda organizacja uwierzytelnia użytkowników na różne sposoby, dlatego do integracji protokołu OAuth z magazynem użytkowników wymagane jest dostosowanie zasad lub zastosowanie kodu. Na przykład wszyscy użytkownicy mogą być przechowywany w Active Directory, w LDAP lub innym magazynie użytkowników. Aby uruchomić trzyetapową autoryzację OAuth, musisz zintegrować sprawdzanie w magazynie użytkowników z ogólnym przepływem OAuth.

OAuth 1.0a

Więcej informacji o zasadach dotyczących protokołu OAuth 1.0a znajdziesz w artykule Zasady OAuth w wersji 1.0a.

Pomoc

Więcej informacji znajdziesz w artykule na temat obsługi klienta Apigee.