Zasady OAuthV2

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Co

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

Wskazówka: jeśli chcesz dowiedzieć się więcej o OAuth w Apigee Edge, odwiedź stronę główną OAuth. Zawiera linki do zasobów, przykładów, filmów i innych materiałów. Dobry przykład użycia tej zasady w działającej aplikacji znajdziesz w zaawansowanym przykładzie OAuth w usłudze GitHub.

Próbki

<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 logowania”.

Odniesienie do elementu

Dokumentacja zasady opisuje elementy i atrybuty zasady OAuthV2.

Przykładowe zasady przedstawione poniżej to jedna z wielu możliwych konfiguracji. Ten przykład pokazuje zasady OAuthV2 skonfigurowane dla 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">

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <AccessToken>

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

Domyślnie funkcja VerifyAccessToken oczekuje, że token dostępu zostanie wysłany w nagłówku Authorization. Możesz zmienić to ustawienie domyślne za pomocą tego elementu. Na przykład request.queryparam.access_token oznacza, ż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 zasada VerifyAccessToken oczekuje, że token dostępu zostanie wysłany w nagłówku Authorization jako token Bearer. Na przykład:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Obecnie obsługiwany jest tylko prefiks Bearer.

Element <AppEndUser>

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

W przypadku gdy identyfikator użytkownika aplikacji musi zostać wysłany na serwer autoryzacji, ten element umożliwia określenie, gdzie Edge ma szukać identyfikatora użytkownika. Może być na przykład wysłany jako parametr zapytania lub w nagłówku HTTP.

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

To ustawienie umożliwia uwzględnienie 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 na podstawie identyfikatora użytkownika. Więcej informacji znajdziesz w artykule Włączanie pobierania i unieważniania tokenów dostępu OAuth 2.0 według identyfikatora użytkownika, identyfikatora aplikacji lub obu tych identyfikatorów.

<Attributes/Attribute>

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

Użyj tego elementu, aby dodać atrybuty niestandardowe do tokena dostępu lub kodu autoryzacji. Możesz na przykład osadzić w tokenie dostępu identyfikator użytkownika lub identyfikator sesji, który można wyodrębnić i sprawdzić w czasie działania programu.

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

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

Wyświetlanie i ukrywanie atrybutów niestandardowych w odpowiedzi

Pamiętaj, że jeśli ustawisz element GenerateResponse tej zasady na true, w odpowiedzi zostanie zwrócona pełna reprezentacja tokena w formacie JSON, w tym wszystkie ustawione przez Ciebie atrybuty niestandardowe. W niektórych przypadkach możesz chcieć 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ć parametr display na 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 jest zapisywana. 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, w odpowiedzi tokena odświeżania pojawią się oryginalne atrybuty niestandardowe z tokena dostępu. Dzieje się tak, ponieważ Edge nie pamięta, że atrybut display został pierwotnie ustawiony na false w zasadach generowania tokena dostępu – atrybut niestandardowy jest po prostu częścią metadanych tokena dostępu.

To samo zachowanie wystąpi, jeśli dodasz atrybuty niestandardowe do kodu autoryzacji – gdy token dostępu zostanie wygenerowany przy użyciu tego kodu, te atrybuty niestandardowe pojawią się w odpowiedzi tokena dostępu. Może to nie być oczekiwane zachowanie.

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

• Wyraźnie zresetuj atrybuty niestandardowe w zasadach tokena odświeżania i ustaw ich wyświetlanie na wartość „false”. W takim przypadku może być konieczne pobranie oryginalnych wartości niestandardowych z oryginalnego tokena dostępu za pomocą zasady GetOAuthV2Info.
• Użyj zasady JavaScriptu po przetworzeniu, 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 określa, że Apigee ma szukać identyfikatora klienta w zmiennej przepływu request.formparam.client_id. Ustawienie ClientId na inną zmienną nie jest obsługiwane. Zobacz też Prośba o tokeny dostępu i kody autoryzacji.

Element <Code>

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

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

