Zasady OAuthV2

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Co

OAuthV2 to wieloaspektowa zasada wykonywania operacji na rodzajach uwierzytelnienia OAuth 2.0. To jest podstawowa zasada używana do konfigurowania punktów końcowych OAuth 2.0 w Apigee Edge.

Wskazówka: jeśli chcesz dowiedzieć się więcej o OAuth w usłudze Apigee Edge, zapoznaj się z stroną główną OAuth. Zawiera ona linki do zasobów, przykładów, filmów i innych materiałów. Aby zobaczyć, jak ta zasada jest używana w działającej aplikacji, zapoznaj się z przykładem OAuth zaawansowanego na GitHubie.

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 danych logowania do podstawowego uwierzytelniania”.

Odniesienie do elementu

Opis zasad zawiera opis jej elementów i atrybutów.

Przykładowa zasada widoczna 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 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 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 funkcja VerifyAccessToken oczekuje, że token dostępu zostanie wysłany w nagłówku Authorization jako token Bearer. Na przykład:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Obecnie Bearer jest jedynym obsługiwanym prefiksem.

Element <AppEndUser>

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

W przypadku, gdy identyfikator użytkownika końcowego aplikacji musi zostać wysłany na serwer autoryzacji, ten element umożliwia określenie, gdzie Edge powinien szukać identyfikatora użytkownika końcowego. Mogą być na przykład wysyłane jako parametr zapytania lub w nagłówku HTTP.

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ć klasy AppEndUser w nagłówku HTTP, ustaw tę wartość na request.header.app_enduser.

Dzięki temu ustawieniu możesz uwzględnić identyfikator użytkownika aplikacji w tokenie dostępu. Ta funkcja jest przydatna, jeśli chcesz pobierać lub anulować tokeny dostępu OAuth 2.0 według 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.

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

Użyj tego elementu, aby dodać atrybuty niestandardowe do tokena dostępu lub kodu autoryzacji. Możesz na przykład umieścić identyfikator użytkownika lub identyfikator sesji w tokenie dostępu, 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 zmiennej nie uda się rozwiązać, zostanie użyty ciąg znaków domyślny.

Więcej informacji o korzystaniu z tego elementu znajdziesz w artykule na temat dostosowywania 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, wraz ze wszystkimi ustawionymi atrybutami niestandardowymi. 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 są widoczne w odpowiedzi. Jeśli chcesz je ukryć, możesz ustawić parametr display na 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 zachowywana. Załóżmy, że wygenerujesz token dostępu z atrybutami niestandardowymi, które chcesz ukryć w wygenerowanej odpowiedzi. Ustawienie display=false spełnia ten cel. Jeśli jednak nowy token dostępu zostanie wygenerowany później za pomocą tokena odświeżania, w odpowiedzi na token odświeżania pojawią się pierwotne atrybuty niestandardowe z tokena dostępu. Dzieje się tak, ponieważ Edge nie pamięta, że atrybut display miał pierwotnie wartość false w zasadzie generowania tokena dostępu – atrybut niestandardowy jest po prostu częścią metadanych tokena dostępu.

Takie samo zachowanie zauważysz po dodaniu do kodu autoryzacji atrybutów niestandardowych – gdy token dostępu zostanie wygenerowany za pomocą tego kodu, pojawią się one w odpowiedzi tokena dostępu. Ponownie, może to nie być pożądane działanie.

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

• Wyraźnie zresetuj atrybuty niestandardowe w zasadach dotyczących tokena odświeżania i ustaw ich wyświetlanie na fałsz. W takim przypadku może być konieczne pobranie oryginalnych wartości niestandardowych z oryginalnego tokena dostępu przy użyciu zasady GetOAuthV2Info.
• Aby ręcznie wyodrębnić atrybuty niestandardowe, których nie chcesz wyświetlać w odpowiedzi, użyj zasady JavaScript do przetwarzania w tle.

Zobacz też artykuł Dostosowywanie tokenów i kodów autoryzacyjnych.

Element <ClientId>

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

W niektórych przypadkach aplikacja klienta 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 do dowolnej innej zmiennej nie jest obsługiwane. Zobacz też Wysyłanie żądania tokenów dostępu i kodów autoryzacji.

Element <Code>

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

