使用 OAuth2 存取 Edge API

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

Apigee Edge 可讓您進行以 OAuth2 權杖驗證的 Edge API 呼叫。根據預設,系統會為 Cloud 帳戶啟用 Edge 的 OAuth2 支援功能。如果您在私有雲使用 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 APIacurlget_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

    acurlget_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 天後失效。

因此,使用 acurlget_token 成功發出 API 呼叫後,您就可以在 30 天內繼續使用權杖組合。到期後,您必須重新輸入憑證並取得新權杖。

透過 OAuth2 存取 Edge API

如要存取 Edge API,請向 API 端點傳送要求並加入存取權杖。 方法適用於任何 HTTP 用戶端,包括指令列公用程式 (例如 curl)、瀏覽器式 UI (例如 Postman),或是 acurl 等 Apigee 公用程式。

以下章節會說明使用 acurlcurl 存取 Edge API 的方式。

使用 curl

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

後續要求時,acurl 會使用 ~/.sso-cli 中儲存的權杖,因此在權杖過期前,您無須再次納入憑證。

以下範例顯示獲取「ahamilton-eval」機構詳細資料的初始 acurl 要求:

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」縮短「o」。

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

詳情請參閱「使用 acurl 存取 Edge API」一文。

使用 curl

您可以使用 curl 存取 Edge API。如要執行上述操作,您必須先取得存取權和更新權杖。您可以使用 get_tokenEdge 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

您可以使用 acurlget_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 代碼。