Zmienna request.queryparam.auth_code oznacza, że kod autoryzacji powinien być obecny jako parametr zapytania, np. ?auth_code=AfGlvs9. Aby wymagać kodu autoryzacji w nagłówku HTTP, ustaw np. tę wartość na request.header.auth_code. Zobacz też Prośba o tokeny dostępu i kody autoryzacji.

Element <ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

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

Czas wygaśnięcia można też ustawić w czasie działania, używając zakodowanej na stałe wartości domyślnej lub odwołując się 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 zasadach. Na przykład: kvm.oauth.expires_in.

W przypadku Apigee Edge na platformie chmury publicznej Edge przechowuje w pamięci podręcznej te elementy przez co najmniej 180 sekund od momentu uzyskania do nich dostępu.

• tokeny dostępu OAuth, Oznacza to, że odwołany token może być nadal ważny przez maksymalnie 3 minuty, dopóki nie wygaśnie limit pamięci podręcznej.
• podmioty usługi Key Management Service (KMS) (aplikacje, programiści, usługi API);
• Atrybuty niestandardowe tokenów OAuth i encji KMS.

Ten fragment kodu określa 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 wymuszania wygaśnięcia tokena po jego utworzeniu. Jeśli musisz wymusić wygaśnięcie tokena (np. na podstawie warunku), możliwe rozwiązanie opisano w  tym poście na forum społeczności Apigee.

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

Private Cloud: w przypadku instalacji Edge for Private Cloud wartość domyślna jest określana 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 właściwość w odpowiedni sposób:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Sprawdź, czy plik właściwości należy do użytkownika „apigee”:

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

4. Uruchom ponownie 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 znaleźć zewnętrzny token dostępu (token dostępu, który nie został wygenerowany przez Apigee Edge).

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

Element <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Jeśli ten element ma wartość false lub nie występuje, Edge weryfikuje identyfikator klienta i klucz tajny klienta w normalny sposób w magazynie autoryzacji Apigee Edge. Użyj tego elementu, jeśli chcesz pracować z tokenami OAuth innych firm. Więcej informacji o korzystaniu z tego elementu znajdziesz w artykule Korzystanie z tokenów OAuth innych firm.

Element <ExternalAuthorizationCode>

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

Określa, gdzie Apigee Edge ma szukać zewnętrznego kodu autoryzacji (kodu autoryzacji, który nie został wygenerowany przez Apigee Edge).

Zmienna request.queryparam.external_auth_code oznacza, że zewnętrzny kod autoryzacji powinien być obecny jako parametr zapytania, np. ?external_auth_code=12345678. Aby wymagać kodu autoryzacji zewnętrznej w nagłówku HTTP, ustaw na przykład tę wartość na request.header.external_auth_code. Zobacz też Korzystanie z tokenów OAuth innych firm.

Element <ExternalRefreshToken>

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

Informuje Apigee Edge, gdzie znaleźć zewnętrzny token odświeżania (token odświeżania, który nie został wygenerowany przez Apigee Edge).

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

Element <GenerateResponse>

<GenerateResponse enabled='true'/>

Jeśli ta opcja ma wartość true, zasada generuje i zwraca odpowiedź. Na przykład w przypadku 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 false, nie zostanie wysłana żadna odpowiedź. Zamiast tego zestaw zmiennych przepływu jest wypełniany wartościami związanymi z funkcją zasady. Na przykład zmienna przepływu o nazwie oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code zostanie wypełniona nowo wygenerowanym kodem autoryzacji. Pamiętaj, że w odpowiedzi wartość expires_in jest podana w sekundach.

Element <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Jeśli zasada ma wartość true, generuje i zwraca odpowiedź, jeśli atrybut ContinueOnError ma wartość true. Jeśli false (wartość domyślna), nie jest wysyłana żadna odpowiedź. Zamiast tego zestaw zmiennych przepływu jest wypełniany wartościami związanymi z funkcją zasady.

<GrantType>

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

