Zabezpieczanie interfejsu API za pomocą protokołu OAuth

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

Czego się nauczysz

  • Pobierz i wdróż przykładowy serwer proxy interfejsu API.
  • Utwórz serwer proxy interfejsu API chroniony przez OAuth.
  • Utwórz produkt, dewelopera i aplikację.
  • Wymiana danych logowania tokena dostępu OAuth.
  • Wywołaj interfejs API za pomocą tokena dostępu.

W tym samouczku pokazujemy, jak zabezpieczyć interfejs API za pomocą protokołu OAuth 2.0.

OAuth to protokół autoryzacji, który umożliwia aplikacjom dostęp do informacji w imieniu użytkowników bez konieczności podawania nazwy użytkownika i hasła.

W ramach protokołu OAuth dane uwierzytelniające (takie jak nazwa użytkownika/hasło lub klucz/klucz) są wymieniane na token dostępu. Na przykład:

joe:joes_password (nazwa_użytkownika:hasło) lub
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (klucz:tajny)

zmieni się na:

b0uiYwjRZLEo4lEu7ky2GGxHkanN

Token dostępu to losowy ciąg znaków i jest tymczasowy (powinien wygasać po stosunkowo krótkim czasie), dlatego jego przekazanie w celu uwierzytelnienia użytkownika w przepływie pracy w aplikacji jest znacznie bezpieczniejsze niż przekazywanie rzeczywistych danych logowania.

Specyfikacja OAuth 2.0 definiuje różne mechanizmy nazywane „typami uwierzytelnienia” do rozpowszechniania tokenów dostępu do aplikacji. Najbardziej podstawowy typ uwierzytelnienia zdefiniowany przez OAuth 2.0 to „dane logowania klienta”. W tym typie uwierzytelnienia tokeny dostępu OAuth są generowane w zamian za dane logowania klienta, które są parami klucz-wartość klienta i klienta, tak jak w przykładzie powyżej.

Typ przyznania danych logowania klienta w Edge jest wdrażany przy użyciu zasad w serwerach proxy interfejsu API. Typowy przepływ OAuth obejmuje 2 kroki:

  • Wywołaj serwer proxy 1 interfejsu API, aby wygenerować token dostępu OAuth na podstawie danych logowania klienta. Zajmuje się tym zasada OAuth 2.0 na serwerze proxy interfejsu API.
  • Serwer proxy 2 interfejsu API wywoływania, aby wysłać token dostępu OAuth w wywołaniu interfejsu API. Serwer proxy interfejsu API weryfikuje token dostępu przy użyciu zasady OAuth 2.0.

Czego potrzebujesz

  • konto Apigee Edge. Jeśli jeszcze go nie masz, możesz się zarejestrować zgodnie z instrukcjami na stronie Tworzenie konta Apigee Edge.
  • Zainstalowany na komputerze program cURL umożliwia wykonywanie wywołań interfejsu API z poziomu wiersza poleceń.

Pobierz i wdróż serwer proxy interfejsu API do generowania tokenów

W tym kroku utworzysz serwer proxy interfejsu API, który generuje token dostępu OAuth z klucza klienta i tajnego klucza klienta wysłanych w wywołaniu interfejsu API. Apigee udostępnia przykładowy serwer proxy interfejsu API, który to robi. Pobierzesz i wdrożysz serwer proxy, a potem użyjesz go później w samouczku. Ten serwer proxy interfejsu API możesz łatwo utworzyć samodzielnie. Ten krok pobierania i wdrażania ma na celu udogodnienie oraz pokazanie, jak łatwo można udostępniać utworzone serwery proxy.

  1. Pobierz plik ZIP „oauth” przykładowego serwera proxy interfejsu API do dowolnego katalogu w systemie plików.
  2. Otwórz stronę https://apigee.com/edge i zaloguj się.
  3. Na pasku nawigacyjnym po lewej stronie wybierz Programowanie > Proxies API.
  4. Kliknij + Serwer proxy.
    Przycisk tworzenia serwera proxy
  5. W kreatorze tworzenia serwera proxy kliknij Prześlij pakiet proxy.
  6. Wybierz pobrany plik oauth.zip i kliknij Dalej.
  7. Kliknij Utwórz.
  8. Po zakończeniu kompilacji kliknij Edytuj serwer proxy, aby wyświetlić nowy serwer proxy w edytorze proxy interfejsu API.
  9. Na stronie Przegląd interfejsu API Proxy Editor kliknij menu Wdrożenie i wybierz test. Jest to środowisko testowe w organizacji.

    Po wyświetleniu prośby o potwierdzenie kliknij Wdróż.
    Gdy ponownie klikniesz menu Wdrażanie, zielona ikona będzie oznaczać, że serwer proxy został wdrożony w środowisku testowym.

