啟用 SAML (Beta 版)

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

本節說明如何為 Apigee Edge 啟用 SAML，以便將貴機構的成員驗證委派給您自己的身分識別服務。如需在 Edge 中管理 SAML 和身分可用區的總覽，請參閱 SAML 總覽。

影片：觀看這部短片，瞭解如何在使用 SAML 單一登入 (SSO) 之前和之後存取 Apigee Edge API。

關於 zoneadmin 角色

您必須是 zoneadmin，才能管理 Edge 中的身分識別可用區。區域管理員角色提供完整的 CRUD 程序，只能管理身分區域。

如要為您的 Apigee Edge 帳戶指派 zoneadmin 角色，請與 Apigee Edge 支援團隊聯絡。

事前準備

在開始之前，請先向第三方 SAML 識別資訊提供者取得以下資訊：

  • 簽章驗證憑證 (PEM 或 PKCSS 格式)。如有需要，請將 x509 憑證轉換為 PEM 格式。

  • 設定資訊 (如下表定義)

    設定 說明
    登入網址 將使用者重新導向至 SAML 識別資訊提供者的網址。
    登出網址 將使用者重新導向至 SAML 識別資訊提供者的網址。
    IdP 實體 ID 這個識別資訊提供者的專屬網址。例如：https://idp.example.com/saml

此外，請按照下列設定設定第三方 SAML 識別資訊提供者：

  • 確認 NameID 屬性已對應至使用者的電子郵件地址。使用者的電子郵件地址會做為 Edge 開發人員帳戶的專屬 ID。以下範例是使用 Okta 的範例，其中「名稱 ID 格式」欄位定義了 NameID 屬性。

  • (選用) 將驗證的工作階段持續時間設為 15 天，以符合 Edge UI 驗證工作階段的時間長度。

探索邊緣單一登入 (SSO) 區域管理頁面

在「Edge SSO Zone 管理」頁面管理 Edge 的識別區域。貴機構外會提供 Edge SSO 可用區管理頁面，方便您將多個機構指派給同一個識別可用區。

如何存取「Edge SSO Zone 管理」頁面：

  1. 使用具備 zoneadmin 權限的 Apigee Edge 使用者帳戶登入 https://apigee.com/edge。
  2. 依序選取「管理員」>單一登入 (SSO)。

「Edge SSO Zone 管理」頁面隨即顯示 (不屬於貴機構)。

如圖中所示，「Edge SSO Zone 管理」頁面可讓您執行下列操作：

新增身分識別區域

如何新增身分區域：

  1. 存取邊緣單一登入 (SSO) 區域管理頁面。
  2. 在「身分區域」部分中，按一下「+」。

  3. 輸入身分區域的名稱和說明。
    所有 Edge 機構中的區域名稱均不得重複。

    注意：Apigee 有權移除任何認為不合理的可用區名稱。

  4. 視需要輸入要附加到子網域的字串。
    舉例來說，如果 acme 是可用區名稱，就可以定義正式環境可用區 acme-prod 和測試可用區 acme-test。
    如要建立實際工作環境可用區，請輸入 prod 做為子網域尾碼。在此情況下，請按照「使用識別資訊區域存取貴機構」一文的說明，存取 Edge UI 所在的網址：acme-prod.apigee.com。

    注意：您所有區域的附加子網域後置字串都不得重複。

  5. 按一下「OK」。

  6. 設定 SAML 識別資訊提供者。

設定 SAML 識別資訊提供者

如要設定 SAML 識別資訊提供者，請按照下列步驟操作：

  1. 調整 SAML 設定。
  2. 上傳新憑證。
    如有需要，請將 x509 憑證轉換為 PEM 格式。

進行 SAML 設定

