Zasady OAuthV2

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

Co

OAuthV2 to wieloaspektowa zasada służąca do wykonywania operacji typu uwierzytelniania OAuth 2.0. Jest to podstawowa zasada używana do konfigurowania punktów końcowych OAuth 2.0 w Apigee Edge.

Wskazówka: więcej informacji o protokole OAuth w Apigee Edge znajdziesz na stronie głównej OAuth. Znajdziesz w niej linki do zasobów, przykładów, filmów i innych treści. Zobacz przykład zaawansowanego protokołu OAuth na GitHubie, aby zobaczyć, jak ta zasada jest używana w działającej aplikacji.

Przykłady

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

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

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

Zobacz też „Kodowanie podstawowych danych uwierzytelniających”.

Dokumentacja elementu

Dokumentacja zasad zawiera opis elementów i atrybutów zasady OAuthV2.

Przykładowa zasada przedstawiona poniżej to jedna z wielu możliwych konfiguracji. Ten przykład pokazuje zasadę OAuthV2 skonfigurowaną na potrzeby operacji GenerateAccessToken. Zawiera elementy wymagane i opcjonalne. Szczegółowe informacje znajdziesz w opisach elementów w tej sekcji.

<OAuthV2 name="GenerateAccessToken">
  <!-- 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>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

Atrybuty <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

Tabela poniżej zawiera opis atrybutów wspólnych dla wszystkich elementów nadrzędnych zasad:

Element <DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

Domyślnie VerificationAccessToken oczekuje, że token dostępu zostanie wysłany w nagłówku Authorization. Za pomocą tego elementu możesz zmienić to ustawienie. Na przykład request.queryparam.access_token wskazuje, że token dostępu powinien być obecny jako parametr zapytania o nazwie access_token.

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

Element <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Domyślnie VerificationAccessToken wymaga, aby token dostępu został wysłany w nagłówku autoryzacji jako token okaziciela. Na przykład:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Obecnie jedynym obsługiwanym prefiksem jest nośnik.

Element <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Jeśli identyfikator użytkownika aplikacji musi być wysłany do serwera autoryzacji, ten element pozwala określić, gdzie Edge ma szukać identyfikatora użytkownika. Można go wysłać na przykład jako parametr zapytania lub w nagłówku HTTP.

Na przykład request.queryparam.app_enduser wskazuje, że parametr AppEndUser powinien być obecny jako parametr zapytania, np. ?app_enduser=ntesla@theramin.com. Aby na przykład wymagać elementu AppEndUser w nagłówku HTTP, ustaw tę wartość na request.header.app_enduser.

Udostępnienie tego ustawienia umożliwia uwzględnianie w tokenie dostępu identyfikatora użytkownika aplikacji. Ta funkcja jest przydatna, jeśli chcesz mieć możliwość pobierania lub unieważniania tokenów dostępu OAuth 2.0 według identyfikatora użytkownika. Więcej informacji znajdziesz w artykule o włączaniu pobierania i unieważniania tokenów dostępu OAuth 2.0 według identyfikatora użytkownika, identyfikatora aplikacji lub obu tych parametrów.

<Atrybuty/atrybut>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Za pomocą tego elementu możesz dodać atrybuty niestandardowe do tokena dostępu lub kodu autoryzacji. Możesz na przykład umieścić w tokenie dostępu identyfikator użytkownika lub sesji, który można wyodrębnić i sprawdzić w czasie działania.

Ten element umożliwia określenie wartości w zmiennej przepływu lub ciągu literału. Jeśli podasz zarówno zmienną, jak i ciąg znaków, zostanie użyta wartość określona w zmiennej przepływu. Jeśli nie można rozpoznać zmiennej, zwracany jest ciąg znaków domyślny.

Więcej informacji o używaniu tego elementu znajdziesz w artykule o dostosowywaniu tokenów i kodów autoryzacji.

Wyświetlanie lub ukrywanie atrybutów niestandardowych w odpowiedzi

Pamiętaj, że jeśli ustawisz element GenerateResponse tej zasady na wartość true, w odpowiedzi zostanie zwrócona pełna reprezentacja tokena w formacie JSON razem z wszelkimi ustawionymi atrybutami niestandardowymi. W niektórych przypadkach możesz ukryć niektóre lub wszystkie atrybuty niestandardowe w odpowiedzi, aby nie były widoczne dla aplikacji klienckich.