Informuje zasadę, gdzie znaleźć parametr typu uprawnień przekazywany w żądaniu. Zgodnie ze specyfikacją OAuth 2.0 typ przyznania musi być podawany w żądaniach 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 oznacza, że hasło powinno być obecne jako parametr zapytania, np. ?grant_type=password. Aby wymagać typu przyznania w nagłówku HTTP, ustaw np. tę wartość na request.header.grant_type. Zobacz też Prośba o tokeny dostępu i kody autoryzacji.

Element <Operation>

<Operation>GenerateAuthorizationCode</Operation>

Operacja OAuth 2.0 wykonana przez zasadę.

Element <PassWord>

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

Ten element jest używany tylko z  typem uwierzytelnienia password. 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 wartości (domyślnie) będą znajdować się w parametrach formularza o nazwach username i password. Jeśli wartości nie zostaną znalezione, zasada zgłosi błąd. Możesz użyć elementów <PassWord> i <UserName>, aby 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 ten 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 wykonuje żadnych innych działań z tymi wartościami danych logowania. Edge po prostu sprawdza, czy są one obecne. To deweloper interfejsu API musi pobrać wartości żądania i przesłać je do dostawcy tożsamości przed wykonaniem zasady generowania tokena.

Zobacz też Prośba 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 typami uwierzytelnienia kod autoryzacji i niejawne. Identyfikator URI przekierowania informuje serwer autoryzacji (Edge), gdzie wysłać kod autoryzacji (w przypadku typu przyznawania kodu autoryzacji) lub token dostępu (w przypadku typu przyznawania pośredniego). Warto wiedzieć, kiedy ten parametr jest wymagany, kiedy jest opcjonalny i jak jest używany:

• (wymagany) Jeśli w aplikacji dewelopera powiązanej z kluczami klienta żądania zarejestrowany jest adres URL wywołania zwrotnego i jeśli w żądaniu występuje parametr redirect_uri, oba muszą być identyczne. Jeśli nie pasują, zwracany jest błąd. Informacje o rejestrowaniu aplikacji deweloperskich w Edge i określaniu adresu URL wywołania zwrotnego znajdziesz w artykule Rejestrowanie aplikacji i zarządzanie kluczami interfejsu API.

• (opcjonalnie) Jeśli zarejestrowany jest adres URL wywołania zwrotnego, a w żądaniu brakuje parametru redirect_uri, Edge przekierowuje do zarejestrowanego adresu URL wywołania zwrotnego.
• (wymagany) Jeśli adres URL wywołania zwrotnego nie jest zarejestrowany, wymagany jest parametr redirect_uri. Pamiętaj, że w tym przypadku Edge zaakceptuje KAŻDY adres URL. W tym przypadku może wystąpić problem z bezpieczeństwem, dlatego należy go używać tylko w przypadku zaufanych aplikacji klienckich. Jeśli aplikacje klienckie nie są zaufane, najlepszym rozwiązaniem jest zawsze wymaganie rejestracji adresu URL wywołania zwrotnego.

Ten parametr możesz wysłać w parametrze zapytania lub w nagłówku. Zmienna request.queryparam.redirect_uri oznacza, że parametr RedirectUri powinien występować jako parametr zapytania, np. ?redirect_uri=login.myapp.com. Aby wymagać parametru RedirectUri w nagłówku HTTP, ustaw na przykład tę wartość na request.header.redirect_uri. Zobacz też Prośba o tokeny dostępu i kody autoryzacji.

Element <RefreshToken>

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

Gdy prosisz o token dostępu za pomocą tokena odświeżania, musisz podać token odświeżania w żądaniu. Ten element umożliwia określenie, gdzie Edge ma szukać tokena odświeżania. Może być na przykład wysyłany jako parametr zapytania, nagłówek HTTP lub parametr formularza (domyślnie).

Zmienna request.queryparam.refreshtoken oznacza, że token odświeżania powinien być obecny jako parametr zapytania, np. ?refresh_token=login.myapp.com. Aby wymagać tokenu odświeżania w nagłówku HTTP, ustaw na przykład tę wartość na request.header.refresh_token. Zobacz też Prośba o tokeny dostępu i kody autoryzacji.