如何進行 SAML 設定：

  1. 存取邊緣單一登入 (SSO) 區域管理頁面。
  2. 找到您要設定 SAML 識別資訊提供者的識別資訊可用區，並按一下對應的資料列。
  3. 在「SAML Settings」部分，按一下 。

  4. 按一下 SP 中繼資料網址旁的「複製」。

  5. 使用服務供應商 (SP) 中繼資料檔案中的資訊設定 SAML 識別資訊提供者。

    部分 SAML 識別資訊提供者只會提示您輸入中繼資料網址。若是其他商家，則需要從中繼資料檔案中擷取特定資訊，然後以表單形式輸入。

    如果是後者，請將網址貼到瀏覽器，以下載服務供應商 (SP) 中繼資料檔案並擷取必要資訊。舉例來說，您可以透過 SP 中繼資料檔案中的下列元素，擷取實體 ID 或登入網址：

    注意：SP 中繼資料檔案中的登入網址稱為 AssertionConsumerService (ACS) 網址。

    • <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login" entityID="diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login">
    • <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://diyyaumzqchrbui-a5vnmu1sp8qzekbd.portal-login.apigee.com/saml/SSO/alias/diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login" index="0" isDefault="true"/>

    注意：如果 SAML 識別資訊提供者要求，請將目標對象限制設為 zoneID.apigee-saml-login，您可以從 SP 中繼資料檔案中的 entityID 元素複製 (如上圖所示)。

  6. 調整 SAML 識別資訊提供者的 SAML 設定。

    在「SAML Settings」部分，編輯下列從 SAML 識別資訊提供者中繼資料檔案取得的值：

    SAML 設定說明
    登入網址將使用者重新導向至 SAML 入口網站識別資訊提供者的網址。
    例如：https://dev-431871.oktapreview.com/app/googledev431871_devportalsaml_1/exkhgdyponHIp97po0h7/sso/saml
    登出網址系統會將使用者重新導向到這個網址，以便登出 SAML 入口網站識別資訊提供者。
    注意：如果您的 SAML 識別資訊提供者未提供登出網址，請將這個欄位留空。在這個範例中，系統會將該值設為登入網址所使用的值。
    IdP 實體 IDSAML 識別資訊提供者的專屬網址。
    例如：http://www.okta.com/exkhgdyponHIp97po0h7

    注意：這個欄位的名稱可能會因 SAML 識別資訊提供者而不同，例如 Entity ID、SP Entity ID、Audience URI 等。

    注意：Apigee 單一登入 (SSO) 不支援下列 2 項功能：

    • 使用 IDP 中繼資料網址自動重新整理 IdP 憑證，並定期下載中繼資料，以更新 Apigee 單一登入 (SSO) 服務供應商端的變更。
    • 上傳整個 IDP 中繼資料 XML 檔案，或針對自動 IdP 設定使用 IdP 中繼資料網址。

  7. 按一下 [儲存]。

接下來，請按照下一節的說明，以 PEM 或 PKCSS 格式上傳憑證。

上傳新憑證

如何上傳新憑證：

  1. 下載憑證，以便透過 SAML 識別資訊提供者進行簽名驗證。

    注意：憑證必須採用 PEM 或 PKCSS 格式。如有需要，請將 x509 憑證轉換為 PEM 格式。

  2. 存取邊緣單一登入 (SSO) 區域管理頁面。

  3. 針對您要上傳新憑證的識別區域，按一下對應的資料列。

  4. 在「Certificate」(憑證) 部分中，按一下 。

  5. 按一下「Browse」，然後前往本機目錄中的憑證。

  6. 按一下「Open」上傳新憑證。
    系統會更新憑證資訊欄位，以反映所選憑證。

  7. 驗證憑證是否有效且尚未過期。

  8. 按一下「儲存」。

將 x509 憑證轉換為 PEM 格式

如果您下載的是 x509 憑證，則必須轉換為 PEM 格式。

如何將 x509 憑證轉換為 PEM 格式：

  1. 從 SAML 識別資訊提供者中繼資料檔案複製 ds:X509Certificate element 的內容，然後貼到您慣用的文字編輯器中。
  2. 在檔案頂端加入下列程式碼：
    -----BEGIN CERTIFICATE-----
  3. 在檔案底部新增下列程式碼：
    -----END CERTIFICATE-----
  4. 請使用 .pem 副檔名儲存檔案。

以下提供 PEM 檔案內容範例：

