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

Korzystanie z protokołu OAuth2 do uzyskiwania dostępu do interfejsu Edge API

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

Apigee Edge umożliwia wykonywanie wywołań interfejsu Edge API uwierzytelnianych za pomocą tokenów OAuth2. Obsługa protokołu OAuth2 jest domyślnie włączona w Edge dla kont Cloud. Jeśli używasz Edge na potrzeby Private Cloud, nie możesz używać protokołu OAuth2 bez uprzedniego skonfigurowania SAML lub LDAP.

Jak działa protokół OAuth2 (z interfejsem Apigee Edge API)

Wywołania interfejsu Apigee Edge API wymagają uwierzytelniania, abyśmy mogli mieć pewność, że jesteś tym, za kogo się podaje. Aby Cię uwierzytelnić, wraz z żądaniem dostępu do interfejsu API musimy otrzymać token dostępu OAuth2.

Jeśli na przykład chcesz uzyskać szczegółowe informacje o organizacji w Edge, wyślij żądanie na adres URL podobny do tego:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

Nie możesz jednak wysłać takiej prośby bez podania nam swojej tożsamości. W przeciwnym razie każdy może zobaczyć szczegóły Twojej organizacji.

Właśnie tu do akcji wkracza protokół OAuth2: aby Cię uwierzytelnić, musisz też przesłać nam w tym żądaniu token dostępu. Token dostępu informuje nas, kim jesteś, dzięki czemu mamy pewność, że możesz zobaczyć szczegółowe informacje o organizacji.

Na szczęście możesz uzyskać token, wysyłając swoje dane logowania do usługi Edge OAuth2. Usługa odpowiada za pomocą tokenów dostępu i odświeżania.

Proces OAuth2: początkowe żądanie

Poniższy obraz przedstawia przepływ OAuth2 przy pierwszym uruchomieniu interfejsu Edge API:

Proces OAuth: pierwsze żądanie — **Rysunek 1.** Przepływ protokołu OAuth: pierwsze żądanie

Jak pokazujemy na Rys. 1, gdy wysyłasz wstępne żądanie do interfejsu Edge API:

Prosisz o token dostępu. Możesz to zrobić za pomocą interfejsu Edge API, acurl lub get_token. Przykład:

get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456

Usługa Edge OAuth2 w odpowiedzi wysyła token dostępu i wyświetla go na stronie stdout, na przykład:

Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

Narzędzia acurl i get_token dyskretnie zapisują tokeny dostępu i odświeżenia w ~/.sso-cli (token odświeżania nie jest zapisany w stdout). Jeśli do pobierania tokenów używasz usługi Edge OAuth2, musisz je zapisać do użytku w przyszłości.

Wysyłasz żądanie do interfejsu Edge API z tokenem dostępu. acurl automatycznie dołącza token, na przykład:
```
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
```
Jeśli używasz innego klienta HTTP, pamiętaj, by dodać token dostępu. Na przykład:
```
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
```
Interfejs Edge API wykonuje Twoje żądanie i zwykle zwraca odpowiedź z danymi.

Proces OAuth2: kolejne żądania

Przy kolejnych żądaniach nie musisz wymieniać danych logowania na token. Zamiast tego możesz dołączyć token dostępu, który już masz, o ile jeszcze nie wygasł:

Proces OAuth: kolejne żądania — **Rysunek 2.** Przepływ protokołu OAuth: kolejne żądania

Jak widać na Rys. 2, jeśli masz już token dostępu:

Wysyłasz żądanie do interfejsu Edge API z tokenem dostępu. acurl automatycznie dołącza token. Jeśli używasz innych narzędzi, musisz dodać token ręcznie.
Interfejs Edge API wykonuje Twoje żądanie i zwykle zwraca odpowiedź z danymi.

Proces OAuth2: po wygaśnięciu tokena dostępu

Gdy token dostępu wygaśnie (po 12 godzinach), możesz za jego pomocą uzyskać nowy token dostępu:

Przepływ protokołu OAuth: odświeżanie tokena dostępu — **Rysunek 3.** Proces OAuth: odświeżanie tokena dostępu

Jak widać na Rys. 3, gdy token dostępu wygaśnie:

Wysyłasz żądanie do interfejsu Edge API, ale token dostępu wygasł.
Interfejs Edge API odrzuca Twoje żądanie jako nieautoryzowane.
Wysyłasz token odświeżania do usługi Edge OAuth2. Jeśli używasz acurl, dzieje się to automatycznie.
Usługa Edge OAuth2 w odpowiedzi wysyła nowy token dostępu.
Wysyłasz żądanie do interfejsu Edge API z nowym tokenem dostępu.
Interfejs Edge API wykonuje Twoje żądanie i zwykle zwraca odpowiedź z danymi.

Odbierz tokeny

Aby uzyskać token dostępu, który możesz wysłać do interfejsu Edge API, możesz użyć nie tylko narzędzia curl, ale też tych narzędzi Apigee:

