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

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

Apigee Edge umożliwia wykonywanie wywołań interfejsu Edge API przy użyciu tokenów OAuth2. Obsługa protokołu OAuth2 jest domyślnie włączona w Edge na kontach Cloud. Jeśli używasz Edge w chmurze Private Cloud nie można używać protokołu OAuth2 bez najpierw skonfiguruj SAML lub LDAP.

Jak działa OAuth2 (z Apigee Edge API)

Wywołania interfejsu Apigee Edge API wymagają uwierzytelniania, abyśmy mieli pewność, że jesteś osobą mówisz, że jesteś. Aby Cię uwierzytelnić, wraz z Twoim żądaniem musi zostać wysłany token dostępu OAuth2 dostęp do interfejsu API.

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

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

Nie możesz jednak po prostu wysłać tej prośby bez poinformowania nas, kim jesteś. W przeciwnym razie każdy może wyświetlić szczegółowe informacje o Twojej organizacji.

Dlatego właśnie otrzymujesz protokół OAuth2: aby Cię uwierzytelnić, musisz wysłać nam token dostępu. również w tym żądaniu. Token dostępu informuje nas, kim jesteś, i mamy pewność, że możesz zawierają informacje o Twojej organizacji.

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

Przepływ OAuth2: wstępne żądanie

Poniższy obraz przedstawia przepływ OAuth2, gdy uzyskujesz dostęp do interfejsu Edge API po raz pierwszy godzina:

Przepływ OAuth: pierwsze żądanie
Rys. 1. Proces OAuth: pierwsze żądanie

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

  1. Wysyłam prośbę o token dostępu. Możesz to zrobić za pomocą Edge API, acurl lub get_token. Na 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
  2. Usługa Edge OAuth2 wysyła token dostępu i drukuje go na serwerze stdout. np.: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    Narzędzia acurl i get_token dyskretnie zapisują dostęp tokeny odświeżania w: ~/.sso-cli (token odświeżania nie jest zapisywany w stdout. Jeśli do uzyskiwania tokenów używasz usługi Edge OAuth2, musisz je zapisać dla używać ich później.

  3. Wysyłasz żądanie do interfejsu Edge API z tokenem dostępu. acurl załączniki token automatycznie, np.: 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    Jeśli używasz innego klienta HTTP, pamiętaj o dodaniu tokena dostępu. Na przykład:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. Interfejs Edge API wykonuje żądanie i zwykle zwraca odpowiedź z danymi.

Przepływ OAuth2: kolejne żądania

W przypadku kolejnych żądań nie musisz wymieniać danych logowania na token. Zamiast tego: możesz po prostu podać token dostępu, który już masz, o ile jeszcze nie wygasł:

Przepływ OAuth: kolejne żądania
Rys. 2. Przepływ OAuth: kolejne żądania

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

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

Przepływ OAuth2: gdy token dostępu wygaśnie

Gdy token dostępu wygaśnie (po 12 godzinach), możesz go użyć, aby uzyskać nowy token dostępu:

Przepływ 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:

  1. Wysyłasz żądanie do interfejsu Edge API, ale Twój token dostępu wygasł.
  2. Interfejs Edge API odrzuca Twoje żądanie jako nieautoryzowane.
  3. Wysyłasz token odświeżania do usługi Edge OAuth2. Jeśli korzystasz z usługi acurl, zostanie ona wykonana. automatycznie.
  4. Usługa Edge OAuth2 wysyła w odpowiedzi nowy token dostępu.
  5. Wysyłasz do interfejsu Edge API żądanie z nowym tokenem dostępu.
  6. Interfejs Edge API wykonuje żądanie i zwykle zwraca odpowiedź z danymi.

Uzyskaj tokeny

Aby uzyskać token dostępu, który możesz wysłać do interfejsu Edge API, możesz użyć: Narzędzia Apigee oprócz narzędzi takich jak curl:

  • get_token tool (Narzędzie get_token): wymienia dane logowania do Apigee, aby uzyskać dostęp. i odśwież tokeny, których można używać do wywoływania interfejsu Edge API.
  • acurl Utility: zapewnia wygodny kod towarzyszący curl. Konstruuje żądania HTTP do Edge API, uzyskuje dostęp i tokeny odświeżania od get_token oraz przekazuje token dostępu do przy użyciu Edge API.
  • Punkty końcowe tokena w usłudze Edge OAuth2: wymień Dane logowania Apigee dotyczące dostępu i odświeżania tokenów za pomocą wywołania interfejsu Edge API.

Te narzędzia wymieniają Twoje dane logowania do konta Apigee (adres e-mail i hasła) w przypadku tokenów o następujących czasach trwania:

  • Tokeny dostępu wygasają po 12 godzinach.
  • Tokeny odświeżania tracą ważność po 30 dniach.

Dlatego po pomyślnym wywołaniu interfejsu API za pomocą acurl lub get_token możesz dalej używać tej pary przez 30 dni. Po wygaśnięciu konieczne będzie ponowne podanie dane logowania i wygeneruj 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żna to zrobić za pomocą dowolnego klienta HTTP, w tym narzędzia wiersza poleceń, takiego jak curl, interfejsu działającego w przeglądarce, np. Postman, lub narzędzia Apigee, takiego jak acurl.

Dostęp do interfejsu Edge API za pomocą acurl i curl opisano w w kolejnych sekcjach.

Użyj polecenia acurl

Aby można było uzyskać dostęp do interfejsu Edge API za pomocą interfejsu acurl, początkowe żądanie musi zawierać dane logowania. Usługa Edge OAuth2 odpowiada tokenom dostępu i odświeżania. acurl zapisuje tokeny lokalnie.

W kolejnych żądaniach acurl używa tokenów zapisanych w ~/.sso-cli, więc aby nie trzeba było ponownie wpisywać danych logowania, dopóki tokeny nie stracą ważności.

Poniższy przykład pokazuje pierwsze żądanie acurl, które pobiera szczegóły dotyczące „ahamilton-eval” organizacja:

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 w tym przykładzie pokazujemy również drugie żądanie. pobierającego listę zasad z „helloworld” Proxy API. W drugim żądaniu skrócenie „o” dla „organizacji” w adresie URL.

Pamiętaj, że w drugim żądaniu acurl automatycznie przekazuje token dostępu. Ty nie muszą przekazywać danych logowania użytkownika, gdy acurl przechowuje tokeny OAuth2. it pobiera token z ~/.sso-cli dla kolejnych wywołań.

Więcej informacji znajdziesz w artykule Uzyskiwanie dostępu do interfejsu Edge API przy użyciu acurl.

Użyj curl

Aby uzyskać dostęp do interfejsu Edge API, możesz użyć adresu curl. Aby to zrobić, musisz najpierw pobrać i odświeżania tokenów. Możesz je pobrać przy użyciu narzędzia takiego jak get_token lub Usługa Edge OAuth2.

Po zapisaniu tokena dostępu przekaż go w Nagłówek Authorization wywołań interfejsu Edge API, jak w tym przykładzie programy:

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 wydania. Po wygaśnięciu tokena dostępu możesz go używać przez 30 dni do wygenerowania inny token dostępu bez konieczności podawania danych logowania. Apigee zaleca żądanie nowego tokena dostępu dopiero po wygaśnięciu tokena odesłania, wpisując dane logowania i wysyłając nowe żądanie przy każdym wywołaniu interfejsu API.

Wygaśnięcie tokena

Po wygaśnięciu tokena dostępu możesz go użyć, aby uzyskać nowy token dostępu bez bez konieczności ponownego przesłania danych logowania.

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

  • acurl: nie musisz nic robić. acurl automatycznie odświeża token dostępu .
  • get_token: wywołaj get_token, aby odświeżyć token dostępu.
  • Usługa Edge OAuth2: wyślij żądanie zawierające:
    • Token odświeżania
    • Parametr formularza grant_type ustawiono na „refresh_token”

OAuth2 dla użytkowników komputerów

Do skryptu automatycznego dostępu możesz użyć narzędzi acurl i get_token do interfejsów Edge API z uwierzytelnianiem OAuth2 dla użytkowników maszyn. Ten przykład pokazuje, jak użyj get_token do zażądać tokena dostępu, a następnie dodać wartość tokena 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 za pomocą 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 przed wyświetleniem prośby o kod MFA.