-----BEGIN CERTIFICATE-----
MIICMzCCAZygAwIBAgIJALiPnVsvq8dsMA0GCSqGSIb3DQEBBQUAMFMxCzAJBgNV
BAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNVBAcTA2ZvbzEMMAoGA1UEChMDZm9v
MQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2ZvbzAeFw0xMzAzMTkxNTQwMTlaFw0x
ODAzMTgxNTQwMTlaMFMxCzAJBgNVBAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNV
BAcTA2ZvbzEMMAoGA1UEChMDZm9vMQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2Zv
bzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAzdGfxi9CNbMf1UUcvDQh7MYB
OveIHyc0E0KIbhjK5FkCBU4CiZrbfHagaW7ZEcN0tt3EvpbOMxxc/ZQU2WN/s/wP
xph0pSfsfFsTKM4RhTWD2v4fgk+xZiKd1p0+L4hTtpwnEw0uXRVd0ki6muwV5y/P
+5FHUeldq+pgTcgzuK8CAwEAAaMPMA0wCwYDVR0PBAQDAgLkMA0GCSqGSIb3DQEB
BQUAA4GBAJiDAAtY0mQQeuxWdzLRzXmjvdSuL9GoyT3BF/jSnpxz5/58dba8pWen
v3pj4P3w5DoOso0rzkZy2jEsEitlVM2mLSbQpMM+MUVQCQoiG6W9xuCFuxSrwPIS
pAqEAuV4DNoxQKKWmhVv+J0ptMWD25Pnpxeq5sXzghfJnslJlQND
-----END CERTIFICATE-----

將 Edge 機構連結至身分識別可用區

如要將 Edge 機構連線至身分可用區，請按照下列步驟操作：

  1. 存取邊緣單一登入 (SSO) 區域管理頁面。
  2. 在「機構對應」部分中，找到與要指派可用區的機構相關聯，然後在「識別資訊可用區」下拉式選單中選取身分識別可用區。
    選取「無 (Apigee 預設值)」即可為機構啟用基本驗證功能。
  3. 按一下「確認」確認變更。

使用身分可用區存取貴機構

您用來存取 Edge UI 的網址，是由您的身分可用區名稱定義：

https://zonename.apigee.com

同樣地，用於存取傳統版 Edge UI 的網址如下：

https://zonename.enterprise.apigee.com

舉例來說，Acme Inc. 想要使用 SAML 並選擇「acme」做為可用區名稱Acme Inc. 的客戶可透過以下網址存取 Edge UI：

https://acme.apigee.com

這個可用區可用來識別支援 SAML 的 Edge 機構。舉例來說，Acme Inc. 有三個 OrgA、OrgB 和 OrgCAcme 可選擇將所有機構新增至 SAML 區域，也可以只新增 子集。其餘機構繼續使用從以下來源產生的基本驗證或 OAuth2 權杖： 基本驗證憑證。

您可以定義多個身分可用區。這樣所有可用區都能設為 識別資訊提供者

舉例來說，Acme 可以定義正式環境可用區「acme-prod」，其中包含 OrgAProd，以及 OrgBProd 和測試區域「acme-test」，其中包含 OrgATest、OrgBTest、OrgADev 和 OrgBDev。

然後使用下列網址存取不同可用區：

https://acme-prod.apigee.com
https://acme-test.apigee.com

使用 SAML 驗證註冊 Edge 使用者

為機構啟用 SAML 後，您必須註冊 尚未在貴機構註冊。詳情請參閱「管理機構使用者」。

更新指令碼以傳遞 OAuth2 存取權杖

啟用 SAML 後，Edge API 就會停用基本驗證。所有語言 仰賴 Edge 的指令碼 (Maven 指令碼、殼層指令碼、apigeetool 等) 支援基本驗證的 API 呼叫將停止運作。您必須更新 API 呼叫和 使用基本驗證在 Bearer 標頭中傳遞 OAuth2 存取權杖的指令碼。請參閱透過 Edge API 使用 SAML。

刪除識別資訊可用區

如何刪除身分可用區：

  1. 存取邊緣單一登入 (SSO) 區域管理頁面。
  2. 將遊標移到要刪除的識別資訊可用區所在的資料列上，即可顯示動作選單。
  3. 按一下 。
  4. 按一下「刪除」即可確認刪除作業。

登出 Edge SSO Zone 管理頁面

由於您是管理機構外部的 Edge 身分識別區域，因此您必須登出 Edge SSO Zone 管理頁面，並登入貴機構，才能使用 Apigee Edge 的其他功能。