Doskonale! Udało Ci się pobrać i wdrożyć w swojej organizacji Edge serwer proxy interfejsu API generujący tokeny dostępu.

Wyświetlanie procesu OAuth i zasad

Przyjrzyjmy się temu, co zawiera serwer proxy interfejsu API.

  1. W edytorze proxy interfejsu API kliknij kartę Develop (Programuj). W panelu Nawigator po lewej stronie zobaczysz 2 zasady. W sekcji Proxy Endpoints zobaczysz też 2 przepływy POST.
  2. Kliknij AccessTokenClientCredential w sekcji Proxy Endpoints.

    W widoku kodu XML zobaczysz Flow o nazwie AccessTokenClientCredential:

    <Flow name="AccessTokenClientCredential">
        <Description/>
        <Request>
            <Step>
                <Name>GenerateAccessTokenClient</Name>
            </Step>
        </Request>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
    </Flow>
    

    Przepływ to etap przetwarzania na serwerze proxy interfejsu API. W tym przypadku przepływ jest aktywowany, gdy zostanie spełniony określony warunek (jest to tzw. przepływ warunkowy). Warunek zdefiniowany w elemencie <Condition> wskazuje, że jeśli wywołanie serwera proxy interfejsu API zostanie wykonane do zasobu /accesstoken, a czasownik żądania to POST, wykonaj zasadę GenerateAccessTokenClient, która wygeneruje token dostępu.

  3. Przyjrzyjmy się teraz zasadzie, która uruchamia przepływ warunkowy. Na diagramie procesu kliknij ikonę zasady GenerateAccessTokenClient.

    W widoku kodu zostanie załadowana taka konfiguracja XML:

    <OAuthV2 name="GenerateAccessTokenClient">
        <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
        <Operation>GenerateAccessToken</Operation>
        <!-- This is in millseconds, so expire in an hour -->
        <ExpiresIn>3600000</ExpiresIn>
        <SupportedGrantTypes>
            <!-- This part is very important: most real OAuth 2.0 apps will want to use other
             grant types. In this case it is important to NOT include the "client_credentials"
             type because it allows a client to get access to a token with no user authentication -->
            <GrantType>client_credentials</GrantType>
        </SupportedGrantTypes>
        <GrantType>request.queryparam.grant_type</GrantType>
        <GenerateResponse/>
    </OAuthV2>
    

    Konfiguracja obejmuje te elementy:

    • <Operation>, czyli jedna z kilku wstępnie zdefiniowanych wartości, określa sposób działania tej zasady. W tym przypadku wygeneruje token dostępu.
    • Ważność tokena wygasa po upływie 1 godziny (36 000 000 milisekund) od wygenerowania.
    • W <SupportedGrantTypes> oczekiwany ma być używany protokół OAuth <GrantType> to client_credentials (wymiana klucza klienta i tajnego klucza na token OAuth).
    • Drugi element <GrantType> informuje zasadę, gdzie szukać parametru typu uwierzytelnienia w wywołaniu interfejsu API, zgodnie ze specyfikacją OAuth 2.0. (Trzeba to zobaczyć później w wywołaniu interfejsu API). Typ przyznania można też wysłać w nagłówku HTTP (request.header.grant_type) lub jako parametr formularza (request.formparam.grant_type).

W tej chwili nie musisz nic więcej robić z serwerem proxy interfejsu API. W kolejnych krokach użyjesz tego serwera proxy interfejsu API do wygenerowania tokena dostępu OAuth. Ale najpierw musisz zrobić jeszcze kilka rzeczy:

  • Utwórz serwer proxy interfejsu API, który chcesz zabezpieczyć za pomocą protokołu OAuth.
  • Utwórz więcej artefaktów, aby uzyskać klucz klienta i tajny klucz klienta, które musisz wymienić na token dostępu.

Tworzenie serwera proxy interfejsu API chronionego przez OAuth

Informacje o elemencie próbnym

