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

Praca z zakresami OAuth2

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

W tym temacie omawiamy korzystanie z zakresów OAuth 2.0 w Apigee Edge.

Co to jest zakres OAuth2?

Zakresy protokołu OAuth 2.0 umożliwiają ograniczenie zakresu dostępu, który jest przyznawany dostępowi token. Na przykład token dostępu wydany aplikacji klienckiej może mieć uprawnienia do ODCZYTU i ZAPISU do zasobów chronionych lub tylko do ODCZYTU. Możesz wdrożyć interfejsy API, aby egzekwować dowolny zakres lub z dowolną kombinacją zakresów. Jeśli więc klient otrzyma token z zakresem READ, spróbuje wywołać punkt końcowy API, który wymaga dostępu do ZAPISU, wywołanie zakończy się niepowodzeniem.

W tym temacie omówimy, w jaki sposób są przypisywane zakresy do tokenów dostępu i jak Apigee Edge wymusza zakresy protokołu OAuth 2.0. Po przeczytaniu tego tematu będziesz mógł używać zakresów z pewność siebie.

W jaki sposób zakresy są przypisywane do tokenów dostępu?

Gdy Edge generuje token dostępu, może przypisać do niego zakres. Aby dowiedzieć się, jak to zrobić, najpierw musisz zapoznać się z tymi encjami Apigee Edge: usługami API, deweloperów i aplikacje dla deweloperów. Wprowadzenie do publikowania znajdziesz w artykule Wprowadzenie do publikowania. Zalecamy zapoznaj się z tymi materiałami, zanim przejdziesz dalej.

Token dostępu to długi ciąg przypadkowych znaków, który umożliwia Edge weryfikację przychodzących żądań do interfejsu API (jako zastęp nazwy użytkownika/hasła). Technicznie rzecz biorąc, token to klucz odnoszący się do zbioru takie metadane:

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Metadane tokena zawierają rzeczywisty ciąg tokena dostępu, informacje o wygaśnięciu dane aplikacji i dewelopera oraz produktów powiązanych z tokenem. Za Zwróć uwagę, że metadane zawierają też „zakres”.

W jaki sposób token uzyskuje zakres?

Pierwszym krokiem do zrozumienia zakresu jest zapamiętanie, że każdy produkt w aplikacji nie mieć przypisanych 0 lub więcej zakresów. Zakresy te można przypisać, gdy usługa jest ale można też dodać je później. Mają formę listy nazw i są uwzględnione w „metadane” powiązane z każdym produktem.

Gdy utworzysz aplikację dewelopera i dodasz do niej produkty, Edge sprawdzi wszystkie produkty w w aplikacji dewelopera i tworzy listę wszystkich zakresów tych produktów (główny lub główny globalna lista zakresów – sumę wszystkich rozpoznanych zakresów).

Gdy aplikacja kliencka prosi o token dostępu z Apigee Edge, może opcjonalnie określić, który które ma być powiązane z tym tokenem. Na przykład poniższe żądanie dotyczy dla zakresu „A”. Oznacza to, że klient prosi serwer autoryzacji (Edge) o wygenerowanie token dostępu z zakresem „A” (upoważnienie aplikacji do wywoływania interfejsów API z zakresem „A”). Aplikacja wysyła takie żądanie POST:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A

Co się dzieje

Gdy Edge otrzyma to żądanie, wie, która aplikacja je zgłasza, i wie, która zarejestrowaną przez klienta (identyfikator klienta i klucze tajnego klienta są kodowane w sekcji nagłówek uwierzytelniania podstawowego). Ponieważ dołączony jest parametr zapytania scope, Edge musi: określić, czy któryś z usług API powiązanych z aplikacją dewelopera ma zakres „A”. Jeśli tak, token dostępu zostanie wygenerowany z zakresem „A”. Innym spojrzeniem na tę kwestię jest to, że zakres jest rodzajem filtra. Jeśli aplikacja dewelopera rozpoznaje zakresy „A, B, X” oraz parametr zapytania określa zakres „scope=X Y Z”, a następnie tylko zakres „X” zostanie przypisany do token.

