Implementowanie typu uwierzytelnienia kodu autoryzacji

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Kod autoryzacji jest jednym z najczęściej używanych typów przyznawania uprawnień OAuth 2.0. Procedura kodu autoryzacji to konfiguracja „trzyskładnikowego uwierzytelniania OAuth”. W tej konfiguracji użytkownik uwierzytelnia się na serwerze zasobów i wyraża zgodę na dostęp aplikacji do chronionych zasobów bez ujawniania nazwy użytkownika ani hasła aplikacji klienckiej.

O tym temacie

W tym temacie znajdziesz ogólny opis i omówienie procedury typu przyznawania uprawnień OAuth 2.0 oraz dowiesz się, jak zaimplementować tę procedurę w Apigee Edge.

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak zabezpieczyć interfejsy API za pomocą typu przyznawania uprawnień OAuth 2.0.

Przypadki użycia

Ten typ przyznawania uprawnień jest przeznaczony dla aplikacji napisanych przez deweloperów zewnętrznych, którzy nie mają zaufanych relacji biznesowych z dostawcą interfejsu API. Na przykład deweloperzy, którzy rejestrują się w publicznych programach interfejsu API, nie powinni być traktowani jako zaufani. W przypadku tego typu przyznawania uprawnień dane logowania użytkownika na serwerze zasobów nigdy nie są udostępniane aplikacji.

Przykładowy kod

Kompletną, działającą przykładową implementację typu przyznawania uprawnień kodu autoryzacji w Apigee Edge znajdziesz w api-platform-samples repozytorium na GitHubie. Zobacz przykład oauth-advanced sample w katalogu api-platform-samples/sample-proxies. Szczegółowe informacje o przykładzie znajdziesz w pliku README.

Diagram przepływu

Poniższy diagram przepływu ilustruje przepływ OAuth kodu autoryzacji, w którym Apigee Edge pełni rolę serwera autoryzacji.

Wskazówka: aby wyświetlić większą wersję tego diagramu, kliknij go prawym przyciskiem myszy i otwórz w nowej karcie lub zapisz i otwórz w przeglądarce obrazów.

Kroki w przepływie kodu autoryzacji

Oto podsumowanie kroków wymaganych do zaimplementowania typu przyznawania uprawnień kodu autoryzacji, w którym Apigee Edge pełni rolę serwera autoryzacji. Pamiętaj, że kluczem do tej procedury jest to, że klient nigdy nie widzi danych logowania użytkownika na serwerze zasobów.

Wymaganie wstępne: aplikacja kliencka musi być zarejestrowana w Apigee Edge, aby uzyskać identyfikator i tajny klucz klienta. Więcej informacji znajdziesz w artykule Rejestrowanie aplikacji klienckich.

1. Użytkownik inicjuje procedurę

Gdy aplikacja potrzebuje dostępu do chronionych zasobów użytkownika z serwera zasobów (np. listy kontaktów w witrynie mediów społecznościowych), wysyła wywołanie interfejsu API do Apigee Edge, który sprawdza identyfikator klienta i, jeśli jest prawidłowy, przekierowuje przeglądarkę użytkownika na stronę logowania, na której użytkownik wpisuje swoje dane logowania. Wywołanie interfejsu API zawiera informacje, które aplikacja kliencka uzyskała podczas rejestracji: identyfikator klienta i identyfikator URI przekierowania.

2. Użytkownik wpisuje dane logowania

Użytkownik widzi teraz stronę logowania, na której musi wpisać swoje dane logowania. Jeśli logowanie się powiedzie, przejdziemy do następnego kroku.

3. Użytkownik wyraża zgodę

W tym kroku użytkownik wyraża zgodę na dostęp aplikacji do swoich zasobów. Formularz zgody zwykle zawiera opcje zakresu, w których użytkownik może wybrać, co aplikacja może robić na serwerze zasobów. Użytkownik może na przykład przyznać uprawnienia tylko do odczytu lub uprawnienia do aktualizowania zasobów.

4. Aplikacja logowania wysyła żądanie do Apigee Edge

Jeśli logowanie i zgoda się powiodą, aplikacja logowania wysyła dane POST do punktu końcowego /authorizationcode w Apigee Edge. Dane obejmują identyfikator URI przekierowania, identyfikator klienta, zakres, wszelkie informacje o użytkowniku , które chce uwzględnić, oraz informację o tym, że logowanie się powiodło.

5. Apigee Edge generuje kod autoryzacji

Gdy Edge otrzyma żądanie POST z aplikacji logowania w punkcie końcowym /authorizationcode, dzieją się 2 rzeczy. Po pierwsze, Edge stwierdza, że logowanie się powiodło (sprawdzając parametry lub nagłówki żądania pod kątem wskaźnika powodzenia). Następnie Edge sprawdza, czy identyfikator URI przekierowania wysłany z aplikacji logowania jest zgodny z identyfikatorem URI przekierowania określonym podczas rejestracji aplikacji w Apigee Edge. Jeśli wszystko jest w porządku, Edge generuje kod autoryzacji.

{redirect_uri}?code={authorization_code}&state={some_string}

6. Klient pobiera kod autoryzacji i wysyła do Edge żądanie tokena dostępu

Teraz, gdy klient ma prawidłowy kod autoryzacji, może poprosić Edge o token dostępu. W tym celu wysyła POST z identyfikatorem klienta i tajnym kluczem klienta (uzyskanym podczas rejestracji aplikacji w Edge), kodem autoryzacji, typem przyznawanych uprawnień i zakresem. Dzięki identyfikatorowi klienta i tajnemu kluczowi klienta Apigee Edge może sprawdzić czy aplikacja kliencka jest tą, która została zarejestrowana. Na przykład:

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