Usługa mocktarget jest hostowana w Apigee i zwraca proste dane. W rzeczywistości jest ona dostępna w przeglądarce. Aby wypróbować tę funkcję, kliknij ten link:

http://mocktarget.apigee.net/ip

Obiekt docelowy zwraca to, co powinno zostać wyświetlone, gdy w końcu wywołasz ten serwer proxy interfejsu API.

Możesz też wejść na stronę http://mocktarget.apigee.net/help, aby zobaczyć inne zasoby interfejsu API dostępne w mocktarget.

Teraz utworzysz serwer proxy interfejsu API, który chcesz chronić. Jest to wywołanie interfejsu API, które zwraca to, czego szukasz. W tym przypadku serwer proxy interfejsu API wywoła usługę Apigee, aby zwrócić Twój adres IP. Zobaczysz go tylko wtedy, gdy w wywołaniu interfejsu API przekażesz prawidłowy token dostępu OAuth.

Utworzony w tym miejscu serwer proxy interfejsu API będzie zawierał zasadę, która sprawdza, czy w żądaniu występuje token OAuth.

  1. Na pasku nawigacyjnym po lewej stronie wybierz Programowanie > Proxies API.
  2. Kliknij + Serwer proxy.
    Przycisk tworzenia serwera proxy
  3. W kreatorze Tworzenie serwera proxy wybierz Odwrotny serwer proxy (najczęstszy) i kliknij Dalej.
  4. W serwerze proxy skonfiguruj:
    W tym polu wykonaj to
    Nazwa serwera proxy Wpisz: helloworld_oauth2
    Ścieżka bazowa projektu

    Zmień na: /hellooauth2

    Ścieżka bazowa projektu jest częścią adresu URL używanego do wysyłania żądań do serwera proxy interfejsu API.

    Dotychczasowy interfejs API

    Wpisz: https://mocktarget.apigee.net/ip

    Określa docelowy adres URL wywoływany przez Apigee Edge w odpowiedzi na żądanie wysyłane do serwera proxy interfejsu API.

    Opis Wpisz: hello world protected by OAuth
  5. Kliknij Dalej.
  6. Na stronie Typowe zasady:
    W tym polu wykonaj to
    Zabezpieczenia: autoryzacja Wybierz: OAuth 2.0.
  7. Kliknij Dalej.
  8. Na stronie Hosty wirtualne kliknij Dalej.
  9. Na stronie Tworzenie wybierz środowisko testowe, a następnie kliknij Utwórz i wdróż.
  10. Na stronie Podsumowanie zobaczysz potwierdzenie, że nowy serwer proxy interfejsu API został utworzony, a serwer proxy interfejsu API został wdrożony w środowisku testowym.
  11. Kliknij Edytuj serwer proxy, aby wyświetlić stronę Przegląd serwera proxy interfejsu API.
    Zwróć uwagę, że tym razem serwer proxy interfejsu API jest wdrażany automatycznie. Kliknij menu Wdrożenie, aby sprawdzić, czy obok środowiska „testowego” znajduje się zielona kropka wdrożenia.

Wyświetl zasady

Przyjrzyjmy się bliżej temu, co udało Ci się utworzyć.

  1. W edytorze proxy interfejsu API kliknij kartę Develop (Programuj). Zobaczysz, że do przepływu żądań serwera proxy interfejsu API zostały dodane 2 zasady:
    • Zweryfikuj token dostępu OAuth 2.0 – sprawdza wywołanie interfejsu API, by upewnić się, że istnieje prawidłowy token dostępu OAuth.
    • Remove Header Authorization (Usuń autoryzację nagłówka) – zasada AssignMessage, która usuwa token dostępu po sprawdzeniu, by nie został przekazany do usługi docelowej. (Jeśli usługa docelowa wymaga tokena dostępu OAuth, nie używaj tej zasady).
  2. Kliknij ikonę Zweryfikuj token dostępu OAuth 2.0 w widoku procesu i spójrz na kod XML znajdujący się pod nim w panelu kodu.

    <OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
        <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
        <Operation>VerifyAccessToken</Operation>
    </OAuthV2>
    

    Zwróć uwagę, że <Operation> to VerifyAccessToken. Ta operacja określa, co powinna robić zasada. W tym przypadku sprawdza, czy w żądaniu znajduje się prawidłowy token OAuth.

Dodaj usługę API

