Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje
![](https://docs.apigee.com/static/api-platform/images/icon_policy_security.jpg?hl=pl)
Co
Zasady weryfikacji klucza interfejsu API umożliwiają egzekwowanie weryfikacji kluczy interfejsu API w czasie działania, dzięki czemu dostęp do interfejsów API mają tylko aplikacje z zatwierdzonymi kluczami interfejsu API. Ta zasada zapewnia, że klucze interfejsu API są prawidłowe, nie zostały unieważnione i zatwierdzone pod kątem wykorzystywania określonych zasobów powiązanych z usługami interfejsu API.
Sample
Klucz w parametrze zapytania
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
W tym przykładzie zasada oczekuje, że klucz interfejsu API znajdzie się w zmiennej przepływu o nazwie request.queryparam.apikey
. Zmienna request.queryparam.{name}
to standardowa zmienna przepływu brzegowego, która jest wypełniana wartością parametru zapytania przekazanego w żądaniu klienta.
To polecenie curl
przekazuje klucz interfejsu API w parametrze zapytania:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
Klucz w nagłówku
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey" /> </VerifyAPIKey>
W tym przykładzie zasada oczekuje, że klucz interfejsu API znajdzie się w zmiennej przepływu o nazwie request.header.x-apikey
. Zmienna request.header.{name}
to standardowa zmienna przepływu Edge, która jest wypełniana wartością nagłówka przekazaną w żądaniu klienta.
Ten cURL pokazuje, jak przekazać klucz interfejsu API w nagłówku:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
Klucz w zmiennej
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
Zasada może się odwoływać do każdej zmiennej zawierającej klucz. Zasada w tym przykładzie wyodrębnia klucz interfejsu API ze zmiennej o nazwie requestAPIKey.key.
Sposób wypełniania tej zmiennej zależy od Ciebie. Możesz na przykład użyć zasady Wyodrębnianie zmiennych, aby wypełniać requestAPIKey.key z parametru zapytania o nazwie myKey, jak pokazano poniżej:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar"> <Source>request</Source> <QueryParam name="myKey"> <Pattern ignoreCase="true">{key}</Pattern> </QueryParam> <VariablePrefix>requestAPIKey</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Zmienne przepływu zasad dostępu
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Edge automatycznie wypełnia zestaw zmiennych przepływu podczas wykonywania zasady weryfikacji klucza interfejsu API dla prawidłowego klucza interfejsu API. Za pomocą tych zmiennych możesz uzyskać dostęp do informacji, takich jak nazwa i identyfikator aplikacji, oraz informacje o deweloperze lub firmie, która zarejestrowała aplikację. W przykładzie powyżej za pomocą zasad przypisywania wiadomości możesz uzyskać dostęp do imienia, nazwiska i adresu e-mail programisty po wykonaniu operacji weryfikacji klucza interfejsu API.
Wszystkie te zmienne mają przedrostek:
verifyapikey.{policy_name}
W tym przykładzie nazwa zasady weryfikacji klucza interfejsu API to „verify-api-key”. Dlatego poprzez dostęp do zmiennej verifyapikey.verify-api-key.developer.firstName.
odwołujesz się do imienia dewelopera, który wysłał żądanie.
Dowiedz się więcej
Informacje o zasadzie weryfikacji klucza interfejsu API
Gdy deweloper rejestruje aplikację na Edge, Edge automatycznie generuje parę klucza klienta i obiektu tajnego. Para klucza klienta i obiektu tajnego możesz zobaczyć w interfejsie użytkownika Edge lub uzyskać do nich dostęp za pomocą interfejsu Edge API.
W momencie rejestracji aplikacji deweloper wybiera co najmniej jedną usługę interfejsu API, która zostanie powiązana z aplikacją. Usługa API jest zbiorem zasobów dostępnych przez serwery proxy interfejsu API. Następnie deweloper przekazuje klucz interfejsu API (klucz klienta) w ramach każdego żądania wysyłanego do interfejsu API w usłudze API powiązanej z aplikacją. Więcej informacji znajdziesz w artykule Omówienie publikowania.
Klucze interfejsu API można wykorzystać jako tokeny uwierzytelniania lub uzyskać tokeny dostępu OAuth. W protokole OAuth klucze interfejsu API są określane jako „identyfikator klienta”. Nazwy mogą być używane zamiennie. Więcej informacji znajdziesz w artykule Strona główna protokołu OAuth.
Edge automatycznie wypełnia zestaw zmiennych przepływu podczas wykonywania zasady weryfikacji klucza interfejsu API. Więcej informacji znajdziesz poniżej w sekcji Zmienne przepływu.
Odniesienie do elementu
Oto elementy i atrybuty, które możesz konfigurować w tej zasadzie:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> </VerifyAPIKey>
Atrybuty <VerifyAPIKey>
Ten przykład pokazuje atrybuty w tagu <VerifyAPIKey>
:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
Tabela poniżej zawiera opis atrybutów wspólnych dla wszystkich elementów nadrzędnych zasad:
Atrybut | Opis | Domyślne | Obecność |
---|---|---|---|
name |
Wewnętrzna nazwa zasady. Wartość atrybutu Opcjonalnie możesz użyć elementu |
Nie dotyczy | Wymagane |
continueOnError |
Ustaw wartość Ustaw jako |
false | Opcjonalnie |
enabled |
Ustaw jako Ustaw wartość |
prawda | Opcjonalnie |
async |
Ten atrybut został wycofany. |
false | Wycofano |
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>
Domyślne |
Nie dotyczy Jeśli pominiesz ten element, zostanie użyta wartość atrybutu |
---|---|
Obecność | Opcjonalnie |
Typ | Ciąg znaków |
Element <APIKey>
Ten element określa zmienną przepływu, która zawiera klucz interfejsu API. Zwykle klient wysyła klucz interfejsu API w parametrze zapytania, nagłówku HTTP lub parametrze formularza. Jeśli np. klucz jest wysyłany w nagłówku o nazwie x-apikey
, klucz znajdzie się w zmiennej: request.header.x-apikey
Domyślne | Nie dotyczy |
---|---|
Obecność | Wymagane |
Typ | Ciąg znaków |
Atrybuty
W tabeli poniżej opisujemy atrybuty elementu <APIKey>
.
Atrybut | Opis | Domyślne | Obecność |
---|---|---|---|
referencja |
Odwołanie do zmiennej zawierającej klucz interfejsu API. Dozwolona jest tylko 1 lokalizacja na zasadę. |
Nie dotyczy | Wymagane |
Przykłady
W tych przykładach klucz jest przekazywany w parametrach i nagłówku x-apikey
.
Jako parametr zapytania:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.x-apikey"/> </VerifyAPIKey>
Jako nagłówek HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey"/> </VerifyAPIKey>
Jako parametr formularza HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
Schematy
Zmienne przepływu
Gdy zasada Weryfikacja klucza interfejsu API jest egzekwowana dla prawidłowego klucza interfejsu API, Edge wypełnia zestaw zmiennych przepływu. Te zmienne są dostępne dla zasad lub kodu uruchamianego na późniejszym etapie procesu i często są wykorzystywane do niestandardowego przetwarzania na podstawie atrybutów klucza interfejsu API, takich jak nazwa aplikacji, usługa API używana do autoryzacji klucza lub niestandardowe atrybuty klucza interfejsu API.
Zasada wypełnia kilka różnych typów zmiennych przepływu, w tym:
- Ogólne
- Promująca aplikację
- Deweloper
- Firma
- Statystyki
Każdy typ zmiennej przepływu ma inny prefiks. Wszystkie zmienne są skalarami, z wyjątkiem tych oznaczonych specjalnie jako tablice.
Ogólne zmienne przepływu
W tabeli poniżej znajdziesz ogólne zmienne przepływu wypełniane przez zasadę Zweryfikuj klucz interfejsu API. Wszystkie te zmienne mają przedrostek:
verifyapikey.{policy_name}
np.: verifyapikey.{policy_name}.client_id
Dostępne zmienne to:
Zmienna | Opis |
---|---|
client_id |
Klucz klienta (nazywany kluczem interfejsu API lub kluczem aplikacji) dostarczonym przez aplikację wysyłającą żądanie. |
client_secret |
Tajny klucz klienta powiązany z kluczem klienta. |
redirection_uris |
Wszelkie identyfikatory URI przekierowania występujące w żądaniu. |
developer.app.id |
Identyfikator aplikacji dewelopera wysyłającej żądanie. |
developer.app.name |
Nazwa aplikacji dewelopera, z której pochodzi żądanie. |
developer.id |
Identyfikator dewelopera zarejestrowanego jako właściciel aplikacji wysyłającej żądanie. |
developer.{custom_attrib_name} |
Wszystkie atrybuty niestandardowe uzyskane z profilu App Key. |
DisplayName |
Wartość atrybutu <DisplayName> zasady. |
failed |
Ustaw wartość „true” (prawda), gdy weryfikacja klucza interfejsu API się nie powiedzie. |
{custom_app_attrib} |
Dowolny atrybut niestandardowy pobrany z profilu aplikacji. Podaj nazwę atrybutu niestandardowego. |
apiproduct.name* |
Nazwa usługi API użytej do zweryfikowania żądania. |
apiproduct.{custom_attrib_name}* |
Dowolny atrybut niestandardowy pobrany z profilu produktu w interfejsie API. |
apiproduct.developer.quota.limit* |
Ewentualny limit ustawiony w usłudze API. |
apiproduct.developer.quota.interval* |
Interwał limitu ustawiony w usłudze API (jeśli istnieje). |
apiproduct.developer.quota.timeunit* |
Jednostka czasu limitu ustawiona w usłudze API (jeśli istnieje). |
* Zmienne usług API są wypełniane automatycznie, jeśli usługi API są skonfigurowane z prawidłowym środowiskiem, serwerami proxy i zasobami (pobranymi z proxy.pathsuffix ). Instrukcje konfigurowania usług API znajdziesz w artykule o używaniu interfejsu Edge Management API do publikowania interfejsów API. |
Zmienne przepływu aplikacji
Ta zasada uzupełnia podane niżej zmienne przepływu zawierające informacje o aplikacji. Wszystkie te zmienne mają przedrostek:
verifyapikey.{policy_name}.app
.
Na przykład:
verifyapikey.{policy_name}.app.name
Dostępne zmienne to:
Zmienna | Opis |
---|---|
name |
Nazwa aplikacji. |
id |
Identyfikator aplikacji. |
accessType |
Nieużywane przez Apigee. |
callbackUrl |
Adres URL wywołania zwrotnego aplikacji. Zwykle używany tylko w przypadku OAuth. |
DisplayName |
Wyświetlana nazwa aplikacji. |
status |
Stan aplikacji, np. „zatwierdzono” lub „anulowano”. |
apiproducts |
Tablica zawierająca listę usług API powiązanych z aplikacją. |
appFamily |
każda rodzina aplikacji zawierająca aplikację lub „domyślna”. |
appParentStatus |
stan elementu nadrzędnego aplikacji, na przykład „aktywna” lub „nieaktywna”; |
appType |
Typ aplikacji, jako „Firma” lub „Deweloper”. |
appParentId |
Identyfikator aplikacji nadrzędnej. |
created_at |
Data i godzina utworzenia aplikacji. |
created_by |
Adres e-mail dewelopera, który utworzył aplikację. |
last_modified_at |
Data i godzina ostatniej aktualizacji aplikacji. |
last_modified_by |
Adres e-mail dewelopera, który ostatnio aktualizował aplikację. |
{app_custom_attributes} |
Dowolny niestandardowy atrybut aplikacji. Podaj nazwę atrybutu niestandardowego. |
Zmienne przepływu dewelopera
Zasada uzupełnia podane niżej zmienne przepływu zawierające informacje o deweloperze. Wszystkie te zmienne mają przedrostek:
verifyapikey.{policy_name}.developer
Na przykład:
verifyapikey.{policy_name}.developer.id
Dostępne zmienne to:
Zmienna | Opis |
---|---|
id |
Zwraca organizację {org_name}@@{developer_id} |
userName |
Nazwa użytkownika dewelopera. |
firstName |
Imię dewelopera. |
lastName |
Nazwisko dewelopera. |
email |
Adres e-mail dewelopera. |
status |
Stan dewelopera jako aktywny, nieaktywny lub login_lock. |
apps |
Tablica aplikacji powiązanych z deweloperem. |
created_at |
Data i godzina utworzenia dewelopera. |
created_by |
Adres e-mail użytkownika, który utworzył dewelopera. |
last_modified_at |
Data i godzina ostatniej modyfikacji dewelopera. |
last_modified_by |
Adres e-mail użytkownika, który zmodyfikował dewelopera. |
{developer_custom_attributes} |
Dowolny niestandardowy atrybut dewelopera. Podaj nazwę atrybutu niestandardowego. |
Company |
Nazwa firmy powiązanej z deweloperem (jeśli istnieje). |
Zmienne przepływu firmy
Ta zasada uzupełnia podane niżej zmienne przepływu zawierające informacje o firmie. Wszystkie te zmienne mają przedrostek:
verifyapikey.{policy_name}.company
Na przykład:
verifyapikey.{policy_name}.company.name
Dostępne zmienne to:
Zmienna | Opis |
---|---|
name |
Nazwa firmy. |
displayName |
Wyświetlana nazwa firmy. |
id |
Identyfikator firmy. |
apps |
Tablica zawierająca listę aplikacji firmowych. |
appOwnerStatus |
Stan właściciela aplikacji: aktywny, nieaktywny lub login_lock.
|
created_at |
Data i godzina utworzenia firmy. |
created_by |
Adres e-mail użytkownika, który utworzył firmę. |
last_modified_at |
Data i godzina ostatniej modyfikacji firmy. |
last_modified_by |
Adres e-mail użytkownika, który ostatnio modyfikował firmę. |
{company_custom_attributes} |
Dowolny niestandardowy atrybut firmy. Podaj nazwę atrybutu niestandardowego. |
Zmienne Analytics
Gdy dla prawidłowego klucza interfejsu API egzekwowana jest zasada weryfikacji klucza interfejsu API, poniższe zmienne są automatycznie wypełniane w Analytics. Te zmienne są wypełniane tylko przez zasadę weryfikacji klucza interfejsu API i zasady OAuth.
Zmienne i wartości mogą służyć jako wymiary do tworzenia raportów Analytics, które dają wgląd we wzorce konsumpcji przez deweloperów i aplikacje.
- apiproduct.name
- developer.app.name
- client_id
- developer.id
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.
Kod błędu | Stan HTTP | Przyczyna |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | Firma powiązana z aplikacją dewelopera, która ma klucz interfejsu API, którego używasz, jest nieaktywna. Jeśli stan firmy to nieaktywna, nie będziesz mieć dostępu do powiązanych z nią deweloperów ani aplikacji. Administrator organizacji może zmienić stan firmy za pomocą interfejsu API zarządzania. Zobacz Ustawianie stanu firmy. |
keymanagement.service.DeveloperStatusNotActive |
401 |
Deweloper, który utworzył aplikację dewelopera i ma klucz interfejsu API, którego używasz, ma stan nieaktywny. Gdy stan dewelopera aplikacji jest nieaktywny, wszystkie utworzone przez niego aplikacje są dezaktywowane. Administrator z odpowiednimi uprawnieniami (np. administrator organizacji) może zmienić stan dewelopera w ten sposób:
|
keymanagement.service.invalid_client-app_not_approved |
401 | Aplikacja dewelopera powiązana z kluczem interfejsu API została unieważniona. Unieważniona aplikacja nie ma dostępu do żadnych usług API ani nie może wywoływać żadnych interfejsów API zarządzanych przez Apigee Edge. Administrator organizacji może zmienić stan aplikacji programisty za pomocą interfejsu API zarządzania. Więcej informacji znajdziesz w sekcji Zatwierdzanie lub unieważnianie aplikacji dewelopera. |
oauth.v2.FailedToResolveAPIKey |
401 | Zasada oczekuje klucza interfejsu API w zmiennej określonej w elemencie <APIKey> zasady. Ten błąd występuje, gdy oczekiwana zmienna nie istnieje (nie można jej rozwiązać). |
oauth.v2.InvalidApiKey |
401 | Klucz interfejsu API został odebrany przez Edge, ale jest on nieprawidłowy. Podczas wyszukiwania klucza w bazie danych Edge musi być dokładnie zgodny z tym, który został wysłany w żądaniu. Jeśli interfejs API wcześniej działał, sprawdź, czy nie został on wygenerowany ponownie. Jeśli klucz został wygenerowany ponownie, przy próbie użycia starego klucza pojawi się ten błąd. Więcej informacji znajdziesz w artykule o rejestrowaniu aplikacji i zarządzaniu kluczami interfejsu API. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | Edge otrzymał klucz interfejsu API i jest on prawidłowy. Nie pasuje jednak do zatwierdzonego klucza w aplikacji programisty powiązanego z serwerem proxy interfejsu API za pośrednictwem usługi. |
Błędy wdrażania
Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.
Nazwa błędu | Przyczyna |
---|---|
SpecifyValueOrRefApiKey |
Element <APIKey> nie ma określonej wartości lub klucza. |
Zmienne błędów
Te zmienne są ustawiane, gdy wystąpi błąd środowiska wykonawczego. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z naruszeniem zasad.
Zmienne | Gdzie | Przykład |
---|---|---|
fault.name="fault_name" |
fault_name to nazwa błędu podana w tabeli Błędy środowiska wykonawczego powyżej. Nazwa błędu to ostatnia część kodu. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name to określona przez użytkownika nazwa zasady, która spowodowała błąd. | oauthV2.VK-VerifyAPIKey.failed = true |
Przykładowe odpowiedzi na błędy
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
Przykładowa reguła błędu
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>