您正在查看 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 流程:
如圖 1 所示,初始要求至 Edge API 時:
- 您要求存取權杖。您可以使用 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
- Edge OAuth2 服務使用存取權杖回應,並將存取權杖輸出至
stdout
,例如:Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0 RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG 420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M 2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw
acurl
和get_token
公用程式會自動將存取權和更新權杖儲存至~/.sso-cli
(更新權杖不會寫入stdout
)。如果您使用 Edge OAuth2 服務取得權杖,必須儲存權杖供日後使用。 - 您使用存取權杖傳送要求至 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"
- Edge API 會執行要求,通常會傳回含有資料的回應。
OAuth2 流程:後續請求
在後續請求中,您不需要交換憑證來取得權杖。而是可以直接包含已經取得的存取權杖,前提是該權杖尚未過期:
如圖 2 所示,如果您已擁有存取權杖:
- 您使用存取權杖傳送要求至 Edge API。
acurl
會自動附加權杖。如果使用其他工具,則需手動新增權杖。 - Edge API 會執行要求,通常會傳回含有資料的回應。
OAuth2 流程:存取權杖到期時
存取權杖過期 (12 小時後) 時,您可以使用更新權杖取得新的存取權杖:
如圖 3 所示,存取權杖已過期:
- 您傳送要求至 Edge API,但存取權杖已過期。
- Edge API 拒絕您的要求為未經授權的要求。
- 您將更新權杖傳送至 Edge OAuth2 服務。如果您使用的是
acurl
,系統會自動為您完成這項操作。 - Edge OAuth2 服務會以新的存取權杖回應。
- 您使用新的存取權杖傳送要求至 Edge API。
- 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
)、瀏覽器式 UI (例如 Postman),或是 acurl
等 Apigee 公用程式。
以下章節會說明使用 acurl
和 curl
存取 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_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 代碼。