Implementowanie typu uwierzytelnienia kodu autoryzacji

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

Kod autoryzacji to jeden z najczęściej używanych typów uwierzytelniania OAuth 2.0. Przepływ kodu autoryzacji ma postać konfiguracji „trzyetapowej autoryzacji OAuth”. W tej konfiguracji użytkownik uwierzytelnia się na serwerze zasobów i wyraża zgodę na dostęp aplikacji do swoich zabezpieczonych zasobów bez ujawniania nazwy użytkownika i hasła aplikacji klienckiej.

O tym temacie

Ten temat zawiera ogólny opis i omówienie procesu uwierzytelniania przez OAuth 2.0 oraz sposób wdrażania tego procesu w Apigee Edge.

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak używać typu uwierzytelnienia OAuth 2.0 do zabezpieczania interfejsów API.

Przypadki użycia

Ten rodzaj przyznania jest przeznaczony dla aplikacji napisanych przez zewnętrznych deweloperów, którzy nie współpracują z zaufanym dostawcą interfejsu API. Na przykład deweloperzy rejestrujący się w publicznych programach dotyczących interfejsów API nie powinni być ogólnie zaufani. W przypadku tego typu uwierzytelnienia dane logowania użytkownika na serwerze zasobów nigdy nie są udostępniane aplikacji.

Przykładowy kod

Pełną, działającą przykładową implementację typu uwierzytelnienia kodu autoryzacji w Apigee Edge znajdziesz w repozytorium api-platform-samples na GitHubie. Zobacz przykładowy interfejs OAuth-advanced w katalogu api-platform-samples/sample-proxies. Szczegółowe informacje o przykładzie znajdziesz w pliku README.

Schemat blokowy

Poniższy diagram przedstawia przepływ kodu autoryzacji OAuth z Apigee Edge pełniącym funkcję 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.

Etapy przepływu kodu autoryzacji

Oto podsumowanie kroków wymaganych do zaimplementowania typu uwierzytelnienia kodu autoryzacji, w którym jako serwer autoryzacji działa Apigee Edge. Pamiętaj, że kluczem w tym procesie jest to, że klient nigdy nie widzi danych logowania użytkownika na serwerze zasobów.

Warunek wstępny: aby uzyskać identyfikator klienta i klucze tajnego klucza klienta, aplikacja klienta musi być zarejestrowana w Apigee Edge. Więcej informacji znajdziesz w sekcji Rejestrowanie aplikacji klienckich.

1. Użytkownik inicjuje proces

Gdy aplikacja chce uzyskać dostęp do chronionych zasobów użytkownika z serwera zasobów (np. listy kontaktów w witrynie mediów społecznościowych), wysyła do Apigee Edge wywołanie interfejsu API, które weryfikuje identyfikator klienta i, jeśli jest poprawny, przekierowuje przeglądarkę użytkownika do strony logowania, na której użytkownik wpisze swoje dane logowania. Wywołanie interfejsu API zawiera informacje, które aplikacja kliencka uzyskała w momencie rejestracji: identyfikator klienta i identyfikator URI przekierowania.

2. Użytkownik wpisuje dane logowania

Użytkownik widzi stronę logowania, na której musi podać 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 jego zasobów. Formularz zgody zwykle zawiera wybór zakresu, w którym użytkownik może zdecydować, co aplikacja może robić na serwerze zasobów. Na przykład użytkownik może przyznać aplikacji uprawnienia tylko do odczytu lub aktualizowanie zasobów.

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

Jeśli logowanie i prośba zostaną zaakceptowane, aplikacja do logowania przesyła dane POST do punktu końcowego /authorizationcode w Apigee Edge. Dane te obejmują identyfikator URI przekierowania, identyfikator klienta, zakres, wszelkie informacje dotyczące użytkownika, które chcesz uwzględnić, a także informację o udanym logowaniu.

5. Apigee Edge generuje kod autoryzacji

Gdy Edge otrzyma żądanie GET z aplikacji do logowania w punkcie końcowym /authorizationcode mają 2 wyniki. Najpierw Edge wykrywa, czy logowanie się udało (sprawdzając stan HTTP lub w inny sposób). Następnie Edge sprawdza, czy identyfikator URI przekierowania wysyłany z aplikacji do logowania jest zgodny z identyfikatorem URI przekierowania określonym podczas rejestracji aplikacji w Apigee Edge. Jeśli wszystko jest w porządku, Edge wygeneruje kod autoryzacji. Na przykład:

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

6. Edge wysyła kod autoryzacji z powrotem do klienta

Edge wysyła do klienta przekierowanie 302 z kodem autoryzacji załączonym jako parametr zapytania.

7. Klient pobiera kod autoryzacji i wysyła żądanie kodu dostępu z Edge