Aby dodać usługę API za pomocą interfejsu Apigee:

  1. Wybierz Opublikuj > Usługi API.
  2. Kliknij + Usługa interfejsu API.
  3. Podaj Szczegóły produktu w interfejsie API.
    Pole Opis
    Nazwa Wewnętrzna nazwa usługi API. Nie dodawaj znaków specjalnych w nazwie.
    Uwaga: po utworzeniu usługi API nie można edytować nazwy. Przykład: helloworld_oauth2-Product
    Wyświetlana nazwa Wyświetlana nazwa usługi API. Wyświetlana nazwa jest używana w interfejsie użytkownika i możesz ją w każdej chwili edytować. Jeśli wartość nie zostanie określona, zostanie użyta wartość Nazwa. To pole jest automatycznie wypełniane wartością Nazwa. Możesz edytować i usuwać jego zawartość. Wyświetlana nazwa może zawierać znaki specjalne. Na przykład: helloworld_oauth2-Product.
    Opis Opis usługi API.
    Środowisko Środowiska, do których produkt API ma dostęp. Wybierz środowisko, w którym wdrożono serwer proxy interfejsu API. Na przykład: test.
    Dostęp Wybierz Publiczne.
    Automatyczne zatwierdzanie próśb o dostęp Włącz automatyczne zatwierdzanie żądań kluczy dla tej usługi interfejsu API z dowolnej aplikacji.
    Limit Zignoruj w tym samouczku.
    Dozwolone zakresy protokołu OAuth Zignoruj w tym samouczku.
  4. W polu Proxy interfejsów API wybierz utworzony przed chwilą serwer proxy interfejsu API.
  5. W polu Ścieżka wpisz „/”. Zignoruj pozostałe pola.
  6. Kliknij Zapisz.

Dodawanie dewelopera i aplikacji do organizacji

Następnie przeprowadzimy symulację przepływu pracy programisty podczas rejestracji w celu korzystania z interfejsów API. W idealnej sytuacji deweloperzy rejestrują się i swoje aplikacje przez portal dla deweloperów. W tym kroku dodaj jednak dewelopera i aplikację jako administratora.

Deweloper będzie mieć co najmniej jedną aplikację, która będzie wywoływać Twoje interfejsy API, a każda z nich otrzyma unikalny klucz klienta i tajny klucz klienta. Ten klucz/klucz tajny dla aplikacji zapewnia też dostawcy interfejsu API dokładniejszą kontrolę nad dostępem do interfejsów API i bardziej szczegółowe raporty analityczne na temat ruchu API, ponieważ Edge wie, które tokeny OAuth należą do dewelopera i aplikacji.

Tworzenie programisty

Utwórzmy dewelopera o nazwie Nigel Tufnel.

  1. W menu kliknij Opublikuj > Programiści.
  2. Kliknij + Deweloper.
  3. W oknie Nowy programista wpisz te informacje:
    W tym polu Wejdź
    Imię Nigel
    Nazwisko Tufnel
    Nazwa użytkownika nigel
    Napisz e-maila nigel@example.com
  4. Kliknij Utwórz.

Zarejestruj aplikację

Stwórzmy aplikację dla Nigela.

  1. Wybierz Opublikuj > Aplikacje.
  2. Kliknij + Aplikacja.
  3. W oknie Nowa aplikacja wpisz te dane:
    W tym polu wykonaj to
    Name (Nazwa) i Display Name (Nazwa wyświetlana) Wpisz: nigel_app
    Deweloper Kliknij Programista i wybierz: Nigel Tufnel (nigel@example.com)
    Callback URL (URL wywołania zwrotnego) i Notes (Uwagi) Zostaw puste
  4. W sekcji Produkty kliknij Dodaj produkt.
  5. Wybierz helloworld_oauth2-Product.
  6. Kliknij Utwórz.

Pobieranie klucza i tajnego klucza klienta

Otrzymasz teraz klucz klienta i tajny klucz klienta, które zostaną wymienione na token dostępu OAuth.

  1. Upewnij się, że wyświetlana jest strona nigel_app. Jeśli nie, na stronie Aplikacje (Publikowanie > Aplikacje) kliknij nigel_app.
  2. Na stronie nigel_app kliknij Pokaż w kolumnach Klucz i Tajny. Zwróć uwagę, że klucz/klucz jest powiązany z zasobem „helloworld_oauth2-Product”, który został automatycznie utworzony wcześniej.

  3. Zaznacz i skopiuj klucz oraz obiekt tajny. Wklej ją w tymczasowym pliku tekstowym. Użyjesz ich w kolejnym kroku, czyli wywołaniu serwera proxy interfejsu API, który wymieni te dane logowania na token dostępu OAuth.