Domyślnie atrybuty niestandardowe pojawiają się w odpowiedzi. Jeśli chcesz je ukryć, możesz ustawić dla parametru display wartość false. Na przykład:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Wartość atrybutu display nie została zachowana. Załóżmy, że generujesz token dostępu z atrybutami niestandardowymi, które chcesz ukryć w wygenerowanej odpowiedzi. Ustawienie display=false pozwala osiągnąć ten cel. Jeśli jednak później zostanie wygenerowany nowy token dostępu za pomocą tokena odświeżania, pierwotne atrybuty niestandardowe z tokena dostępu pojawią się w odpowiedzi tokena odświeżania. Dzieje się tak, ponieważ Edge nie zapamiętuje, że atrybut display był pierwotnie ustawiony na false w zasadach generowania tokenów dostępu – atrybut niestandardowy jest po prostu częścią metadanych tokena dostępu.

Podobnie będzie, jeśli dodasz do kodu autoryzacji atrybuty niestandardowe – gdy token dostępu zostanie wygenerowany za pomocą tego kodu, atrybuty niestandardowe pojawią się w odpowiedzi tokena dostępu. Pamiętaj, że może to nie być zgodne z Twoimi oczekiwaniami.

Aby ukryć atrybuty niestandardowe w takich przypadkach, masz do wyboru te opcje:

• Wyraźnie zresetuj atrybuty niestandardowe w zasadzie tokenów odświeżania i ustaw ich wyświetlanie na false (fałsz). W takim przypadku może być konieczne pobranie oryginalnych wartości niestandardowych z pierwotnego tokena dostępu za pomocą zasady GetOAuthV2Info.
• Użyj zasady JavaScript przetwarzania po przetwarzaniu, aby ręcznie wyodrębnić atrybuty niestandardowe, których nie chcesz widzieć w odpowiedzi.

Zobacz też Dostosowywanie tokenów i kodów autoryzacji.

Element <ClientId>

<ClientId>request.formparam.client_id</ClientId>

W kilku przypadkach aplikacja kliencka musi wysłać identyfikator klienta do serwera autoryzacji. Ten element pozwala określić, gdzie Edge ma szukać identyfikatora klienta. Jedyną prawidłową lokalizacją, jaką możesz ustawić, jest lokalizacja domyślna, czyli zmienna przepływu request.formparam.client_id. Ustawienie ClientId na dowolną inną zmienną nie jest obsługiwane. Zobacz też Wysyłanie prośby o tokeny dostępu i kody autoryzacji.

Element <Code>

<Code>request.queryparam.code</Code>

W procedurze typu uwierzytelnienia autoryzacji klient musi przesłać kod autoryzacji do serwera autoryzacji (Apigee Edge). Ten element pozwala określić, gdzie Edge ma szukać kodu autoryzacji. Możesz go na przykład wysłać jako parametr zapytania, nagłówek HTTP lub parametr formularza (domyślnie).

Zmienna request.queryparam.auth_code wskazuje, że kod autoryzacji powinien znajdować się jako parametr zapytania, np. ?auth_code=AfGlvs9. Aby na przykład wymagać kodu autoryzacji w nagłówku HTTP, ustaw tę wartość na request.header.auth_code. Zapoznaj się też z prośbą o tokeny dostępu i kody autoryzacji.

Element<ExpiresIn>

<ExpiresIn>10000</ExpiresIn> 

Wymusza wygaśnięcie tokenów dostępu i kodów autoryzacji (w milisekundach). W przypadku tokenów odświeżania użyj <RefreshTokenExpiresIn>. Wartość wygaśnięcia ważności to wartość wygenerowana przez system plus wartość <ExpiresIn>. Jeśli <ExpiresIn> ma wartość -1, token lub kod wygasa zgodnie z maksymalnym czasem wygaśnięcia tokena dostępu OAuth. Jeśli zasada <ExpiresIn> nie jest określona, system stosuje wartość domyślną skonfigurowaną na poziomie systemu.

Czas wygaśnięcia można też ustawić w czasie działania za pomocą zakodowanej na stałe wartości domyślnej lub przez odwołanie do zmiennej przepływu. Możesz na przykład zapisać wartość wygaśnięcia tokena w mapie par klucz-wartość, pobrać ją, przypisać do zmiennej i odwołać się do niej w zasadzie. Na przykład: kvm.oauth.expires_in.