Co się stanie, jeśli klient nie dołączy parametru zakresu? W tym przypadku Edge generuje token. obejmujący wszystkie zakresy rozpoznawane przez aplikację dewelopera. Jest trzeba zrozumieć, że domyślnym działaniem jest zwrócenie tokena dostępu zawierającego dla wszystkich usług zawartych w aplikacji dla deweloperów.

Jeśli żaden z produktów powiązanych z aplikacją dewelopera nie określa zakresów, a token ma takie zakresy zakres, wywołania wykonywane za pomocą tego tokena zakończą się niepowodzeniem.

Załóżmy, że aplikacja dewelopera rozpoznaje te zakresy: A B C D. To jest główna lista aplikacji i zakresu. Może się zdarzyć, że jeden produkt w aplikacji ma zakres A i B, a drugi zakres C. i D lub dowolną kombinację tych opcji. Jeśli klient nie określa parametru scope (lub jeśli określa parametr zakresu bez wartości) token otrzyma wszystkie 4 zakresy: A, B, C, i D. Token również otrzymuje zestaw zakresów, który stanowi sumę wszystkich rozpoznanych zakresów. przez aplikację dewelopera.

Jest jeszcze jeden przypadek, w którym domyślnym działaniem jest zwrócenie tokena dostępu ze wszystkimi rozpoznanych zakresów. W takim przypadku zasada GenerateAccessToken (zasada Apigee Edge, (generowanie tokenów dostępu)) nie określa elementu <Scope>. Oto na przykład zasada GenerateAccessToken, w której <Scope> jest określony. Jeśli brakuje tego elementu <Scope> (lub jest on niedostępny) jest obecne, ale puste), wykonywane jest domyślne zachowanie.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Jak są egzekwowane zakresy?

Po pierwsze pamiętaj, że w Apigee Edge tokeny dostępu są weryfikowane z użyciem zasady OAuthV2 (zwykle jest umieszczany na samym początku przepływu serwera proxy). Zasada musi zawierać Określono operację VerifyAccessToken. Przyjrzyjmy się tym zasadom:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

Zwróć uwagę na element <Scope>. Służy do określania zakresów, .

W tym przykładzie zasada jest skuteczna tylko wtedy, gdy token dostępu zawiera zakres „A”. Jeśli <Scope> zostanie pominięty, a jeśli nie ma on wartości, zasada ignoruje zakres argumentu token dostępu.

Teraz, dzięki możliwości weryfikowania tokenów dostępu na podstawie zakresu, możesz tak zaprojektować interfejsy API, wymuszają określone zakresy. W tym celu należy projektować niestandardowe przepływy za pomocą tokena VerifyAccessToken rozpoznającego zakres powiązane z nimi zasady.

Załóżmy, że w interfejsie API jest zdefiniowany proces dla punktu końcowego /resourceA:

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

Po wywołaniu tego przepływu (żądanie przychodzi z parametrem /resourceA w ścieżce). sufiks), zasada OAuthV2-VerifyAccessTokenA jest wywoływana natychmiast. Ta zasada potwierdza, że token dostępu jest prawidłowy i sprawdza, jakie zakresy obsługuje token. Jeśli zasada to skonfigurowany zgodnie z poniższym przykładem z wartością <Scope>A</Scope> zasada jest udana tylko jeśli token dostępu ma zakres „A”. W przeciwnym razie zwraca błąd.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Podsumowując, za projektowanie egzekwowania zakresów w interfejsach API odpowiadają deweloperzy interfejsów API. Aby to zrobić, tworzą niestandardowe przepływy do obsługi określonych zakresów i dołączając do tokena VerifyAccessToken do egzekwowania tych zakresów.