7. Klient otrzymuje token dostępu

Jeśli wszystko się powiedzie, Edge zwraca klientowi token dostępu. Token dostępu będzie miał datę ważności i będzie ważny tylko w zakresie określonym przez użytkownika, gdy wyraził zgodę na dostęp aplikacji do swoich zasobów.

8. Klient wywołuje chroniony interfejs API

Teraz, gdy klient ma prawidłowy token dostępu, może wywoływać chroniony interfejs API. W tym scenariuszu żądania są wysyłane do Apigee Edge (proxy), a Edge odpowiada za sprawdzenie tokena dostępu przed przekazaniem wywołania interfejsu API do docelowego serwera zasobów. Tokeny dostępu są przekazywane w nagłówku Authorization. Na przykład:

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

Konfigurowanie przepływów i zasad

Jako serwer autoryzacji Edge musi przetwarzać wiele żądań OAuth: tokenów dostępu , kodów autoryzacji, tokenów odświeżania, przekierowań na stronę logowania itp. Aby skonfigurować te punkty końcowe, musisz wykonać 2 podstawowe kroki:

  • Tworzenie niestandardowych przepływów
  • Dodawanie i konfigurowanie zasad OAuthV2

Konfiguracja przepływu niestandardowego

Zwykle konfigurujesz ten typ przyznawania uprawnień tak, aby każdy krok lub "odcinek" przepływu był definiowany przez przepływ w proxy Apigee Edge. Każdy przepływ ma punkt końcowy i zasadę, która wykonuje wymagane zadanie związane z OAuth, np. generowanie kodu autoryzacji lub tokena dostępu. Na przykład, jak pokazano w poniższym kodzie XML, punkt końcowy /oauth/authorizationcode ma powiązaną zasadę o nazwie GenerateAuthCode (która jest zasadą OAuthV2 z określoną operacją GenerateAuthorizationCode).

Najłatwiej jest pokazać konfigurację przepływu za pomocą przykładu XML. Informacje o każdym przepływie znajdziesz w komentarzach w tekście. To jest przykład – nazwy przepływów i ścieżki można skonfigurować w dowolny sposób. Aby szybko zapoznać się z krokami wymaganymi do utworzenia takiego przepływu niestandardowego, zobacz też Konfigurowanie punktów końcowych i zasad OAuth.

Zobacz też przykładową implementację na GitHubie. 

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

Konfigurowanie przepływów za pomocą zasad

Każdy punkt końcowy ma powiązaną z nim zasadę. Zobaczmy przykłady zasad. Aby szybko zapoznać się z krokami wymaganymi do dodania zasad OAuthV2 do punktów końcowych proxy, zobacz też Konfigurowanie punktów końcowych i zasad OAuth.

Przekierowanie logowania

Jest to ścieżka /oauth/authorize. Dołączona zasada odpowiada za przekierowanie użytkownika do aplikacji logowania, w której użytkownik może bezpiecznie uwierzytelnić się i autoryzować aplikację kliencką do uzyskiwania dostępu do swoich chronionych zasobów bez ujawniania nazwy użytkownika i hasła aplikacji klienckiej. Możesz to zrobić za pomocą zasady wywołania usługi, JavaScriptu, Node.js lub innych środków.

Wywołanie interfejsu API do wykonania żądania to GET i wymaga parametrów zapytania client_id, response_type, redirect_uri, scope i state.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

Pobierz kod autoryzacji

Jest to ścieżka /oauth/authorizationcode. Używa zasady OAuthV2 z określoną operacją GenerateAuthorizationCode.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

Wywołanie interfejsu API w celu uzyskania kodu autoryzacji to POST i wymaga przekazania w treści żądania jako parametrów formularza parametrów client_id, response_type, redirect_uri oraz opcjonalnie scope i state, jak pokazano w tym przykładzie:

$ curl http://myorg-test.apigee.net/oauth/authorizationcode -X POST -d 'client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}'

Uzyskaj token dostępu

Ta zasada jest dołączona do ścieżki /oauth/accesstoken. Używa zasady OAuthV2 z określoną operacją GenerateAccessToken. W tym przypadku parametr grant_type jest oczekiwany jako parametr zapytania:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn>
    <SupportedGrantTypes>
        <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

Wywołanie interfejsu API w celu uzyskania tokena dostępu to POST i musi zawierać kod autoryzacji, client_id, client_secret, grant_type=authorization_code oraz opcjonalnie scope. Na przykład:

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

To tylko podstawowe podsumowanie. Przykład produkcyjny obejmuje wiele innych zasad dotyczących tworzenia adresów URL, przeprowadzania transformacji i wykonywania innych zadań. Kompletny, działający projekt znajdziesz w przykładzie na GitHubie.

Dołączanie zasady sprawdzania tokena dostępu

Dołącz zasadę VerifyAccessToken (zasadę OAuthV2 z określoną operacją VerifyAccessToken ) na początku każdego przepływu, który uzyskuje dostęp do chronionego interfejsu API, aby była wykonywana za każdym razem, gdy nadejdzie żądanie chronionych zasobów. Edge sprawdza, czy każde żądanie ma prawidłowy token dostępu. Jeśli nie, zwracany jest błąd. Podstawowe kroki znajdziesz w artykule Sprawdzanie tokenów dostępu. 

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

Wywoływanie chronionego interfejsu API

Aby wywołać interfejs API chroniony za pomocą zabezpieczeń OAuth 2.0, musisz przedstawić prawidłowy token dostępu. Prawidłowy wzorzec polega na dołączeniu tokena w nagłówku Authorization w ten sposób: pamiętaj że token dostępu jest też nazywany „tokenem okaziciela”. 

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

Zobacz też Wysyłanie tokena dostępu.