W przypadku Apigee Edge dla chmury publicznej Edge przechowuje następujące encje w pamięci podręcznej przez co najmniej 180 sekund po uzyskaniu dostępu do encji.

• tokeny dostępu OAuth. Oznacza to, że unieważniony token może nadal działać przez maksymalnie 3 minuty, aż do wygaśnięcia limitu pamięci podręcznej.
• Jednostki usługi zarządzania kluczami (KMS) (aplikacje, deweloperzy, produkty API).
• Atrybuty niestandardowe tokenów OAuth i encji KMS.

Poniższa sekcja określa też zmienną przepływu i wartość domyślną. Pamiętaj, że wartość zmiennej przepływu ma pierwszeństwo przed określoną wartością domyślną.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Edge nie obsługuje sposobu wymuszania wygaśnięcia tokena po jego utworzeniu. Jeśli musisz wymusić wygaśnięcie tokena (na przykład na podstawie warunku), możliwe rozwiązanie znajdziesz w tym poście w społeczności Apigee.

Domyślnie wygasłe tokeny dostępu są automatycznie usuwane z systemu Apigee Edge po 3 dniach po wygaśnięciu. Zobacz też Trwałe usuwanie tokenów dostępu

Private Cloud: w przypadku instalacji Edge dla Private Cloud wartość domyślną jest ustawiana przez właściwość conf_keymanagement_oauth_auth_code_expiry_time_in_millis. Aby ustawić tę właściwość:

1. Otwórz plik message-processor.properties w edytorze. Jeśli plik nie istnieje, utwórz go:

   vi /opt/apigee/customer/application/message-processor.properties

2. Ustaw odpowiednią usługę:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Upewnij się, że plik właściwości należy do użytkownika „apigee”:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Ponownie uruchom procesor wiadomości.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Element <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Informuje Apigee Edge, gdzie znajduje się zewnętrzny token dostępu (token dostępu, który nie został wygenerowany przez Apigee Edge).

Zmienna request.queryparam.external_access_token wskazuje, że zewnętrzny token dostępu powinien być obecny jako parametr zapytania, np. ?external_access_token=12345678. Aby na przykład wymagać tokena dostępu zewnętrznego w nagłówku HTTP, ustaw tę wartość na request.header.external_access_token. Zapoznaj się też z informacjami o używaniu tokenów OAuth innych firm.

Element <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Jeśli ten element ma wartość Fałsz lub nie istnieje, Edge weryfikuje parametry client_id i client_secret w normalny sposób pod kątem magazynu autoryzacji Apigee Edge. Użyj tego elementu, jeśli chcesz pracować z tokenami OAuth innych firm. Szczegółowe informacje o używaniu tego elementu znajdziesz w artykule Używanie tokenów OAuth innych firm.

Element <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Informuje Apigee Edge, gdzie znajduje się zewnętrzny kod autoryzacji (kod autoryzacji nie wygenerowany przez Apigee Edge).

Zmienna request.queryparam.external_auth_code wskazuje, że zewnętrzny kod autoryzacji powinien znajdować się jako parametr zapytania, np. ?external_auth_code=12345678. Aby na przykład wymagać zewnętrznego kodu autoryzacji w nagłówku HTTP, ustaw tę wartość na request.header.external_auth_code. Zapoznaj się też z informacjami o używaniu tokenów OAuth innych firm.

Element <ExternalOdświeżToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Informuje Apigee Edge, gdzie znajduje się zewnętrzny token odświeżania (token odświeżania nie został wygenerowany przez Apigee Edge).

Zmienna request.queryparam.external_refresh_token wskazuje, że zewnętrzny token odświeżania powinien być obecny jako parametr zapytania, np. ?external_refresh_token=12345678. Aby na przykład wymagać zewnętrznego tokena odświeżania w nagłówku HTTP, ustaw tę wartość na request.header.external_refresh_token. Zapoznaj się też z informacjami o używaniu tokenów OAuth innych firm.

Element <GenerateResponse>

<GenerateResponse enabled='true'/>