Element <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Wymusza czas wygaśnięcia tokenów odświeżania w milisekundach. Wartość czasu wygaśnięcia to wartość wygenerowana przez system plus wartość <RefreshTokenExpiresIn>. Jeśli wartość parametru <RefreshTokenExpiresIn> to -1, token odświeżania wygasa zgodnie z maksymalnym czasem ważności tokena odświeżania OAuth. Jeśli nie podasz wartości <RefreshTokenExpiresIn>, system zastosuje wartość domyślną skonfigurowaną na poziomie systemu. Aby uzyskać więcej informacji o domyślnych ustawieniach systemu, skontaktuj się z zespołem pomocy Apigee Edge.

Czas wygaśnięcia można też ustawić w czasie działania, używając zakodowanej na stałe wartości domyślnej lub odwołując się 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 zasadach. Na przykład: kvm.oauth.expires_in.

Ten fragment kodu określa zmienną przepływu i wartość domyślną. Pamiętaj, że wartość zmiennej flow ma pierwszeństwo przed określoną wartością domyślną.

<RefreshTokenExpiresIn ref="kvm.oauth.expire>s_in"
  <  3600000 !--default value in mill>i<seconds--
/RefreshToke>nExpiresIn

Private Cloud: w przypadku instalacji Edge for Private Cloud wartość domyślna jest określana 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 właściwość w odpowiedni sposób:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Sprawdź, czy plik właściwości należy do użytkownika „apigee”:

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

4. Uruchom ponownie 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 jaki typ uprawnień prosi aplikacja kliencka. Jest on używany tylko w przypadku przepływów kodu autoryzacji i niejawnego udzielania dostępu.

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 będzie szukać typu odpowiedzi przekazywanego w nagłówku żądania. Zobacz też Prośba o tokeny dostępu i kody autoryzacji.

Element <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Gdy ta wartość jest ustawiona na true, dotychczasowy token odświeżania jest używany ponownie do momentu wygaśnięcia. Jeśli false, Apigee Edge wydaje nowy token odświeżania, gdy zostanie przedstawiony prawidłowy token odświeżania.

Element <Scope>

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

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

Jeśli ten element występuje w zasadzie „VerifyAccessToken”, służy do określania zakresów, które mają być egzekwowane przez zasadę. W przypadku tego typu zasady wartość musi być „zakodowaną na stałe” nazwą zakresu – nie można używać zmiennych. Na przykład:

<Scope>A B</Scope>

Zobacz też Praca z zakresami OAuth2 oraz Żądanie tokenów dostępu i kodów autoryzacji.

Element <State>

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

W przypadkach, gdy aplikacja kliencka musi wysłać informacje o stanie do serwera autoryzacji, ten element umożliwia określenie, gdzie Edge ma szukać wartości stanu. Może być na przykład wysyłany jako parametr zapytania lub w nagłówku HTTP. Wartość stanu jest zwykle używana jako środek bezpieczeństwa zapobiegający atakom CSRF.

Na przykład request.queryparam.state oznacza, że stan powinien być obecny jako parametr zapytania, np. ?state=HjoiuKJH32. Aby wymagać stanu w nagłówku HTTP, ustaw na przykład tę wartość na request.header.state. Zobacz też Żądanie tokenów dostępu i kodów autoryzacji.

Element <StoreToken>

 <StoreToken>true</StoreToken>

Ustaw ten element na true, gdy element <ExternalAuthorization> jest true. Element <StoreToken> informuje Apigee Edge, że ma przechowywać zewnętrzny token dostępu. W przeciwnym razie nie zostanie on zachowany.

Element <SupportedGrantTypes>/<GrantType>

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

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

Jeśli nie określono żadnych obsługiwanych typów uwierzytelnienia, dozwolone są tylko typy authorization_code i implicit. Zobacz też element <GrantType> (element wyższego poziomu, który służy do określania, gdzie Apigee Edge ma szukać parametru grant_type przekazywanego w żądaniu klienta). Edge sprawdzi, czy wartość parametru grant_type jest zgodna z jednym z obsługiwanych typów autoryzacji.

Element <Tokens>/<Token>

