透過 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 時，您必須在取得權杖組合時納入下列項目：

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

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

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

get_token 公用程式
Edge OAuth2 服務

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

使用 get_token 取得存取權杖

您可以使用 get_token 公用程式來交換憑證，以存取 OAuth2 存取權，並重新整理與 SAML 搭配使用的權杖。

注意事項

本節中的範例使用 curl 發出 API 要求。建議您使用 acurl，這是 Apigee 的實用工具，可做為 curl 周圍的便利包裝函式。 acurl 會傳入存取權杖，並在權杖到期時為您重新整理。

如要取得 get_token 存取權杖：

將 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
```
呼叫 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 的密碼來產生存取權杖。例如：
輸入密碼。get_token 公用程式會取得 OAuth2 權杖，將存取權杖列印至 stdout，然後將存取及重新整理權杖寫入 ~/.sso-cli。
呼叫 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：

在瀏覽器中前往以下網址，即可取得動態密碼：
```
https://zoneName.login.apigee.com/passcode
```
以「acme」區域為例，請前往以下網址：
```
https://acme.login.apigee.com/passcode
```
如果您最近不透過識別資訊提供者登入，系統會提示您登入。

這個網址會傳回一次性密碼，這個憑證將用於取得權杖，而且在您重新整理網址以取得新的密碼之前，密碼會保持有效；或者使用 get_token 的密碼來產生存取權杖。例如：
將要求傳送至 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/...'