Jeśli zasada ma wartość true, zasada generuje i zwraca odpowiedź. Na przykład w przypadku metody GenerateAccessToken odpowiedź może wyglądać tak:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Jeśli ustawiona jest wartość false, odpowiedź nie jest wysyłana. Zamiast tego zestaw zmiennych przepływu jest wypełniany wartościami powiązanymi z funkcją zasady. Na przykład zmienna przepływu o nazwie oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code jest wypełniana nowo wygenerowanym kodem autoryzacji. Pamiętaj, że parametr expires_in jest wyrażony w sekundach w odpowiedzi.

Element <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Jeśli zasada ma wartość true, zasada generuje i zwraca odpowiedź, jeśli atrybut kontynuacji z błędem ma wartość Prawda. Jeśli ustawiona jest wartość false, odpowiedź nie jest wysyłana. Zamiast tego zestaw zmiennych przepływu jest wypełniany wartościami powiązanymi z funkcją zasady.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Informuje zasadę, gdzie znajduje się parametr typu uwierzytelnienia przekazywany w żądaniu. Zgodnie ze specyfikacją OAuth 2.0 typ uwierzytelnienia musi być podawany z żądaniami tokenów dostępu i kodów autoryzacji. Zmienna może być nagłówkiem, parametrem zapytania lub parametrem formularza (domyślnie).

Na przykład request.queryparam.grant_type wskazuje, że hasło powinno występować jako parametr zapytania, np. ?grant_type=password. Aby na przykład wymagać typu uwierzytelnienia w nagłówku HTTP, ustaw tę wartość na request.header.grant_type. Zobacz też Wysyłanie prośby o tokeny dostępu i kody autoryzacji.

Element <Operation>

<Operation>GenerateAuthorizationCode</Operation>

Operacja OAuth 2.0 wykonywana przez zasadę.

Element <PassWord>

<PassWord>request.queryparam.password</PassWord>

Ten element jest używany tylko z typem przyznania hasła. W przypadku typu przyznania hasła dane logowania użytkownika (hasło i nazwa użytkownika) muszą być dostępne dla zasady OAuthV2. Elementy <PassWord> i <UserName> służą do określania zmiennych, w których Edge może znaleźć te wartości. Jeśli te elementy nie są określone, zasada oczekuje, że powinny znaleźć wartości (domyślnie) w parametrach formularzy o nazwach username i password. W przypadku braku wartości zasada zwraca błąd. Za pomocą elementów <PassWord> i <UserName> możesz odwołać się do dowolnej zmiennej przepływu zawierającej dane logowania.

Możesz na przykład przekazać hasło w żądaniu tokena za pomocą parametru zapytania i ustawić element w następujący sposób: <PassWord>request.queryparam.password</PassWord>. Aby wymagać hasła w nagłówku HTTP, ustaw tę wartość na request.header.password.

Zasada OAuthV2 nie ma żadnego innego działania z tymi wartościami danych logowania. Edge po prostu sprawdza ich obecność. To deweloper interfejsu API musi pobrać żądanie wartości i wysłać je do dostawcy tożsamości przed uruchomieniem zasady generowania tokenów.

Zobacz też Wysyłanie prośby o tokeny dostępu i kody autoryzacji.

Element <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Określa, gdzie Edge ma szukać parametru redirect_uri w żądaniu.

Informacje o identyfikatorach URI przekierowania

Identyfikatory URI przekierowania są używane z kodem autoryzacji i niejawnymi typami uwierzytelnienia. Identyfikator URI przekierowania informuje serwer autoryzacji (Edge), gdzie należy wysłać kod autoryzacji (w przypadku typu uwierzytelnienia kodu autoryzacji) lub token dostępu (w przypadku niejawnego typu uwierzytelnienia). Ważne jest, aby wiedzieć, kiedy ten parametr jest wymagany, kiedy jest opcjonalny i jak go używać:

• (Wymagane) Jeśli URL wywołania zwrotnego jest zarejestrowany w aplikacji dewelopera, która jest powiązana z kluczami klienta żądania, i jeśli żądanie zawiera redirect_uri, muszą one być dokładnie takie same. W przeciwnym razie zwracany jest błąd. Informacje o rejestrowaniu aplikacji dla programistów w Edge i określaniu adresu URL wywołania zwrotnego znajdziesz w artykule Rejestrowanie aplikacji i zarządzanie kluczami interfejsu API.