Używane w operacjach ValidateToken i InvalidateToken. Zobacz też zatwierdzanie i unieważnianie tokenów dostępu. Element <Token> identyfikuje zmienną przepływu, która definiuje źródło tokena do unieważnienia. Jeśli deweloperzy mają przesyłać tokeny dostępu jako parametry zapytania o nazwie np. access_token, użyj request.queryparam.access_token.

Element <UserName>

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

Ten element jest używany tylko z  typem uwierzytelnienia password. 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 wartości (domyślnie) będą znajdować się w parametrach formularza o nazwach username i password. Jeśli wartości nie zostaną znalezione, zasada zgłosi błąd. Możesz użyć elementów <PassWord> i <UserName>, aby 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ć nazwy użytkownika w nagłówku HTTP, ustaw tę wartość na request.header.username.

Zasada OAuthV2 nie wykonuje żadnych innych działań z tymi wartościami danych logowania. Edge po prostu sprawdza, czy są one obecne. To deweloper interfejsu API musi pobrać wartości żądania i przesłać je do dostawcy tożsamości przed wykonaniem zasady generowania tokena.

Zobacz też Prośba o tokeny dostępu i kody autoryzacji.

Weryfikowanie tokenów dostępu

Gdy dla serwera proxy interfejsu API skonfigurujesz punkt końcowy tokena, do przepływu, który udostępnia chroniony zasób, zostanie dołączona odpowiednia zasada OAuthV2 określająca operację VerifyAccessToken.

Aby na przykład mieć pewność, że wszystkie żądania do interfejsu API są autoryzowane, ta zasada wymusza weryfikację tokena dostępu:

<OAuthV2 name="VerifyOAuthAccessT>oke<n"
 > OperationVerifyA<ccessToken>/<Operatio>n
/OAuthV2

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

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

Te opcjonalne elementy mogą służyć do zastępowania ustawień domyślnych operacji VerifyAccessToken.

<OAuthV2 name="ValidateOauthScopePo>lic<y"
 > OperationVerifyA<ccessToken>/Op<erati>on
  Scope<READ W>R<ITE/Scop>e
/OAuthV2

Zobacz też weryfikowanie tokenów dostępu i wysyłanie próśb o tokeny dostępu i kody autoryzacji.

Określanie lokalizacji zmiennych żądania

W przypadku każdego typu przyznawania uprawnień zasady zakładają, że w wiadomościach z prośbą o przyznanie uprawnień znajdują się określone informacje lub lokalizacja. 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ć jego lokalizację, identyfikator klienta, identyfikator URI przekierowania i zakres. Można je określić jako nagłówki HTTP, parametry zapytania lub parametry formularza.

Poniższy przykład pokazuje, jak możesz 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>
  ...

W razie potrzeby możesz też łączyć nagłówki i parametry zapytania, aby obsługiwać bazę aplikacji klienckich:

  ...
  <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>
  ...

Każdy parametr może mieć tylko 1 skonfigurowaną lokalizację.

Zmienne przepływu

Zmienne przepływu zdefiniowane w tej tabeli są wypełniane po wykonaniu odpowiednich zasad OAuth, a tym samym są dostępne dla innych zasad lub aplikacji wykonywanych w przepływie serwera proxy interfejsu API.

Operacja VerifyAccessToken

Wykonuje się operacja VerifyAccessToken, a w kontekście wykonania serwera proxy wypełnia się duża liczba zmiennych przepływu. Te zmienne zawierają właściwości związane z tokenem dostępu, aplikacją dewelopera, deweloperem i firmą. Możesz na przykład użyć zasady AssignMessage lub JavaScript, aby odczytać dowolną z tych zmiennych i użyć jej w razie potrzeby w dalszej części przepływu. Te zmienne mogą być też przydatne do debugowania.

Zmienne związane z tokenem

Zmienne specyficzne dla aplikacji

Te zmienne są powiązane z aplikacją dewelopera, która jest powiązana z tokenem.

Zmienne specyficzne dla dewelopera

Jeśli app.appType ma wartość „Company”, wypełniane są atrybuty firmy, a jeśli app.appType ma wartość „Developer”, wypełniane są atrybuty dewelopera.