W ramach przepływu typu autoryzacji klient musi przesłać kod autoryzacji do serwera autoryzacji (Apigee Edge). Ten element umożliwia określenie, gdzie Edge ma szukać kodu autoryzacji. Może ona być na przykład wysyłana jako parametr zapytania, nagłówek HTTP lub parametr formularza (wartość domyślna).

Zmienna request.queryparam.auth_code wskazuje, że kod autoryzacji powinien być obecny jako parametr zapytania, na przykład ?auth_code=AfGlvs9. Aby wymagać kodu autoryzacji w nagłówku HTTP, ustaw tę wartość na request.header.auth_code. Zobacz też Wysyłanie żądań o tokeny dostępu i kodów autoryzacji.

Element<ExpiresIn>

<ExpiresIn>10000</ExpiresIn> 

Wymusza czas ważności 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 <ExpiresIn> ma wartość -1, token lub kod wygasa zgodnie z maksymalnym czasem ważności 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 wykonywania za pomocą zaprogramowanej wartości domyślnej lub przez odwołanie do zmiennej przepływu. Możesz na przykład zapisać datę wygaśnięcia tokena w mapie wartości klucza, pobrać ją, przypisać do zmiennej lub odwołać się do niej w zasadzie. Na przykład: kvm.oauth.expires_in.

W usłudze Apigee Edge for Public Cloud Edge przechowuje te elementy w pamięci podręcznej przez co najmniej 180 sekund od momentu ich dostępowania.

• tokeny dostępu OAuth. Oznacza to, że unieważniony token może być nadal skuteczny przez maksymalnie 3 minuty, dopóki nie wygaśnie limit pamięci podręcznej.
• elementy usługi Key Management Service (KMS) (aplikacje, deweloperzy, usługi API).
• Atrybuty niestandardowe w tokenach OAuth i elementach KMS.

Ten wers określa zmienną przepływu i wartość domyślną. Pamiętaj, że wartość zmiennej procesu 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 na karcie Społeczność Apigee.

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

Private Cloud: w przypadku instalacji Edge for Private Cloud wartość domyślna 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 właściwość zgodnie z potrzebami:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Upewnij się, że właścicielem pliku właściwości jest użytkownik „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>

Określa, gdzie Apigee Edge znajdzie zewnętrzny token dostępu (token dostępu niewygenerowany przez Apigee Edge).

Zmienna request.queryparam.external_access_token wskazuje, że zewnętrzny token dostępu powinien być obecny jako parametr zapytania, na przykład ?external_access_token=12345678. Aby wymagać tokena dostępu zewnętrznego w nagłówku HTTP, ustaw 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 jest nieprawidłowy lub go nie ma, Edge normalnie weryfikuje client_id i client_secret w sklepie autoryzacyjnym Apigee Edge. Użyj tego elementu, jeśli chcesz pracować z tokenami OAuth innych firm. Szczegółowe informacje o korzystaniu z tego elementu znajdziesz w artykule Korzystanie z tokenów OAuth innych firm.

Element <ExternalAuthorizationCode>

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

Informuje Apigee Edge, gdzie znaleźć zewnętrzny kod uwierzytelniający (kod uwierzytelniający nie wygenerowany przez Apigee Edge).

Zmienna request.queryparam.external_auth_code wskazuje, że kod autoryzacji zewnętrznej powinien być obecny jako parametr zapytania, na przykład ?external_auth_code=12345678. Aby wymagać kodu uwierzytelniania zewnętrznego w nagłówku HTTP, ustaw tę wartość na request.header.external_auth_code. Zobacz też Używanie 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 nie wygenerowany przez Apigee Edge).

Zmienna request.queryparam.external_refresh_token wskazuje, że zewnętrzny token odświeżania powinien być obecny jako parametr zapytania, na przykład ?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. Zobacz też Używanie tokenów OAuth innych firm.

Element <GenerateResponse>

<GenerateResponse enabled='true'/>

Jeśli ustawisz wartość true, zasada wygeneruje i zwróci odpowiedź. Na przykład w przypadku wywołania 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 zasada jest 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 zostanie uzupełniona nowo wygenerowanym kodem autoryzacji. Pamiętaj, że expires_in jest wyrażony w odpowiedzi w sekundach.

