透過 SAML 存取 Edge API

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

SAML 支援單一登入 (SSO) 環境。將 SAML 與 Edge 搭配使用，除了您提供的任何其他服務以外，您還能透過 Edge 支援 Edge UI 和 API 的單一登入 (SSO) 服務。

事前準備：您必須至少為一個機構啟用 SAML，才能使用 SAML。

SAML 與 OAuth2 的差異

SAML 設定完成後，使用的方式與使用 OAuth2 存取 Edge API 非常類似。呼叫 Edge API 時，您必須在要求中加入 OAuth2 存取權杖。

存取 Edge API 時，SAML 和 OAuth2 之間的主要差異是取得權杖的方式。使用 SAML 時，您必須在取得權杖組合時納入以下內容：

1. 可用區：在取得權杖時，公用雲端的邊緣必須參照自己的可用區名稱。
2. 密碼：要求存取權/重新整理權杖組合時加入一次性密碼。

SAML 會在 Edge OAuth2 服務中使用相同的端點，並加入適當的可用區名稱。

如要透過 SAML 取得存取權杖，可以使用本節說明的下列任一方法：

• get_token 公用程式
• 邊緣 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 是「權杖」。
     • 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 代碼。對於含有 SAML 區域的要求所觸發的密碼，使用 --force-basic-auth 旗標會覆寫標準提示。

您也可以使用 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/...'