透過 SAML 存取 Edge API

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

SAML 支援單一登入 (SSO) 環境。在 Edge 中使用 SAML 時，除了您提供的任何其他服務 (也支援 SAML) 之外，您還可以支援 Edge UI 和 API 的單一登入。

必要條件：您必須先為至少一個機構啟用 SAML，才能使用 SAML 存取 Edge API。

SAML 和 OAuth2 的差異

設定 SAML 後，使用方式與使用 OAuth2 存取 Edge API 非常相似。呼叫 Edge API 時，請在要求中加入 OAuth2 存取權杖。

存取 Edge API 時，SAML 和 OAuth2 的主要差異在於取得權杖的方式。使用 SAML 時，您必須在取得權杖對時加入下列項目：

1. 區域：Public Cloud Edge 使用者取得權杖時，必須參照區域名稱。
2. 密碼：要求存取/更新權杖組時，請附上動態密碼。

SAML 在 Edge OAuth2 服務上使用相同的端點，並新增適當的區域名稱。

如要使用 SAML 取得存取權杖，可以採用本節所述的下列其中一種方法：

• get_token公用程式
• Edge OAuth2 服務

此外，您也可以自動產生機器使用者權杖，詳情請參閱「自動產生權杖」。

使用 get_token 取得存取權杖

您可以使用 get_token 公用程式，將憑證換成 OAuth2 存取和更新權杖，以便搭配 SAML 使用。

如要使用 get_token 取得存取權杖：

1. 將 SSO_LOGIN_URL 環境變數設為登入網址。登入網址的格式如下：

   https://zoneName.login.apigee.com

   舉例來說，如果區域名稱為「acme」，請將 SSO_LOGIN_URL 設為「https://acme.login.apigee.com」，如下例所示：

   export SSO_LOGIN_URL=https://acme.login.apigee.com

2. 呼叫 get_token 取得 OAuth2 存取權杖：

   get_token -u me@example.com

   系統會提示您前往顯示的網址，取得動態密碼：

   Get passcode from https://acme.login.apigee.com/passcode
   [Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:

   如果您最近未透過身分識別提供者登入，系統會提示您登入。

   這個網址會傳回動態密碼，在您重新整理該網址以取得新密碼，或使用該密碼搭配 get_token 產生存取權杖前，該密碼都有效。例如：

   

3. 輸入密碼。get_token 公用程式會取得 OAuth2 權杖，將存取權杖列印至 stdout，並將存取和更新權杖寫入 ~/.sso-cli。

4. 呼叫 Edge API，並在 Authorization: Bearer 標頭中傳遞存取權杖，如下列範例所示：

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

   存取權杖的值可從 stdout 複製。

   這個範例會取得指定機構的詳細資料。如需管理 API 端點的完整清單，請參閱「Apigee Edge API 參考資料」。

存取權杖到期時，您可以再次呼叫 get_token，取得新的存取權杖。例如：

get_token -u me@example.com

在更新權杖過期前，系統不會提示您輸入新密碼。

如果更新權杖過期，get_token 會提示您輸入新的密碼。您必須先產生新密碼，才能產生新的 OAuth2 存取權杖。

使用 Edge OAuth2 服務取得存取權杖

您可以使用 Edge OAuth2 服務取得存取權杖，搭配 SAML 使用。如要使用 Edge API 驗證身分，請在初始要求中使用密碼，取得存取/更新權杖組，然後再次使用密碼取得新的權杖組。

如要使用 Edge API 取得權杖組合，請按照下列步驟操作：

1. 在瀏覽器中前往下列網址，取得動態密碼：

   https://zoneName.login.apigee.com/passcode

   舉例來說，如果區域名稱為「acme」，請前往下列網址：

   https://acme.login.apigee.com/passcode

   如果您最近未透過身分識別提供者登入，系統會提示您登入。

   這個網址會傳回動態密碼，做為取得權杖的憑證，且在您重新整理網址以取得新密碼前，或使用密碼搭配 get_token 產生存取權杖前，密碼都有效。例如：

   

2. 如下列範例所示，將要求傳送至 Edge API：

   curl https://zoneName.login.apigee.com/oauth/token \
         -s \
         -H "Accept: application/json" \
         -d 'grant_type=password&response_type=token&passcode=passcode'

   passcode 可做為授權憑證。

   其中：

   • Authorization 標頭為「Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0」(請使用這個確切值)。
   • 要求類型為 POST。
   • 要求主體包含下列項目：
     • grant_type 為「password」。
     • response_type 為「token」。
     • passcode，其中 passcode 是上一步傳回的密碼。

   這個呼叫會在畫面上列印存取和更新權杖。

如何重新整理存取權杖：

向 https://zoneName.login.apigee.com/oauth/token 提交要求，如下列範例所示：

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

其中：

• 要求主體包含下列項目：
  • grant_type 為「refresh_token」。
  • refresh_token 是更新權杖的值。
• Authorization 標頭為「Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0」(請使用這個確切值)。
• 要求類型為 POST。

透過 SAML 存取 Edge API

您可以使用 curl 或 Apigee 便利公用程式 acurl 存取 Edge API。

使用 curl 呼叫 Edge API，並在 Authorization: Bearer 標頭中傳遞存取權杖，如下列範例所示：

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

使用 acurl 時，您不需要指定 Authorization 標頭。例如：

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

這些範例會呼叫 Edge API 端點，取得指定機構的詳細資料。如需 Edge API 端點的完整清單，請參閱「Apigee Edge API 參考資料」。

如要瞭解其他呼叫 API 的方法，包括如何確保權杖保持最新狀態，請參閱「使用 OAuth2 存取 Edge API」。

SAML 區域中的機器使用者

您可以使用 acurl 和 get_token 公用程式，為 SAML 區域中的機器使用者編寫自動存取 Edge API 的指令碼。以下範例說明如何使用 get_token 要求存取權杖，然後將權杖值新增至 curl 呼叫：

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '' --force-basic-auth)
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

在上述範例中，將 -m 的值設為空字串，可避免系統提示電腦使用者輸入 MFA 代碼。使用 --force-basic-auth 旗標會覆寫因 SAML 區域要求而觸發的標準密碼提示。

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

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