Element <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Jeśli ma wartość true, zasada generuje i zwraca odpowiedź, jeśli atrybut ContinueOnError ma wartość Prawda. Jeśli false (wartość domyślna), nie wysyłana jest ż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 przyznawania, który jest przekazywany w żądaniu. Zgodnie ze specyfikacją OAuth 2.0 typ przyznawania musi być podawany w żądaniach dotyczących tokenów dostępu i kodów autoryzacji. Zmienna może być nagłówkiem, parametrem zapytania lub parametrem formularza (wartość domyślna).

Przykład request.queryparam.grant_type wskazuje, że jako parametr zapytania powinno być obecne hasło, np. ?grant_type=password. Aby wymagać typu przyznawania w nagłówku HTTP, ustaw tę wartość na request.header.grant_type. Zobacz też Wysyłanie żądania tokenów dostępu i kodów 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 w przypadku typu uwierzytelniania hasłem. W przypadku typu uprawnień hasło dane logowania użytkownika (hasło i nazwa użytkownika) muszą być dostępne dla zasad OAuth 2. 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 (domyślnie) znalezienia wartości w parametrach formularza o nazwach username i password. Jeśli wartości nie zostaną znalezione, zasada zwróci błąd. Za pomocą elementów <PassWord> i <UserName> możesz odwołać się do dowolnej zmiennej przepływu, która zawiera dane logowania.

Możesz na przykład przekazać hasło w żądaniu tokena przy użyciu 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.

Zasady OAuth 2 nie robią nic więcej z tymi wartościami danych logowania. Edge po prostu sprawdza, czy są one obecne. To programista interfejsu API musi pobrać żądanie wartości i wysłać je do dostawcy tożsamości przed wykonaniem zasady generowania tokenów.

Zobacz też Wysyłanie żądań o tokeny dostępu i kodów autoryzacji.

Element <RedirectUri>

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

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

Informacje o identyfikatorach URI przekierowania

Identyfikatory URI przekierowania są używane w przypadku typu uwierzytelnienia za pomocą kodu autoryzacji i niejawnego uwierzytelnienia. Identyfikator URI przekierowania informuje serwer autoryzacji (Edge), gdzie wysłać kod autoryzacji (w przypadku typu autoryzacji za pomocą kodu autoryzacji) lub token dostępu (w przypadku typu autoryzacji z użyciem tokena dostępu). Warto wiedzieć, kiedy ten parametr jest wymagany, kiedy jest opcjonalny i jak jest używany:

• (wymagany) Jeśli adres URL wywołania zwrotnego jest zarejestrowany w aplikacji dewelopera powiązanej z kluczami klienta w żądaniu, a w żądaniu występuje parametr redirect_uri, te 2 elementy muszą się dokładnie zgadzać. Jeśli nazwy się nie zgadzają, zwracany jest błąd. Informacje o rejestrowaniu aplikacji dla deweloperó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 zarejestrowany jest adres URL wywołania zwrotnego, a w żądaniu brakuje parametru redirect_uri, przeglądarka Edge przekierowuje na zarejestrowany adres URL wywołania zwrotnego.
• (wymagany) Jeśli adres URL wywołania zwrotnego nie jest zarejestrowany, wymagany jest adres redirect_uri. Pamiętaj, że w takim przypadku Edge zaakceptuje DOWOLNY adres URL. W tym przypadku może wystąpić problem z bezpieczeństwem, dlatego należy używać go tylko w przypadku zaufanych aplikacji klienckich. Jeśli aplikacje klienckie nie są zaufane, zalecamy zawsze wymaganie rejestracji adresu URL wywołania zwrotnego.

Możesz wysłać ten parametr w parametrze zapytania lub w nagłówku. Zmienna request.queryparam.redirect_uri wskazuje, że parametr RedirectUri powinien występować jako parametr zapytania, np. ?redirect_uri=login.myapp.com. Aby wymagać wartości RedirectUri w nagłówku HTTP, ustaw tę wartość na request.header.redirect_uri. Zapoznaj się też z sekcją o żądaniu tokenów dostępu i kodów autoryzacji.

Element <RefreshToken>

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

Gdy żądasz tokena 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ć tokenu odświeżania. Może ona być na przykład wysyłana jako parametr zapytania, nagłówek HTTP lub parametr formularza (wartość domyślna).

