使用 OAuth2 存取 Edge API

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

OAuth2 運作方式 (搭配 Apigee Edge API)

呼叫 Apigee Edge API 時需要驗證，確保您是您所聲稱的身分。為驗證您的身分，您必須在要求中傳送 OAuth2 存取權杖，才能存取 API。

舉例來說，如要取得 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。
  • Edge OAuth2 服務中的權杖端點：透過呼叫 Edge API，以 Apigee 憑證換取存取和重新整理權杖。

這些公用程式會將您的 Apigee 帳戶憑證 (電子郵件地址和密碼) 換成下列有效時間的權杖：

  • 存取權杖會在 12 小時後失效。
  • 重新整理權杖的有效期限為 30 天。

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

使用 OAuth2 存取 Edge API

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

下節將說明如何使用 acurl 和 curl 存取 Edge API。

使用 acurl

如要使用 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 中的政策清單。第二個要求在網址中將「organizations」縮寫為「o」。

請注意，acurl 會在第二次要求中自動傳遞存取權杖。acurl儲存 OAuth2 權杖後，您就不必傳遞使用者憑證。並從 ~/.sso-cli 取得權杖，以供後續呼叫使用。

詳情請參閱「使用 acurl 存取 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 的值設為空字串，可防止系統提示電腦使用者輸入多重驗證碼。