透過 SAML 存取 Edge API

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

SAML 支援單一登入 (SSO) 環境。您可以搭配 SAML 使用 Edge 來支援 Edge UI 和 API,搭配您提供的任何其他服務及支援 SAML。

必備條件:您必須為至少一個機構啟用 SAML,才能使用 SAML 存取 Edge API。

SAML 與 OAuth2 的差異

SAML 設定完成後,使用類似 OAuth2 存取 Edge API 的程序非常類似。呼叫 Edge API 時,您可以在要求中加入 OAuth2 存取權杖。

存取 Edge API 時,SAML 與 OAuth2 之間的主要差異在於取得權杖的方式。使用 SAML 時,您必須在取得權杖組合時納入下列項目:

  1. 可用區:公用雲端使用者的 Edge 必須在取得權杖時參照自己的可用區名稱。
  2. 密碼:要求存取/重新整理權杖組合時,請提供一次性密碼。

加上適當的可用區名稱,SAML 會使用 Edge OAuth2 服務中的相同端點。

如要透過 SAML 存取權杖,您可以使用下列其中一種方法:

此外,您可以按照「自動化權杖產生程序」一節的說明,讓系統自動為機器使用者產生權杖產生程序。

使用 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 可用區中的電腦使用者

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