Zmienna request.queryparam.refreshtoken wskazuje, że token odświeżania powinien być obecny jako parametr zapytania, np. ?refresh_token=login.myapp.com. Aby na przykład wymagać nagłówka HTTP RefreshToken, ustaw tę wartość na request.header.refresh_token. Zobacz też Wysyłanie żądań dotyczących tokenów dostępu i kodów autoryzacji.

Element <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Wymusza czas ważności tokenów odświeżania w milisekundach. Wartość czasu ważności to wartość wygenerowana przez system plus wartość <RefreshTokenExpiresIn>. Jeśli <RefreshTokenExpiresIn> ma wartość -1, token odświeżania wygasa zgodnie z maksymalnym okresem ważności tokena odświeżania OAuth. Jeśli nie podasz właściwoś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 wykonywania za pomocą zaprogramowanej wartości domyślnej lub przez odwołanie do zmiennej przepływu. Możesz na przykład przechowywać wartość ważności tokena w mapie klucz-wartość, pobierać ją, przypisywać do zmiennej i odwoływać się do niej w zasadach. Na przykład: kvm.oauth.expires_in.

Poniższy zwrotka 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ą.

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

Private Cloud: w przypadku instalacji Edge for Private Cloud domyślna wartość 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 właściwość zgodnie z potrzebami:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Upewnij się, że właścicielem pliku właściwości jest użytkownik „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 jaki typ uprawnień prosi aplikacja kliencka. Jest on używany tylko w przypadku przepływów kodu autoryzacji i typu udzielania dostępu implicit.

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> do skonfigurowania zmiennej przepływu zawierającej wartość typu odpowiedzi. Jeśli na przykład ustawisz ten element na request.header.response_type, Edge będzie szukać typu odpowiedzi w nagłówku żądania. Zobacz też Wysyłanie żądania tokenów dostępu i kodów autoryzacji.

Element <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Gdy ustawiona jest wartość true, istniejący token odświeżania jest używany ponownie, dopóki nie wygaśnie. Jeśli false, nowy token odświeżania jest wydawany przez Apigee Edge, gdy zostanie przedstawiony prawidłowy token odświeżania.

Element <Scope>

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

Jeśli ten element znajduje się w jednej z zasad GenerateAccessToken lub GenerateAuthorizationCode, służy do określania zakresów, które mają przyznać token lub kod. Te wartości są zazwyczaj przekazywane do zasad w żądaniu z aplikacji klienckiej. Możesz skonfigurować element tak, aby przyjmował zmienną przepływu, co pozwoli Ci wybrać sposób przekazywania zakresów w żądaniu. W poniższym przykładzie request.queryparam.scope wskazuje, że zakres powinien być obecny jako parametr zapytania, np. ?scope=READ. Aby wymagać zakresu w nagłówku HTTP, ustaw tę wartość na request.header.scope.

Jeśli ten element pojawia się w zasadzie „VerifyAccessToken”, służy do określania zakresów, które ma narzucać zasada. W przypadku tego typu zasad wartość musi być „twardo zakodowaną” nazwą zakresu – nie można używać zmiennych. Na przykład:

<Scope>A B</Scope>

Zobacz też Zakresy uprawnień OAuth2 i Wysyłanie żądań o tokeny dostępu i kody autoryzacji.

Element <State>

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

W przypadku, gdy aplikacja klienta musi wysłać informacje o stanie do serwera autoryzacji, ten element umożliwia określenie, gdzie Edge powinien szukać wartości stanu. Może ona na przykład być wysyłana jako parametr zapytania lub w nagłówku HTTP. Wartość stanu jest zwykle używana jako zabezpieczenie w celu zapobiegania atakom CSRF.

Na przykład request.queryparam.state wskazuje, że stan powinien być obecny jako parametr zapytania, np. ?state=HjoiuKJH32. Aby wymagać stanu w nagłówku HTTP, ustaw tę wartość na request.header.state. Zapoznaj się też z sekcją 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 o zapisaniu zewnętrznego tokena dostępu. W przeciwnym razie nie zostanie zachowana.

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 usłudze Apigee Edge. Punkt końcowy może obsługiwać wiele typów uprawnień (czyli jeden punkt końcowy może być skonfigurowany tak, aby rozpowszechniać tokeny dostępu dla wielu typów uprawnień). Więcej informacji o punktach końcowych znajdziesz w artykule Informacje o punktach końcowych OAuth. Typ uwierzytelnienia jest przekazywany w żądaniach tokena w parametrze grant_type.