• (opcjonalnie) Jeśli URL wywołania zwrotnego jest zarejestrowany, ale w żądaniu brakuje redirect_uri, Edge przekierowuje na zarejestrowany adres URL wywołania zwrotnego.
• (Wymagane) Jeśli URL wywołania zwrotnego nie jest zarejestrowany, wymagany jest parametr redirect_uri. Pamiętaj, że w tym przypadku Edge akceptuje DOWOLNY URL. To zgłoszenie może zagrażać bezpieczeństwu, dlatego należy go używać tylko w przypadku zaufanych aplikacji klienckich. Jeśli aplikacje klienckie nie są zaufane, najlepiej jest zawsze wymagać zarejestrowania adresu URL wywołania zwrotnego.

Możesz wysyłać ten parametr w parametrze zapytania lub w nagłówku. Zmienna request.queryparam.redirect_uri wskazuje, że parametr RedirectUri powinien być obecny jako parametr zapytania, np. ?redirect_uri=login.myapp.com. Aby na przykład wymagać parametru RedirectUri w nagłówku HTTP, ustaw tę wartość na request.header.redirect_uri. Zapoznaj się też z prośbą o tokeny dostępu i kody autoryzacji.

Element <OdświeżToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Jeśli żądasz tokena dostępu za pomocą tokena odświeżania, musisz podać w żądaniu token odświeżania. Ten element pozwala określić, gdzie Edge ma szukać tokena odświeżania. Można go wysłać na przykład jako parametr zapytania, nagłówek HTTP lub parametr formularza (domyślnie).

Zmienna request.queryparam.refreshtoken wskazuje, że token odświeżania powinien znajdować się jako parametr zapytania, np. ?refresh_token=login.myapp.com. Aby na przykład wymagać elementu refreshToken w nagłówku HTTP, ustaw tę wartość na request.header.refresh_token. Zapoznaj się też z prośbą o tokeny dostępu i kody autoryzacji.

Element <OdświeżTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Wymusza wygaśnięcie tokenów odświeżania w milisekundach. Wartość czasu wygaśnięcia to wartość wygenerowana przez system plus wartość <RefreshTokenExpiresIn>. Jeśli <RefreshTokenExpiresIn> ma wartość -1, token odświeżania wygaśnie zgodnie z maksymalną datą wygaśnięcia tokena odświeżania OAuth. Jeśli nie podasz <RefreshTokenExpiresIn>, domyślnie okres ważności jest nieokreślony.

Czas wygaśnięcia można też ustawić w czasie działania za pomocą zakodowanej na stałe wartości domyślnej lub przez odwołanie do zmiennej przepływu. Możesz na przykład zapisać wartość wygaśnięcia tokena w mapie par klucz-wartość, pobrać ją, przypisać do zmiennej i odwołać się do niej w zasadzie. Na przykład: kvm.oauth.expires_in.

Poniższa sekcja określa też zmienną przepływu i wartość domyślną. Pamiętaj, że wartość zmiennej przepływu ma pierwszeństwo przed określoną wartością domyślną.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Private Cloud: w przypadku instalacji Edge dla Private Cloud wartość domyślną jest ustawiana przez właściwość conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. Aby ustawić tę właściwość:

1. Otwórz plik message-processor.properties w edytorze. Jeśli plik nie istnieje, utwórz go:

   vi /opt/apigee/customer/application/message-processor.properties

2. Ustaw odpowiednią usługę:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Upewnij się, że plik właściwości należy do użytkownika „apigee”:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Ponownie uruchom procesor wiadomości.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Element <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Ten element informuje Edge o typie uwierzytelnienia, którego żąda aplikacja kliencka. Jest używany tylko z kodem autoryzacji i niejawnymi przepływami typu uwierzytelnienia.

Domyślnie Edge szuka wartości typu odpowiedzi w parametrze zapytania response_type. Jeśli chcesz zastąpić to domyślne działanie, użyj elementu <ResponseType>, aby skonfigurować zmienną przepływu zawierającą wartość typu odpowiedzi. Jeśli na przykład ustawisz ten element na request.header.response_type, Edge szuka typu odpowiedzi w nagłówku żądania. Zobacz też Wysyłanie prośby o tokeny dostępu i kody autoryzacji.