Spróbuj wywołać interfejs API, aby uzyskać swój adres IP (nie udało się)

Najpierw spróbuj wywołać serwer proxy chronionego interfejsu API, który powinien zwracać Twój adres IP. Wykonaj poniższe polecenie cURL w oknie terminala, zastępując nazwę organizacji Edge. Słowo test w adresie URL to środowisko testowe Twojej organizacji, które zostało przez Ciebie wdrożone na serwerach proxy. Ścieżka bazowa serwera proxy to /hellooauth2, czyli ta sama ścieżka, która została podana podczas tworzenia serwera proxy. Zwróć uwagę, że w wywołaniu nie przekazujesz tokena dostępu OAuth.

curl https://ORG_NAME-test.apigee.net/hellooauth2

Serwer proxy interfejsu API ma zasadę Zweryfikuj token dostępu OAuth w wersji 2.0 sprawdzającą w żądaniu, czy w żądaniu znajduje się prawidłowy token dostępu OAuth, więc wywołanie powinno zakończyć się błędem:

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

W tym przypadku porażka jest niekorzystna. Oznacza to, że serwer proxy interfejsu API jest znacznie bezpieczniejszy. Tylko zaufane aplikacje z prawidłowym tokenem dostępu OAuth mogą wywołać ten interfejs API.

Uzyskiwanie tokena dostępu OAuth

Dotarliśmy do wielkiego sukcesu. Zamierzasz użyć klucza i obiektu tajnego, które zostały skopiowane i wklejone do pliku tekstowego, i wymienisz je na token dostępu OAuth. Wywołasz teraz interfejs API oauth zaimportowanego przykładowego serwera proxy interfejsu API, co spowoduje wygenerowanie tokena dostępu interfejsu API.

Używając tego klucza i obiektu tajnego, wykonaj poniższe wywołanie cURL (zwróć uwagę, że protokół to https) i wstawiając w nim nazwę organizacji Edge, klucz i tajny klucz we wskazanych miejscach:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://ORG_NAME-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

Jeśli nawiązujesz połączenia, korzystając z klienta, takiego jak Postman, client_id i client_secret w treści żądania muszą mieć wartość x-www-form-urlencoded.

Odpowiedź powinna wyglądać tak:

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "nigel@example.com",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Otrzymujesz token dostępu OAuth. Skopiuj wartość tokenu dostępu (bez cudzysłowu) i wklej ją w pliku tekstowym. Za chwilę go użyjesz.

Co się właśnie stało?

Czy przyglądaliśmy się wcześniej przepływowi warunkowemu w serwerze proxy oauth – jeśli identyfikator URI zasobu to /accesstoken, a czasownik żądania to POST – aby wykonać zasadę GenerateAccessTokenClient OAuth generującą token dostępu. Polecenie cURL spełnia te warunki, więc zasada OAuth została wykonana. Zweryfikowano Twój klucz klienta i tajny klucz klienta oraz wymieniono je na token OAuth, który wygasa w ciągu 1 godziny.

Wywołaj interfejs API za pomocą tokena dostępu (powodzenie!)

Gdy masz już token dostępu, możesz go użyć do wywołania serwera proxy interfejsu API. Wykonaj poniższe wywołanie cURL. Zastąp nazwę organizacji Edge i token dostępu.

curl https://ORG_NAME-test.apigee.net/hellooauth2 -H "Authorization: Bearer TOKEN"

Powinno pojawić się udane wywołanie serwera proxy interfejsu API, który zwraca Twój adres IP. Na przykład:

{"ip":"::ffff:192.168.14.136"}

Możesz powtórzyć to wywołanie interfejsu API przez około godzinę, po czym token dostępu wygaśnie. Aby wykonać wywołanie po godzinie, musisz wygenerować nowy token dostępu zgodnie z poprzednimi krokami.

Gratulacje! Serwer proxy interfejsu API został utworzony i chroniony przez wymaganie, aby wywołanie zawierało prawidłowy token dostępu OAuth.

Powiązane artykuły