Przykłady kodu

Na koniec spójrzmy na kilka przykładowych wywołań interfejsu API, aby pokazać, jak otrzymują tokeny zakresów i sposobu ich egzekwowania.

Domyślna wielkość liter

Załóżmy, że masz aplikację dewelopera z produktami i że ich związek zakresy to A, B i C. To wywołanie interfejsu API żąda tokena dostępu, ale nie określa zapytania dotyczącego zakresu .

curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials

W tym przypadku wygenerowany token otrzyma zakresy A, B i C (działanie domyślne). metadane tokena wyglądają mniej więcej tak:

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

A teraz załóżmy, że masz punkt końcowy API, który ma zakres „A”. (czyli jest to VerifyAccessToken wymaga zakresu „A”). Oto zasada VerifyAccessToken:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Oto przykładowe wywołanie i punkt końcowy, który wymusza zakres A:

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA

Udało się wykonać to wywołanie GET:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

Udało się, ponieważ zasada VerifyAccessToken jest aktywowana po wywołaniu punktu końcowego wymaga zakresu A, a token dostępu otrzymał zakresy A, B i C – domyślne zachowanie użytkownika.

Przypadek filtrowania

Załóżmy, że masz aplikację dewelopera z produktami, które mają zakresy A, B, C i X. Ty prosisz token dostępu i uwzględnij parametr zapytania scope w ten sposób:

curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'

W tym przypadku wygenerowany token otrzyma zakresy A i X, ponieważ zarówno A, jak i X są prawidłowych zakresów. Pamiętaj, że aplikacja dewelopera rozpoznaje zakresy A, B, C i X. W tym przypadku filtrujesz listę usług API na podstawie tych zakresów. Jeśli produkt ma zakres A lub X, możesz skonfigurować punkty końcowe interfejsu API, które wymuszają te zakresy. Jeśli produkt nie ma zakresu A lub X (załóżmy,że ma B, C i Z), to interfejsy API wymuszające zakresy A lub X nie mogą być wywoływane używając tokena.

Gdy wywołujesz interfejs API przy użyciu nowego tokena:

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX

Token dostępu jest weryfikowany przez serwer proxy interfejsu API. Na przykład:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Aktywatory wywołania GET działają poprawnie i zwracają odpowiedź. Na przykład:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

Udało się, ponieważ zasada VerifyAccessToken wymaga zakresu A lub X oraz tokena dostępu obejmuje zakres A i X. Jeśli element <Scope> był ustawiony na „B”, nie uda się wykonać tego połączenia.

Podsumowanie

Ważne jest, aby zrozumieć, jak Apigee Edge obsługuje zakresy OAuth 2.0. Oto najważniejsze wnioski pkt.:

Aplikacja dewelopera „rozpoznaje” sumę wszystkich zakresów zdefiniowanych dla wszystkich jej usług.
Gdy aplikacja żąda tokena dostępu, może określić, które zakresy które chcieliby mieć. To Apigee Edge (serwer autoryzacji) określa, które jej zakresy zostanie faktycznie przypisany do tokena dostępu na podstawie (a) żądanych zakresów oraz (b) jeśli są rozpoznawane przez aplikację dewelopera.
Jeśli Apigee Edge nie jest skonfigurowana do sprawdzania zakresu (element <Scope> brakuje w zasadzie VerifyAccessToken lub jest ona pusta), wywołanie interfejsu API zostanie prawidłowo o ile zakres umieszczony w tokenie dostępu pasuje do jednego z zakresów rozpoznanych przez zarejestrowana aplikacja dewelopera (jeden z zakresów na liście zakresów „master” aplikacji).
Jeśli z tokenem dostępu nie są powiązane żadne zakresy, zostanie on przyznany tylko wtedy, w przypadkach, gdy Edge nie uwzględnia zakresu (brak elementu <Scope>) z zasady VerifyAccessToken lub jest pusty).