Element <ReuserefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Jeśli ma wartość true, istniejący token odświeżania jest używany ponownie, dopóki nie wygaśnie. Jeśli false, po przedstawieniu prawidłowego tokena odświeżania przez Apigee Edge wystawiany jest nowy token odświeżania.

Element <Scope>

<Scope>request.queryparam.scope</Scope>

Jeśli ten element występuje w jednej z zasad GenerateAccessToken lub GenerateAuthorizationCode, jest używany do określania zakresów, które mają przyznać token lub kod. Te wartości są zwykle przekazywane do zasady w żądaniu z aplikacji klienckiej. Możesz skonfigurować element tak, aby pobierał zmienną przepływu, co daje możliwość wyboru sposobu przekazywania zakresów w żądaniu. W poniższym przykładzie request.queryparam.scope wskazuje, że zakres powinien występować jako parametr zapytania, np. ?scope=READ. Aby na przykład wymagać zakresu w nagłówku HTTP, ustaw tę wartość na request.header.scope.

Jeśli ten element pojawia się w zasadzie „VerifyAccessToken”, jest używany do określania zakresów, które powinna egzekwować zasada. W zasadach tego typu wartość musi być „zakodowaną na stałe” nazwą zakresu – nie można używać zmiennych. Na przykład:

<Scope>A B</Scope>

Zapoznaj się też z informacjami o korzystaniu z zakresów OAuth2 oraz o żądaniu tokenów dostępu i kodów autoryzacji.

Element <State>

<State>request.queryparam.state</State>

Jeśli aplikacja klienta musi wysyłać informacje o stanie do serwera autoryzacji, ten element pozwala określić, gdzie Edge ma szukać wartości stanu. Można go wysłać na przykład jako parametr zapytania lub w nagłówku HTTP. Wartość stanu jest zwykle używana jako środek bezpieczeństwa zapobiegający atakom typu CSRF.

Na przykład request.queryparam.state wskazuje, że stan powinien występować jako parametr zapytania, np. ?state=HjoiuKJH32. Aby na przykład wymagać stanu w nagłówku HTTP, ustaw tę wartość na request.header.state. Zapoznaj się też z informacjami o wysyłaniu próśb o tokeny dostępu i kody autoryzacji.

Element <StoreToken>

 <StoreToken>true</StoreToken> 

Ustaw ten element na true, gdy element <ExternalAuthorization> ma wartość true. Element <StoreToken> informuje Apigee Edge, że ma zapisać token dostępu zewnętrznego. W przeciwnym razie nie zostaną zachowane.

Element <SupportedGrantTypes>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Określa typy uwierzytelniania obsługiwane przez punkt końcowy tokena OAuth w Apigee Edge. Punkt końcowy może obsługiwać wiele typów uwierzytelnienia (to znaczy, że pojedynczy punkt końcowy można skonfigurować tak, aby rozprowadzał tokeny dostępu dla wielu typów uwierzytelnienia). Więcej informacji o punktach końcowych znajdziesz w artykule Omówienie punktów końcowych OAuth. Typ przyznania jest przekazywany w żądaniach tokenów w parametrze grant_type.

