使用 OAuth2 存取 Edge API

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。

Apigee Edge 可讓您發出使用 OAuth2 權杖進行驗證的 Edge API 呼叫。Cloud 帳戶預設會為 Edge 帳戶啟用 OAuth2 支援功能。如果您使用的是 Edge for Private Cloud，您必須先設定 SAML 或 LDAP，才能使用 OAuth2。

OAuth2 的運作方式 (與 Apigee Edge API 搭配使用)

呼叫 Apigee Edge API 時必須進行驗證，才能確認您是誰。為了驗證身分，您必須使用要求存取 API 的 OAuth2 存取權杖。

舉例來說，如果您想取得 Edge 上的機構詳細資料，可以向下列網址傳送要求：

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

但你必須表明自己的身分，才能傳送要求。否則，所有人都能查看貴機構的詳細資料。

此時 OAuth2 就派上用場了。在驗證要求中，我們也需要將存取權杖傳送給我們。存取權杖會告訴我們您的身分，以便確保您能看到機構詳細資料。

幸好，您可以透過將憑證傳送至 Edge OAuth2 服務來取得權杖。這項服務會回應存取和重新整理權杖。

OAuth2 流程：初始要求

下圖顯示了第一次存取 Edge API 時的 OAuth2 流程：

OAuth 流程：第一個要求
圖 1：OAuth 流程：第一個要求

如圖 1 所示，首次向 Edge API 發出要求時：

  1. 你要求存取權杖。您可以使用 Edge API、acurl 或 get_token 完成這項操作。例如： 
    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. Edge OAuth2 服務會透過存取權杖回應，並列印至 stdout；例如： 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    acurl 和 get_token 公用程式會默示將存取和重新整理權杖儲存至 ~/.sso-cli (重新整理權杖不會寫入 stdout)。如果您使用 Edge OAuth2 服務取得權杖，則必須儲存憑證以供日後使用。

  3. 您利用存取權杖將要求傳送至 Edge API。acurl 會自動附加權杖，例如： 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    如果您使用的是其他 HTTP 用戶端，請務必新增存取權杖。例如：

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. Edge API 會執行你的要求，且通常會傳回包含資料的回應。

OAuth2 流程：後續的要求

針對後續的要求，你不需要交換憑證。您可以加入先前擁有的存取權杖，前提是該憑證尚未過期：

OAuth 流程：後續的要求
圖 2：OAuth 流程：後續要求

如圖 2 所示，您已擁有存取權杖：

  1. 您利用存取權杖將要求傳送至 Edge API。acurl 會自動附加權杖。使用其他工具時，必須手動新增權杖。
  2. Edge API 會執行你的要求，且通常會傳回包含資料的回應。

OAuth2 流程：存取權杖到期

如果存取權杖過期 (12 小時後)，您可以使用更新權杖取得新的存取權杖：

OAuth 流程：重新整理存取權杖
圖 3：OAuth 流程：重新整理存取權杖

如圖 3 所示，存取權杖已過期時：

  1. 您將要求傳送至 Edge API，但存取權杖已過期。
  2. Edge API 會拒絕未經授權的要求。
  3. 您將更新權杖傳送至 Edge OAuth2 服務。如果您使用的是 acurl，系統會自動為您完成這項作業。
  4. Edge OAuth2 服務可回應新的存取權杖。
  5. 您會使用新的存取權杖將要求傳送至 Edge API。
  6. Edge API 會執行你的要求，且通常會傳回包含資料的回應。

取得權杖

如要取得可傳送至 Edge API 的存取權杖，除了 curl 等公用程式以外，您還可以使用下列 Apigee 公用程式：

  • get_token 公用程式：交換 Apigee 憑證，以便存取及重新整理可用來呼叫 Edge API 的權杖。
  • acurl 公用程式：提供標準 curl 指令的便利包裝函式。建構至 Edge API 的 HTTP 要求、從 get_token 存取及重新整理權杖，並將存取權杖傳遞至 Edge API。
  • 邊緣 OAuth2 服務中的端點端點：透過呼叫 Edge API，交換 Apigee 憑證來取得存取權並更新權杖。

這些公用程式會交換您的 Apigee 帳戶憑證 (電子郵件地址和密碼)，但其中包含的持續時間如下：

  • 存取權杖將於 12 小時後失效。
  • 更新權杖的有效期限為 30 天。

因此，如果您成功透過 acurl 或 get_token 發出 API 呼叫，30 天內可以繼續使用權杖配對。到期後，您必須重新輸入憑證並取得新的權杖。

透過 OAuth2 存取 Edge API

如要存取 Edge API，請將要求傳送至 API 端點，並加入存取權杖。您可以透過任何 HTTP 用戶端執行這項操作，包括 curl 等指令列公用程式、透過瀏覽器為基礎的使用者介面 (例如 Postman)，或 Apigee 公用程式 (例如 acurl)。

以下各節會說明使用 acurl 和 curl 存取 Edge API 的相關說明。

使用 curl

如要透過 acurl 存取 Edge API，您的初始要求必須包含憑證。Edge OAuth2 服務會透過存取及更新權杖回應。acurl 會將權杖儲存在本機。

後續要求時，acurl 會使用 ~/.sso-cli 中儲存的權杖，因此在憑證到期前，您都不需要再次納入憑證。

下例顯示初始 acurl 要求，取得「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" ]

除了取得機構的詳細資料外，這個範例也顯示第二次要求，取得「helloworld」API Proxy 中的政策清單。第二個要求會在網址中使用「機構」這個縮短的「o」。

請注意，acurl 會自動在第二個要求中傳遞存取權杖。acurl 儲存 OAuth2 權杖後，不需要傳遞使用者憑證，系統會從 ~/.sso-cli 取得後續呼叫的權杖。

詳情請參閱使用 curl 存取 Edge API。

使用 curl

您可以使用 curl 存取 Edge API。為此，您必須先取得存取權並更新權杖。您可以使用 get_token 或 Edge OAuth2 服務等公用程式取得這些憑證。

成功儲存存取權杖後，您必須在呼叫 Edge API 的呼叫中，將其傳送至 Authorization 標頭，如以下範例所示：

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

存取權杖核發後，有效期限為 12 小時。存取權杖到期後，更新權杖可在 30 天內發出另一個存取權杖，且無需提供憑證。Apigee 建議只在述詞權杖到期後要求新的存取權杖，不要輸入憑證並針對每個 API 呼叫提出新的要求。

權杖到期

存取權杖到期後，您可以使用更新權杖取得新的存取權杖，無須再次提交憑證。

視您使用的工具而定，更新存取權杖的方式會有所不同：

  • acurl：無須採取任何行動。當你傳送包含過時權杖的要求時，acurl 會自動重新整理存取權杖。
  • get_token：呼叫 get_token 以更新存取權杖。
  • Edge OAuth2 服務：傳送包含下列項目的要求：
    • 重新整理權杖
    • grant_type 個表單參數已設為「refresh_token」

適用於電腦使用者的 OAuth2

您可以使用 acurl 和 get_token 公用程式，透過適用於機器使用者的 OAuth2 驗證機制，自動存取 Edge API。以下範例說明如何使用 get_token 要求存取權杖，然後將權杖值新增至 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/...'

或者，您也可以使用 acurl 公用程式來合併權杖要求和 curl 呼叫。例如：

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

在這兩種範例中，如果將 -m 的值設為空白字串，系統會避免機器使用者收到 MFA 程式碼。