启用 SAML（Beta 版）

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

本部分介绍如何为 Apigee Edge 启用 SAML，以便将组织成员的身份验证委托给您自己的身份服务。如需大致了解 Edge 中的 SAML 和身份区域管理，请参阅 SAML 概览。

视频：观看一段短视频，了解在使用 SAML 启用单点登录 (SSO) 之前和之后如何访问 Apigee Edge API。

zoneadmin 角色简介

您必须是 zoneadmin，才能在 Edge 中管理身份区域。zoneadmin 角色仅提供用于管理身份区域的完整 CRUD 程序。

如需为您的 Apigee Edge 账号分配 zoneadmin 角色，请与 Apigee Edge 支持团队联系。

准备工作

在开始之前，请从第三方 SAML 身份提供方获取以下信息：

  • 用于签名验证的证书（PEM 或 PKCSS 格式）。如有必要，将 x509 证书转换为 PEM 格式

  • 配置信息（如下表中所定义）

    配置 说明
    登录网址 用户重定向到的网址，用于登录 SAML 身份提供方。
    “退出账号”网址 用户退出 SAML 身份提供方时会被重定向到的网址。
    身份提供商实体 ID 相应身份提供方的唯一网址。例如：https://idp.example.com/saml

此外，请使用以下设置配置第三方 SAML 身份提供商：

  • 确保 NameID 属性已映射到用户的电子邮件地址。用户的电子邮件地址是 Edge 开发者账号的唯一标识符。以下示例使用 Okta，其中 Name ID format 字段定义了 NameID 属性。

  • （可选）将经过身份验证的会话时长设置为 15 天，以与 Edge 界面经过身份验证的会话时长保持一致。

探索 Edge SSO 区域管理页面

使用 Edge SSO 区域管理页面管理 Edge 的身份区域。Edge SSO 区域管理页面位于组织外部，可让您将多个组织分配给同一身份区域。

如需访问 Edge SSO 区域管理页面，请执行以下操作：

  1. 使用具有 zoneadmin 权限的 Apigee Edge 用户账号登录 https://apigee.com/edge。
  2. 在左侧导航栏中，依次选择管理 > SSO。

系统会显示 Edge SSO 区域管理页面（在贵组织外部）。

如上图所示，您可以通过 Edge SSO 区域管理页面执行以下操作：

添加身份区域

如需添加身份区域，请执行以下操作：

  1. 访问 Edge SSO Zone Administration 页面。
  2. 在“身份区域”部分中，点击 +。

  3. 输入身份区域的名称和说明。
    可用区名称在所有 Edge 组织中必须是唯一的。

    注意：Apigee 保留移除任何被认为不合理的可用区名称的权利。

  4. 根据需要输入要附加到子网域的字符串。
    例如，如果 acme 是可用区名称，您可能需要定义一个生产可用区 acme-prod 和一个测试可用区 acme-test。
    如需创建生产可用区，请输入 prod 作为子网域后缀。在这种情况下，用于访问 Edge 界面的网址将为 acme-prod.apigee.com，如使用身份区域访问组织中所述。

    注意：附加的子网域后缀在您的所有区域中必须是唯一的。

  5. 点击确定。

  6. 配置 SAML 身份提供商。

配置 SAML 身份提供方

请按照以下步骤配置 SAML 身份提供商：

  1. 配置 SAML 设置。
  2. 上传新证书。
    如有必要，将 x509 证书转换为 PEM 格式。

配置 SAML 设置

要配置 SAML 设置，请执行以下操作：

  1. 访问 Edge SSO Zone Administration 页面。
  2. 点击要为其配置 SAML 身份提供方的身份区域所在的行。
  3. 在 SAML 设置部分中，点击 。

  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 设置部分中，修改从 SAML 身份提供商元数据文件中获取的以下值：

    SAML 设置说明
    登录网址用户重定向到的网址，用于登录 SAML 门户身份提供方。
    例如：https://dev-431871.oktapreview.com/app/googledev431871_devportalsaml_1/exkhgdyponHIp97po0h7/sso/saml
    “退出账号”网址用户退出 SAML 门户身份提供方时会被重定向到的网址。
    注意：如果您的 SAML 身份提供方未提供退出网址，请将此字段留空。在这种情况下，它将设置为与登录网址相同的值。
    身份提供商实体 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. 访问 Edge SSO Zone Administration 页面。

  3. 点击要为其上传新证书的身份区域所在的行。

  4. 在证书部分，点击 。

  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 Zone Administration 页面。
  2. 在组织映射部分中，从身份可用区下拉菜单中选择与要分配给可用区的组织相关联的身份可用区。
    选择无（Apigee 默认）可为组织启用基本身份验证。
  3. 点击确认以确认更改。

使用身份区域访问组织

您用于访问 Edge 界面的网址由身份区域的名称定义：

https://zonename.apigee.com

同样，您用于访问经典版 Edge 界面的网址如下所示：

https://zonename.enterprise.apigee.com

例如，Acme Inc. 想要使用 SAML，并选择“acme”作为其可用区名称。然后，Acme Inc. 客户可以使用以下网址访问 Edge 界面：

https://acme.apigee.com

此区域用于标识支持 SAML 的 Edge 组织。例如，Acme Inc. 有三个组织：OrgA、OrgB 和 OrgC。Acme 可以决定将所有组织添加到 SAML 区域，也可以只添加一部分。其余组织继续使用通过基本身份验证凭据生成的基本身份验证或 OAuth2 令牌。

您可以定义多个身份区域。然后，您可以将所有可用区配置为使用相同的身份提供方。

例如，Acme 可能想要定义一个包含 OrgAProd 和 OrgBProd 的生产区“acme-prod”，以及一个包含 OrgATest、OrgBTest、OrgADev 和 OrgBDev 的测试区“acme-test”。

然后，您可以使用以下网址访问不同的可用区：

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

注册使用 SAML 身份验证的 Edge 用户

为组织启用 SAML 后，您需要注册尚未在组织中注册的 SAML 用户。如需了解详情，请参阅管理组织用户。

更新脚本以传递 OAuth2 访问令牌

启用 SAML 后，Edge API 的基本身份验证会被停用。所有依赖于支持基本身份验证的 Edge API 调用的脚本（Maven 脚本、shell 脚本、apigeetool 等）将不再起作用。您必须更新使用基本身份验证的 API 调用和脚本，以在不记名令牌标头中传递 OAuth2 访问令牌。请参阅将 SAML 与 Edge API 搭配使用。

删除身份区域

如需删除身份区域，请执行以下操作：

  1. 访问 Edge SSO Zone Administration 页面。
  2. 将光标置于要删除的身份区域所对应的行上方，以显示操作菜单。
  3. 点击 。
  4. 点击删除以确认删除操作。

退出 Edge SSO 可用区管理页面

由于您在组织外部管理 Edge 身份区域，因此您需要退出 Edge SSO 区域管理页面，然后登录您的组织，才能访问 Apigee Edge 的其他功能。