啟用 SAML (Beta 版)

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

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

影片:請觀看短片,瞭解在使用 SAML 啟用單一登入 (SSO) 功能前後,如何存取 Apigee Edge API。

關於 zoneadmin 角色

只有 zoneadmin 才能管理 Edge 中的身分可用區。zoneadmin 角色提供完整的 CRUD 程序,僅管理身分區域。

如要將 zone 管理員角色指派給您的 Apigee Edge 帳戶,請與 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 驗證的工作階段持續時間。

探索 Edge SSO 區域管理頁面

使用 Edge SSO 區域管理頁面管理 Edge 的識別區域。「邊緣單一登入 (SSO) 區域管理」頁面位於機構外部,可讓您將多個機構指派給同一個身分識別區域。

如何存取 Edge SSO 區域管理頁面:

  1. 使用具備 zoneadmin 權限Apigee Edge 使用者帳戶,登入 https://apigee.com/edge
  2. 在左側導覽列中,依序選取「管理」>「單一登入 (SSO)」

系統會隨即顯示「Edge SSO Zone Administration」(邊緣單一登入 (SSO) 區域管理) 頁面 (機構外部)。

如圖所示,「Edge SSO Zone Administration」(邊緣單一登入 (SSO) 區域管理) 頁面可讓您進行以下操作:

新增身分識別可用區

如要新增身分識別可用區,請按照下列步驟操作:

  1. 前往 Edge 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. 前往 Edge 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 IDSP Entity IDAudience URI 等等。

    注意:Apigee SSO 不支援下列 2 項功能:

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

  7. 點按「儲存」

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

上傳新憑證

如何上傳新憑證:

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

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

  2. 前往 Edge SSO 區域管理頁面

  3. 按一下您要上傳新憑證的身分可用區列。

  4. 在「Certificate」部分,按一下

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

  6. 按一下「開啟」即可上傳新憑證。
    系統會更新憑證資訊欄位,以反映所選憑證。

  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. 前往 Edge 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 和 OrgC。Acme 可決定將所有機構新增至 SAML 區域,或只加入部分子集。其餘機構會繼續使用從基本驗證憑證產生的基本驗證或 OAuth2 權杖。

您可以定義多個身分可用區。隨後所有區域都可設為使用相同的識別資訊提供者。

舉例來說,Acme 可能需要定義含有 OrgAProd 和 OrgBProd 的正式環境「acme-prod」,以及「acme-test」測試區域,同時包含 OrgATest、OrgBTest、OrgADev 和 OrgBDev。

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

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

使用 SAML 驗證為 Edge 使用者註冊

為機構啟用 SAML 後,您需要註冊尚未向貴機構註冊的 SAML 使用者。詳情請參閱「管理機構使用者」。

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

啟用 SAML 後,Edge API 的基本驗證就會停用。所有仰賴 Edge API 呼叫支援基本驗證的指令碼 (Maven 指令碼、殼層指令碼、apigeetool 等) 都會停止運作。您必須更新使用基本驗證的 API 呼叫和指令碼,透過「不記名」標頭傳遞 OAuth2 存取權杖。請參閱將 SAML 與 Edge API 搭配使用

刪除身分可用區

如要刪除身分可用區:

  1. 前往 Edge SSO 區域管理頁面
  2. 將遊標移到要刪除的身分識別區域相關聯的資料列上,即可顯示動作選單。
  3. 按一下
  4. 按一下「刪除」來確認刪除作業。

登出 Edge SSO 區域管理頁面

由於您負責管理機構外的 Edge 身分識別區域,因此必須登出邊緣單一登入 (SSO) 區域管理頁面,並登入貴機構,才能存取 Apigee Edge 的其他功能。