Jeśli nie określono żadnych obsługiwanych typów uwierzytelnienia, jedyne dozwolone typy uwierzytelnienia to authorization_code i implicit. Zobacz też element <GrantType> (jest to element wyższego poziomu, który służy do określania miejsca, w którym Apigee Edge ma szukać parametru grant_type przekazywanego w żądaniu klienta. Edge dopilnuje, aby wartość parametru grant_type była zgodna z jednym z obsługiwanych typów uwierzytelniania.

Element <Tokens>/<Token>

Używana z operacjami ValidateToken i InvalidateToken. Zobacz też Zatwierdzanie i cofanie tokenów dostępu. Element <Token> określa zmienną przepływu definiującą źródło tokena do unieważnienia. Jeśli deweloperzy mają przesyłać tokeny dostępu jako parametry zapytania o nazwie access_token, na przykład użyj request.queryparam.access_token.

Element <UserName>

<UserName>request.queryparam.user_name</UserName>

Ten element jest używany tylko z typem przyznania hasła. W przypadku typu przyznania hasła dane logowania użytkownika (hasło i nazwa użytkownika) muszą być dostępne dla zasady OAuthV2. Elementy <PassWord> i <UserName> służą do określania zmiennych, w których Edge może znaleźć te wartości. Jeśli te elementy nie są określone, zasada oczekuje, że powinny znaleźć wartości (domyślnie) w parametrach formularzy o nazwach username i password. W przypadku braku wartości zasada zwraca błąd. Za pomocą elementów <PassWord> i <UserName> możesz odwołać się do dowolnej zmiennej przepływu zawierającej dane logowania.

Możesz na przykład przekazać nazwę użytkownika w parametrze zapytania i ustawić element <UserName> w ten sposób: <UserName>request.queryparam.username</UserName>.Aby wymagać podawania nazwy użytkownika w nagłówku HTTP, ustaw tę wartość na request.header.username.

Zasada OAuthV2 nie ma żadnego innego działania z tymi wartościami danych logowania. Edge po prostu sprawdza ich obecność. To deweloper interfejsu API musi pobrać żądanie wartości i wysłać je do dostawcy tożsamości przed uruchomieniem zasady generowania tokenów.

Zobacz też Wysyłanie prośby o tokeny dostępu i kody autoryzacji.

Weryfikowanie tokenów dostępu

Po skonfigurowaniu punktu końcowego tokena dla serwera proxy interfejsu API odpowiednia zasada OAuthV2, która określa operację VerifyAccessToken, jest dołączana do procesu, który ujawnia zabezpieczony zasób.

Aby na przykład upewnić się, że wszystkie żądania wysyłane do interfejsu API są autoryzowane, ta zasada wymusza weryfikację tokena dostępu:

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

Zasada jest połączona z zasobem interfejsu API, który ma być chroniony. Aby mieć pewność, że wszystkie żądania do interfejsu API są zweryfikowane, dołącz zasadę do żądania PreFlow ProxyEndpoint w ten sposób:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Poniższe elementy opcjonalne mogą posłużyć do zastąpienia domyślnych ustawień operacjiVerifyAccessToken.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

Zobacz też Weryfikowanie tokenów dostępu oraz Żądanie tokenów dostępu i kodów autoryzacji.

Określanie lokalizacji zmiennych żądania

W przypadku każdego typu uwierzytelnienia zasada przyjmuje założenia dotyczące lokalizacji lub wymaganych informacji w komunikatach z żądaniami. Te założenia są oparte na specyfikacji OAuth 2.0. Jeśli Twoje aplikacje muszą odbiegać od specyfikacji OAuth 2.0, możesz określić oczekiwane lokalizacje każdego parametru. Na przykład podczas obsługi kodu autoryzacji możesz określić lokalizację kodu autoryzacji, identyfikator klienta, identyfikator URI przekierowania oraz zakres. Możesz je określić jako nagłówki HTTP, parametry zapytania lub parametry formularza.

Poniższy przykład pokazuje, jak określić lokalizację wymaganych parametrów kodu autoryzacji jako nagłówki HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Jeśli jest to konieczne, aby obsługiwać aplikacje klienckie, możesz łączyć i dopasowywać nagłówki oraz parametry zapytania:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Dla każdego parametru można skonfigurować tylko jedną lokalizację.

Zmienne przepływu

Zmienne przepływu zdefiniowane w tej tabeli są wypełniane podczas wykonywania odpowiednich zasad OAuth, dlatego są dostępne dla innych zasad lub aplikacji wykonywanych w procesie przekazywania serwera proxy interfejsu API.

OperacjaVerifyAccessToken

OperacjaVerifyAccessToken jest wykonywana, a w kontekście wykonywania serwera proxy jest zapełniana duża liczba zmiennych przepływu. Te zmienne udostępniają właściwości powiązane z tokenem dostępu, aplikacją dewelopera, programistą i firmą. Możesz na przykład użyć zasady AssignMessage lub JavaScript, by odczytać dowolne z tych zmiennych i użyć ich w razie potrzeby na późniejszym etapie procesu. Zmienne te mogą też być przydatne podczas debugowania.

Zmienne związane z tokenem

Zmienne dotyczące aplikacji

Te zmienne są powiązane z aplikacją dewelopera powiązaną z tokenem.

Zmienne specyficzne dla dewelopera

Jeśli typ app.appType to „Company”, atrybuty firmy zostaną wypełnione, a jeśli app.appType ma wartość „developer”, atrybuty programisty zostaną wypełnione.

Zmienne specyficzne dla firmy

Jeśli typ app.appType to „Company”, atrybuty firmy zostaną wypełnione, a jeśli app.appType ma wartość „developer”, atrybuty programisty zostaną wypełnione.

Operacja WygenerujAuthorizationCode

Te zmienne są ustawiane po wykonaniu operacji GenerateAuthorizationCode:

Prefiks: oauthv2authcode.{policy_name}.{variable_name}

Przykład: oauthv2authcode.GenerateCodePolicy.code

Operacje GenerateAccessToken i refreshAccessToken

Te zmienne są ustawiane po pomyślnym wykonaniu operacji GenerateAccessToken i refreshAccessToken. Zwróć uwagę, że zmienne tokena odświeżania nie mają zastosowania do procesu przyznawania danych logowania klienta.

Prefiks: oauthv2accesstoken.{policy_name}.{variable_name}

Przykład: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

Te zmienne są ustawiane po pomyślnym wykonaniu operacji GenerateAccessTokenImplicit dla przepływu niejawnego typu uwierzytelnienia.

Prefiks: oauthv2accesstoken.{policy_name}.{variable_name}

Przykład: oauthv2accesstoken.RefreshTokenPolicy.access_token

Informacje o błędach

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Zmienne błędów

Te zmienne są ustawiane, gdy zasada wywołuje błąd w czasie działania.

Przykładowa odpowiedź na błąd

Te odpowiedzi są odsyłane z powrotem do klienta, jeśli element <GenerateResponse> ma wartość true.

Jeśli <GenerateResponse> ma wartość true, zasada zwraca błędy w tym formacie w przypadku operacji generujących tokeny i kody. Pełną listę znajdziesz w artykule Informacje o odpowiedziach na błędy HTTP OAuth.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Jeśli <GenerateResponse> ma wartość true, zasada zwraca błędy w tym formacie na potrzeby operacji weryfikacji. Pełną listę znajdziesz w artykule Informacje o odpowiedziach na błędy HTTP OAuth.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Przykładowa reguła błędu

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Schemat zasad

Każdy typ zasady jest definiowany przez schemat XML (.xsd). Schematy zasad są dostępne na GitHubie.

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 wstępnie 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. Więcej informacji znajdziesz w artykule Omówienie punktów końcowych OAuth.

Trwałe usuwanie tokenów dostępu

Domyślnie tokeny OAuth2 są trwale usuwane z systemu Apigee Edge po 3 dniach (259200 sekund) po wygaśnięciu tokena dostępu i tokena odświeżania (jeśli istnieje). W niektórych przypadkach możesz chcieć zmienić to ustawienie. Możesz na przykład skrócić czas trwałego usuwania, aby zaoszczędzić miejsce na dysku w przypadku generowania dużej liczby tokenów.

Jeśli korzystasz z Edge for Private Cloud, możesz zmienić to ustawienie domyślne, ustawiając właściwości organizacji w sposób opisany w tej sekcji. (3-dniowe trwałe usunięcie tokenów wygasłych dotyczy Edge dla Private Cloud w wersji 4.19.01 i nowszych. W przypadku wcześniejszych wersji domyślny okres trwałego usuwania wynosi 180 dni.

Aktualizowanie ustawień trwałego usuwania w Edge Private Cloud 4.16.01 i nowszych

Uwaga: zmiana będzie miała wpływ tylko na tokeny wygenerowane po zastosowaniu tych ustawień. Ustawienia nie dotyczą tokenów wygenerowanych wcześniej.

Aktualizuję ustawienia trwałego usuwania usługi Edge Private Cloud 4.15.07

Uwaga: ta zmiana będzie miała wpływ tylko na tokeny wygenerowane po zastosowaniu tych ustawień. Ustawienia nie dotyczą tokenów wygenerowanych wcześniej.

Działanie niezgodne z RFC

Zasada OAuthV2 zwraca odpowiedź tokena zawierającą określone właściwości niezgodne z RFC. W tabeli poniżej znajdziesz niezgodne właściwości zwrócone przez zasadę OAuthV2 i odpowiadające im zgodne właściwości.

Oprócz tego zwracana jest odpowiedź o błędzie w przypadku wygasłego tokena odświeżania, gdy grant_type = refresh_token:

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

Jednak odpowiedź zgodna ze standardem RFC to:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Powiązane artykuły

• Wprowadzenie do protokołu OAuth 2.0