get_tokentool: wymienia dane logowania Apigee na potrzeby dostępu i tokeny odświeżania, których możesz używać do wywoływania Edge API.
Narzędzie acurl: udostępnia estetyczne otoczenie standardowego polecenia curl. Konstruuje żądania HTTP wysyłane do interfejsu Edge API, uzyskuje tokeny dostępu i odświeżania z get_token oraz przekazuje token dostępu do interfejsu Edge API.
Punkty końcowe tokena w usłudze Edge OAuth2: wymień dane logowania Apigee na tokeny dostępu i odświeżenia, wywołując interfejs Edge API.

Te narzędzia wymieniają dane logowania do konta Apigee (adres e-mail i hasło) na tokeny o następujących czasach trwania:

Tokeny dostępu wygasają po 12 godzinach.
Tokeny odświeżania wygasają po 30 dniach.

W związku z tym po wywołaniu interfejsu API za pomocą acurl lub get_token możesz używać tej pary tokenów przez 30 dni. Po wygaśnięciu okresu logowania musisz ponownie wpisać swoje dane uwierzytelniające i uzyskać nowe tokeny.

Dostęp do interfejsu Edge API przy użyciu protokołu OAuth2

Aby uzyskać dostęp do interfejsu Edge API, musisz wysłać żądanie do punktu końcowego interfejsu API i dołączyć token dostępu. Możesz to zrobić za pomocą dowolnego klienta HTTP, w tym narzędzia wiersza poleceń, np. curl, interfejsu użytkownika działającego w przeglądarce (np. Postman) lub narzędzia Apigee, takiego jak acurl.

Uzyskiwanie dostępu do interfejsu Edge API za pomocą acurl i curl opisano w kolejnych sekcjach.

Użyj adresu acurl

Aby uzyskać dostęp do interfejsu Edge API za pomocą acurl, początkowe żądanie musi zawierać Twoje dane logowania. Usługa Edge OAuth2 w odpowiedzi wysyła tokeny dostępu i odświeżania. acurl zapisuje tokeny lokalnie.

W kolejnych żądaniach acurl używa zapisanych tokenów w ~/.sso-cli, dzięki czemu nie musisz ponownie podawać danych logowania, dopóki tokeny nie wygasną.

Ten przykład przedstawia początkowe żądanie acurl, które pobiera szczegóły organizacji „ahamilton-eval”:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

Oprócz uzyskania informacji o organizacji ten przykład pokazuje też drugie żądanie, które pobiera listę zasad w serwerze proxy interfejsu API „helloworld”. W drugim żądaniu w adresie URL użyto skrótu „o” zamiast słowa „organizacje”.

Pamiętaj, że acurl automatycznie przekazuje token dostępu przy drugim żądaniu. Nie musisz przekazywać danych logowania użytkownika, gdy acurl przechowuje tokeny OAuth2. Do kolejnych wywołań otrzymuje token z usługi ~/.sso-cli.

Więcej informacji znajdziesz w artykule na temat uzyskiwania dostępu do interfejsu Edge API za pomocą adresu acurl.

Użyj zwinięcia

Możesz użyć curl, aby uzyskać dostęp do interfejsu Edge API. Aby to zrobić, musisz najpierw uzyskać tokeny dostępu i odświeżania. Możesz je uzyskać za pomocą narzędzia takiego jak get_token lub usługi Edge OAuth2.

Po zapisaniu tokena dostępu przekazujesz go w nagłówku Authorization wywołań do interfejsu Edge API, jak pokazano w poniższym przykładzie:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token dostępu jest ważny przez 12 godzin od jego wystawienia. Po wygaśnięciu tokenu dostępu możesz go używać przez 30 dni do wydania innego tokena dostępu bez wymagania danych logowania. Apigee zaleca, aby żądać nowego tokena dostępu dopiero po wygaśnięciu tokena strony odsyłającej, zamiast wpisywać dane logowania i tworzyć nowe żądanie przy każdym wywołaniu interfejsu API.

Wygaśnięcie tokena

Po wygaśnięciu tokena dostępu możesz za jego pomocą uzyskać nowy token dostępu bez konieczności ponownego przesyłania danych logowania.

Sposób odświeżania tokena dostępu zależy od używanego narzędzia:

acurl: nie musisz niczego robić. acurl automatycznie odświeża token dostępu, gdy wysyłasz żądanie, które zawiera nieaktualny.
get_token: wywołaj get_token, aby odświeżyć token dostępu.
Usługa OAuth2 Edge – wyślij żądanie zawierające:
- Token odświeżania
- Parametr formularza grant_type ustawiono na „refresh_token”

OAuth2 dla użytkowników komputerów

Za pomocą narzędzi acurl i get_token możesz utworzyć skrypt zautomatyzowanego dostępu do interfejsów API Edge z uwierzytelnianiem OAuth2 dla użytkowników komputerów. Poniższy przykład pokazuje, jak za pomocą polecenia get_token zażądać tokena dostępu, a następnie dodać jego wartość do wywołania curl:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Możesz też połączyć żądanie tokena i wywołanie curl, używając narzędzia acurl. Na przykład:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

W obu przykładach ustawienie wartości -m na pusty ciąg znaków uniemożliwi użytkownikowi komputera prośbę o podanie kodu MFA.