Jeśli nie zostaną określone żadne obsługiwane typy grantów, jedynymi dozwolonymi typami będą authorization_code i implicit. Zobacz też element <GrantType> (element wyższego poziomu używany do określania, gdzie Apigee Edge ma szukać parametru grant_type przekazywanego w żądaniu klienta. Edge sprawdzi, czy wartość parametru grant_type odpowiada jednemu z obsługiwanych typów grantów.

Element <Tokens>/<Token>

Używany w operacjach ValidateToken i InvalidateToken. Zapoznaj się też z sekcją Zatwierdzanie i unieważnianie tokenów dostępu. Element <Token> wskazuje zmienną przepływu, która określa źródło tokena do unieważnienia. Jeśli deweloperzy mają przesyłać tokeny dostępu jako parametry zapytania o nazwie access_token, należy użyć request.queryparam.access_token.

Element <UserName>

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

Ten element jest używany tylko z typem uwierzytelnienia hasłem. W przypadku typu uprawnień hasło dane logowania użytkownika (hasło i nazwa użytkownika) muszą być dostępne dla zasad OAuth 2. 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 spodziewa się znaleźć wartości (domyślnie) w parametrach formularza o nazwach username i password. Jeśli wartości nie zostaną znalezione, zasada zwróci błąd. Za pomocą elementów <PassWord> i <UserName> możesz odwołać się do dowolnej zmiennej przepływu, która zawiera 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.

Zasady OAuth 2 nie robią nic więcej z tymi wartościami; Edge po prostu sprawdza, czy są one obecne. Przed wykonaniem zasad generowania tokenów to twórca interfejsu API musi pobrać wartości żądania i przesłać je do dostawcy tożsamości.

Zapoznaj się też z sekcją o wysyłaniu próśb o tokeny dostępu i kody autoryzacji.

Weryfikowanie tokenów dostępu

Gdy punkt końcowy tokena zostanie skonfigurowany dla serwera proxy interfejsu API, do przepływu, który udostępnia zasobów chronionych, zostanie dołączona odpowiednia zasada OAuthV2, która określa operację VerifyAccessToken.

Aby na przykład zapewnić autoryzację wszystkich żądań do interfejsu API, możesz narzucić weryfikację tokena dostępu za pomocą tej polityki:

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

Zasada jest dołączona do zasobu interfejsu API, który ma być chroniony. Aby mieć pewność, że wszystkie żądania wysyłane 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>

Wymienionych poniżej elementów opcjonalnych można używać do zastępowania domyślnych ustawień operacji VerifyAccessToken.

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

Zapoznaj się też z artykułami Weryfikowanie tokenów dostępu oraz Wysyłanie próśb o tokeny dostępu i kody autoryzacji.

Określanie lokalizacji zmiennych żądań

W przypadku każdego typu finansowania zasady zakładają, że w wiadomościach z prośbami o finansowanie znajduje się lokalizacja lub wymagane informacje. 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 dla poszczególnych parametrów. Podczas obsługi kodu autoryzacji możesz na przykład określić lokalizację kodu autoryzacji, identyfikator klienta, identyfikator URI przekierowania oraz zakres. Mogą one być określone jako nagłówki HTTP, parametry zapytania lub parametry formularza.

Przykład poniżej pokazuje, jak określić lokalizację wymaganych parametrów kodu autoryzacji jako nagłówków 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 to konieczne, aby obsługiwać aplikacje klientów, możesz stosować nagłówki i parametry zapytań w różny sposób:

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

Na każdy parametr 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 i aplikacji działających w przepływie serwera proxy interfejsu API.

Operacja VerifyAccessToken

Podczas wykonywania operacji VerifyAccessToken duża liczba zmiennych przepływu jest wypełniana w kontekście wykonania zastępnika. Te zmienne udostępniają właściwości związane z tokenem dostępu, aplikacją dewelopera, deweloperem i firmą. Aby odczytać dowolną z tych zmiennych i użyć jej w odpowiednim momencie w ramach procesu, możesz użyć na przykład zasady przypisywania wiadomości lub JavaScript. Te zmienne mogą też być przydatne do debugowania.

Zmienne specyficzne dla tokena

Zmienne dotyczące aplikacji

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

Zmienne dla programistów

Jeśli atrybut app.appType ma wartość „Firma”, atrybuty firmy są uzupełnione, a jeśli app.appType ma wartość „Deweloper”, wypełnione są atrybuty dewelopera.

Zmienne specyficzne dla 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 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. Pamiętaj, że zmienne tokenu odświeżania nie mają zastosowania w przypadku procesu udzielania dostępu z użyciem poświadczeń klienta.

Prefiks: oauthv2accesstoken.{policy_name}.{variable_name}

Przykład: oauthv2accesstoken.GenerateTokenPolicy.access_token.

GenerateAccessTokenImplicitGrant

Te zmienne są ustawiane po pomyślnym wykonaniu operacji GenerateAccessTokenImplicit w przypadku przepływu typu niejawny.

Prefiks: oauthv2accesstoken.{policy_name}.{variable_name}

Przykład: oauthv2accesstoken.RefreshTokenPolicy.access_token.

Informacje o błędach

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

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 tę zasadę.

Zmienne błędów

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

Przykładowa odpowiedź na błąd

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

Jeśli <GenerateResponse> ma wartość true, zasada zwraca błędy w tym formacie na potrzeby operacji generowania tokenów i kodów. Pełną listę znajdziesz tutaj Błąd HTTP OAuth odniesienie do odpowiedzi.

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

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

{  
   {  
      "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 zasad jest definiowany przez schemat XML (.xsd). Informacje na temat schematów zasad znajdziesz na GitHubie.

Praca z domyślną konfiguracją OAuth

Każda organizacja (nawet ta w ramach bezpłatnego okresu próbnego) w usłudze Apigee Edge jest obsługiwana za pomocą punktu końcowego tokena OAuth. Punkt końcowy jest wstępnie skonfigurowany za pomocą zasad w serwisie proxy interfejsu API o nazwie oauth. Punkt końcowy tokena możesz zacząć używać od razu po utworzeniu konta w Apigee Edge. Więcej informacji znajdziesz w artykule Omówienie punktów końcowych OAuth.

Czyszczenie tokenów dostępu

Domyślnie tokeny OAuth2 są trwale usuwane z systemu Apigee Edge 3 dni (259 200 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 domyślne. Możesz na przykład skrócić czas oczyszczania, aby zaoszczędzić miejsce na dysku, jeśli generowana jest duża liczba tokenów.

Jeśli korzystasz z Edge for Private Cloud, możesz zmienić to ustawienie domyślne przez ustawienie właściwości organizacji w sposób opisany w tej sekcji. (usuwanie wygasłych tokenów po 3 dniach) dotyczy Edge for Private Cloud w wersji 4.19.01 lub nowszej. We wcześniejszych wersjach domyślny okres trwałego usuwania wynosi 180 dni.

Aktualizacja ustawień oczyszczania w Edge Private Cloud w wersji 4.16.01 i nowszych

Uwaga: ma to wpływ tylko na tokeny wygenerowane po zastosowaniu tych ustawień. Ustawienia nie dotyczą tokenów wygenerowanych wcześniej.

Aktualizacja ustawień oczyszczania w Edge Private Cloud 4.15.07

Uwaga: zmiany te mają wpływ tylko na tokeny wygenerowane po ich zastosowaniu. Nie mają one wpływu na tokeny wygenerowane wcześniej.

Zachowanie niezgodne z RFC

Zasady OAuth 2 zwracają odpowiedź tokena, która zawiera pewne właściwości niezgodne ze standardem RFC. W tabeli poniżej przedstawiono niezgodne właściwości zwrócone przez zasadę OAuthV2 oraz odpowiadające im zgodne właściwości.

Ponadto odpowiedź o błędzie z wygasłym tokenem odświeżania, gdy grant_type = refresh_token to:

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

Odpowiedź zgodna z RFC jest jednak następująca:

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

Powiązane artykuły

• Wprowadzenie do OAuth 2.0