Zmienne dotyczące firmy

Jeśli app.appType ma wartość „Company”, wypełniane są atrybuty firmy, a jeśli app.appType ma wartość „Developer”, wypełniane są atrybuty dewelopera.

Operacja GenerateAuthorizationCode

Te zmienne są ustawiane, gdy operacja GenerateAuthorizationCode zostanie wykonana:

Prefiks: oauthv2authcode.{policy_name}.{variable_name}

Przykład: oauthv2authcode.GenerateCodePolicy.code

operacje GenerateAccessToken i RefreshAccessToken,

Te zmienne są ustawiane, gdy operacje GenerateAccessToken i RefreshAccessToken zostaną wykonane prawidłowo. Pamiętaj, że zmienne tokena odświeżania nie mają zastosowania w przypadku przepływu typu przyznawania danych uwierzytelniających klienta.

Prefiks: oauthv2accesstoken.{policy_name}.{variable_name}

Przykład: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

Te zmienne są ustawiane, gdy operacja GenerateAccessTokenImplicit zostanie wykonana prawidłowo w przypadku przepływu typu zezwolenia dorozumianego.

Prefiks: oauthv2accesstoken.{policy_name}.{variable_name}

Przykład: oauthv2accesstoken.RefreshTokenPolicy.access_token

Odniesienie do błędów

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime.

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

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

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

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

Example fault rule

<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 zdefiniowany przez schemat XML (.xsd). Schematy zasad są dostępne na GitHubie.

Praca z domyślną konfiguracją OAuth

Każda organizacja (nawet organizacja w okresie próbnym) w Apigee Edge ma udostępniony punkt końcowy tokena OAuth. Punkt końcowy jest wstępnie skonfigurowany za pomocą zasad w proxy interfejsu API o nazwie oauth. Możesz zacząć korzystać z punktu końcowego tokena od razu po utworzeniu konta w Apigee Edge. Więcej informacji znajdziesz w artykule Punkty końcowe OAuth.

Usuwanie tokenów dostępu

Domyślnie tokeny OAuth2 są usuwane z systemu Apigee Edge po 3 dniach (259 200 sekund) od wygaśnięcia tokena dostępu i tokena odświeżania (jeśli istnieje). W niektórych przypadkach możesz chcieć zmienić to ustawienie domyślne. Jeśli na przykład generowana jest duża liczba tokenów, możesz skrócić czas usuwania, aby zaoszczędzić miejsce na dysku.

Jeśli korzystasz z Edge for Private Cloud, możesz zmienić to ustawienie domyślne, konfigurując właściwości organizacji w sposób opisany w tej sekcji. (3-dniowe usuwanie wygasłych tokenów dotyczy Edge w chmurze prywatnej w wersji 4.19.01 i nowszych. W przypadku wcześniejszych wersji domyślny interwał usuwania wynosi 180 dni).

Aktualizowanie ustawień czyszczenia w Edge Private Cloud w wersji 4.16.01 i nowszych

Uwaga: te ustawienia mają wpływ tylko na tokeny wygenerowane po ich zastosowaniu. Nie dotyczą tokenów wygenerowanych wcześniej.

Aktualizowanie ustawień czyszczenia w przypadku Edge Private Cloud 4.15.07

Uwaga: te ustawienia mają wpływ tylko na tokeny wygenerowane po ich zastosowaniu. Nie dotyczą tokenów wygenerowanych wcześniej.

Zachowanie niezgodne z RFC

Zasady OAuthV2 zwracają odpowiedź tokena, która zawiera pewne właściwości niezgodne z RFC. W tabeli poniżej znajdziesz właściwości niezgodne z zasadami, które są zwracane przez zasadę OAuthV2, oraz odpowiadające im właściwości zgodne z zasadami.

Odpowiedź o błędzie w przypadku wygasłego tokena odświeżania, gdy grant_type = refresh_token, to:

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

Odpowiedź zgodna z RFC to:

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

Powiązane artykuły

• Wprowadzenie do protokołu OAuth 2.0