启用 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 身份提供方的网址。
    身份提供商实体 ID 此身份提供方的唯一网址。例如：https://idp.example.com/saml

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

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

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

探索 Edge SSO Zone Administration 页面

使用 Edge SSO Zone 管理页面管理 Edge 的身份区域。组织外部会显示边缘 SSO 区域管理页面，您可以通过该页面将多个组织分配给同一身份区域。

如需访问 Edge SSO Zone 管理页面，请按以下步骤操作：

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

系统会显示 Edge SSO Zone 管理页面（在您的组织之外）。

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

添加身份区域

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

  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 元数据文件，然后提取所需信息。例如，实体 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 身份提供方未提供退出网址，请将此字段留空。在这种情况下，该 ID 将设置为与登录网址相同的值。
    身份提供商实体 IDSAML 身份提供方的唯一网址。
    例如：http://www.okta.com/exkhgdyponHIp97po0h7

    注意：此字段的名称可能会因 SAML 身份提供方而异，例如 Entity ID、SP Entity ID、Audience URI 等。

    注意：Apigee SSO 不支持以下两个功能：

    • 使用 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 身份验证注册边缘用户

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

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

启用 SAML 后，系统会为 Edge API 停用基本身份验证。所有依赖于支持基本身份验证的 Edge API 调用的脚本（Maven 脚本、Shell 脚本、apigeetool 等）都将无法再运行。您必须更新使用基本身份验证的 API 调用和脚本，才能在 Bearer 标头中传递 OAuth2 访问令牌。请参阅将 SAML 与 Edge API 搭配使用。

删除身份区域

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

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

退出 Edge SSO Zone 管理页面

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