启用 SAML（Beta 版）

<ph type="x-smartling-placeholder"></ph> 您正在查看 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 身份提供方时被重定向到的目标网址。
    身份提供商实体 ID 此身份提供方的唯一网址。例如：https://idp.example.com/saml

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

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

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

浏览“Edge SSO Zone 管理”页面

使用 Edge SSO 区域管理页面管理 Edge 的身份区域。“边缘单点登录区域管理”页面位于您的组织之外，可让您将多个组织分配到同一身份区域。

如需访问“Edge SSO Zone 管理”页面，请执行以下操作：

  1. 使用具有 zoneadmin 权限的 Apigee Edge 用户账号登录 https://apigee.com/edge。
  2. 选择管理 >SSO 之间切换。

系统会显示“Edge SSO Zone 管理”页面（贵组织外部）。

如图所示，您可以通过“Edge SSO Zone 管理”页面执行以下操作：

添加身份可用区

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

  1. 访问“Edge SSO Zone 管理”页面。
  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 管理”页面。
  2. 点击您要配置 SAML 身份提供方的身份可用区所在的行。
  3. 在 SAML 设置部分中，点击 。

  4. 点击 SP 元数据网址旁边的复制。

  5. 使用服务提供商 (SP) 元数据文件中的信息配置 SAML 身份提供商。

    对于某些 SAML 身份提供商，系统只会向您提示元数据网址。对于其他，您需要从元数据文件中提取特定信息并将其输入到表单中。

    在后一种情况下，请将网址粘贴到浏览器中以下载 SP 元数据文件，然后提取所需信息。例如，实体 ID 或登录网址可以从 SP 元数据文件的以下元素中提取：

    注意：在 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 管理”页面。

  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 管理”页面。
  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 区域，还是只添加一个 子集。其余组织将继续使用 基本身份验证凭据。

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

例如，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 脚本、Shell 脚本、apigeetool 等） 支持基本身份验证的 API 调用将不再有效。您必须更新 API 调用和 使用基本身份验证在 Bearer 标头中传递 OAuth2 访问令牌的脚本。请参阅将 SAML 与 Edge API 搭配使用。

删除身份区域

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

  1. 访问“Edge SSO Zone 管理”页面。
  2. 将光标置于与要删除的身份区域相关联的行上，以显示操作菜单。
  3. 点击 。
  4. 点击删除以确认删除操作。

退出 Edge SSO Zone 管理页面

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