Teraz z prawidłowym kodem autoryzacji klient może zażądać tokena dostępu do Edge. Jest to możliwe dzięki POSTACI dostępu do identyfikatora klienta i kluczy tajnych klienta (uzyskanych podczas rejestracji aplikacji w Edge), typu uwierzytelnienia i zakresu. Dzięki uwzględnieniu identyfikatora klienta i kluczy obiektu tajnego Apigee Edge może sprawdzić, czy została zarejestrowana aplikacja klienta. 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'

8. Klient otrzymuje token dostępu

Jeśli wszystko zadziała, Edge zwraca token dostępu klienta. Token dostępu ma datę ważności i będzie ważny tylko w zakresie określonym przez użytkownika, gdy wyraził on zgodę na dostęp aplikacji do jego zasobów.

9. Klient wywołuje chroniony interfejs API

Teraz, przy zastosowaniu prawidłowego kodu dostępu, klient może wywoływać chroniony interfejs API. W tym scenariuszu żądania są wysyłane do Apigee Edge (serwera proxy) i Edge odpowiada za weryfikację tokena dostępu przed przekazaniem wywołania interfejsu API do docelowego serwera zasobów. Tokeny dostępu są przekazywane w nagłówku autoryzacji. 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 przetworzyć wiele żądań OAuth: tokeny dostępu, kody uwierzytelniania, tokeny odświeżania, przekierowania na stronę logowania itp. Aby skonfigurować te punkty końcowe, musisz wykonać 2 podstawowe kroki:

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

Konfiguracja przepływu niestandardowego

Zwykle konfiguruje się ten przepływ w taki sposób, że każdy krok lub „etap” procesu jest definiowany przez przepływ w serwerze proxy Apigee Edge. Każdy przepływ ma punkt końcowy i zasadę, która wykonuje wymagane zadanie związane z OAuth, takie jak generowanie kodu autoryzacji lub tokena dostępu. Na przykład, jak widać w poniższym kodzie XML, z punktem końcowym /oauth/authorizationcode jest powiązana zasada o nazwie GenerateAuthCode (jest to zasada OAuthV2 z określoną operacją GenerateAuthorizationCode).

Najprostszym sposobem pokazania konfiguracji przepływu jest użycie przykładu XML. Informacje o każdym procesie znajdziesz w komentarzach w tekście. To przykład – nazwy przepływów i ścieżek możesz konfigurować w dowolny sposób. Przeczytaj też artykuł o konfigurowaniu punktów końcowych i zasad OAuth, by szybko zapoznać się z krokami niezbędnymi do utworzenia przepływu niestandardowego.

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

Z każdym punktem końcowym jest powiązana zasada. Przyjrzyjmy się przykładowym zasadom. Przeczytaj też artykuł o konfigurowaniu punktów końcowych i zasad OAuth, z którego dowiesz się, co trzeba zrobić, aby dodać zasady OAuthV2 do punktów końcowych serwera proxy.

Przekierowanie logowania

To jest ścieżka /oauth/authorize. Dołączona zasada odpowiada za przekierowanie użytkownika do aplikacji do logowania, w której może on bezpiecznie uwierzytelnić się i autoryzować aplikację kliencką do uzyskiwania dostępu do swoich zabezpieczonych zasobów bez ujawniania nazwy użytkownika i hasła w aplikacji klienckiej. Można to zrobić za pomocą zasad dotyczących wywołań usługi, języka JavaScript, środowiska Node.js lub innych metod.

Wywołanie interfejsu API umożliwiające wykonanie żądania jest metodą GET i wymaga parametrów zapytania client_id, response_type, redirect_uri, zakresu i stanu.

$ 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}

Uzyskaj kod autoryzacji

To jest ś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 mające na celu uzyskanie kodu autoryzacji jest metodą GET i wymaga parametrów zapytania client_id, response_type oraz opcjonalnie zakresu i stanu, jak w tym przykładzie:

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

Uzyskaj token dostępu

Ta zasada jest dołączona do ścieżki /oauth/accesstoken. Używa w niej zasady OAuthV2 z określoną operacją GenerateAccessCode. 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 umożliwiające uzyskanie kodu dostępu jest żądaniem POST. Musi ono zawierać parametr client_id, client_secret, grant_type=authorization_code oraz opcjonalnie zakres. Na przykład:

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

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

Dołączam zasadę dotyczącą tokenów weryfikacji dostępu

Dołącz zasadęVerifyAccessToken (zasada OAuthV2 z określoną operacjami ConfirmAccessToken) na początku każdego procesu, który uzyskuje dostęp do chronionego interfejsu API, aby była ona wykonywana za każdym razem, gdy pojawi się żądanie chronionych zasobów. Edge sprawdza, czy każde żądanie ma prawidłowy token dostępu. W przeciwnym razie zwracany jest błąd. Instrukcje podstawowe znajdziesz w artykule Weryfikowanie 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 przez uwierzytelnianie OAuth 2.0, musisz przedstawić prawidłowy token dostępu. Prawidłowy wzór należy umieścić w nagłówku Authorization w następujący sposób: Uwaga: 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.