使用 CLI 来创建特定于组织的 LDAP 用户注册表

您可以使用 开发者工具箱 CLI 来配置特定于组织的 LDAP 用户注册表，以便为 开发者门户网站提供用户认证。 还可以通过 LDAP 用户注册表来保护 API。

在开始之前

要将 LDAP 用户注册表配置为 API Manager中的资源，必须创建 LDAP 目录并将其用于 API Connect 生态系统。

LDAP 注册表可用于保护 API ，或者用于保护目录以认证 Developer Portal 用户。

重要信息: 如果要使用 LDAP 注册表来保护 API ，那么不支持 STARTTLS 协议 (通过应用 TLS 安全性将不安全协议升级为安全协议)。
注: 如果您正在使用 Active Directory，那么必须使用 LDAP 配置中的属性 "directory_type": "ad" 来指示此情况。

您需要具有以下某个角色才能配置 LDAP 用户注册表：

  • 管理员
  • 所有者
  • 拓扑管理员
  • 定制角色Settings: Manage许可权
重要信息: 要供 IBM® API Connect访问，您使用的任何 LDAP 注册表 必须 在因特网上可见，不能仅从企业内部网中访问。

关于此任务

本主题描述了如何配置特定于组织的 LDAP 用户注册表。 特定于组织的 LDAP 用户注册表可用于在特定提供者组织中启用和认证 Developer Portal 用户。

注：
  • 您还可以使用 API Manager UI 创建特定于组织的 LDAP 用户注册表; 有关更多信息，请参阅 在 API Manager 中创建 LDAP 用户注册表。
  • 此外，您可以使用 API Connect REST API 来创建和管理 LDAP 用户注册表; 请参阅 API Connect REST API 文档。
  • 如果您正在使用 DataPower® API Gateway，那么不支持 LDAP 组认证。
  • 您可以使用 开发者工具箱 CLI 将外部 LDAP 组映射到 API Connect 用户角色以启用对用户授权的更多控制。 以下指示信息说明如何在 LDAP 用户注册表资源上设置 external_group_mapping_enabled 配置。 有关如何在 API Connect 用户角色上设置外部角色映射的信息，请参阅 在 Cloud Manager 用户角色上配置 LDAP 组映射。

通过以下方式创建 LDAP 用户注册表：首先在配置文件中定义注册表详细信息。 然后，使用 developer toolkit CLI 命令来创建注册表，并将配置文件作为参数传递。 要使注册表可供 Developer Portal使用，必须在关联的目录中启用注册表。 要使用 LDAP 注册表保护 API，必须配置安全性定义。 您可以使用以下指示信息来创建可写或只读的 LDAP 用户注册表。

有关使用 LDAP 进行认证的常规信息，请参阅 LDAP 认证。

登录到管理服务器 CLI

必须先从 developer toolkit CLI 作为提供者组织的成员登录到管理服务器，然后才能定义 LDAP 用户注册表配置。 使用以下命令：
apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider
通过输入以下命令查看所有可用身份提供者的列表（无需登录即可使用此命令），可以确定要在 --realm 参数中使用的身份提供者：
apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm
例如
apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
您可通过 title 值确定要使用的身份提供者；然后，可以直接从显示的 realm 值复制对应的 --realm 参数。 对于管理员在安装 API Connect 之后创建的任何身份提供者，将在创建时确定名称。 用于以提供者组织成员身份登录的缺省 API Manager 本地用户注册表为 default-idp-2。

有关登录命令的完整详细信息，请参阅 登录到管理服务器。

有关如何使用 CLI 的更多信息，请参阅 安装工具箱和 命令行工具概述。

定义 LDAP 配置

在 ldap_config_file.yaml 文件中定义 LDAP 用户注册表的配置，如以下示例中所示。 请注意，YAML 文件的实际内容将根据 LDAP 服务器的认证方法而不同，并在下表中进行阐述。
重要信息: 请勿在 API Manager 与 Developer Portal之间或 Developer Portal 站点之间共享用户注册表 (如果启用了自助服务加载或期望在任何站点中删除帐户)。 您应该为它们创建单独的用户注册表，即使单独的注册表指向相同的后端认证提供程序 (例如， LDAP 服务器) 也是如此。 此分离使 开发者门户网站 能够在目录中维护唯一的电子邮件地址，而无需 API Manager 满足相同的需求。 这还可避免用户从 Developer Portal 中删除其帐户时发生问题，从而影响其 API Manager 访问权。
name: registry_name
title: "display_title"
integration_url: LDAP_integration_url
user_managed: true_or_false
user_registry_managed: false
directory_type: ad
external_group_mapping_enabled: true_or_false
case_sensitive: true_or_false
email_required: true_or_false
email_unique_if_exist: true_or_false
identity_providers:
 - name: provider_name
   title: provider_title
endpoint:
  endpoint: "ldap_server_url_and_port"
configuration:
  authentication_method: authentication_method
  authenticated_bind: "true_or_false"
  admin_dn: "admin_dn"
  admin_password: admin_password
  search_dn_base: "search_dn_base"
  search_dn_scope: search_dn_scope  
  search_dn_filter_prefix: prefix
  search_dn_filter_suffix: suffix
  attribute_mapping:
    dn: "distinguished_name"
    cn: "common_name"
    sn: "last_name"
    mail: "email_address"
    userPassword: "password"
下表中描述了对于每种认证方法通用的注册表属性：
属性 描述
name 注册表的名称。 在 CLI 命令中使用此名称。
title 要在图形用户界面中显示的描述性名称。
integration_url LDAP集成 URL 在您的 API Connect 配置中。 您可以使用以下 CLI 命令确定 LDAP 集成 URL：
apic integrations:list --server mgmt_endpoint_url --subcollection user-registry
user_managed 确定用户注册表是否可写。 对于可写 LDAP，必须设置为 true。 如果您不希望注册表可写，那么可以将此设置更改为 false ; 请参阅本主题末尾的 在可写和只读之间切换 LDAP 注册表 部分以获取详细信息。 请注意，可写 LDAP 用户注册表不能用于认证 Cloud Manager 和 API Manager 用户。
user_registry_managed 对于 LDAP，必须设置为 false。 确定 API Connect 是否管理用户注册表。 只有 LUR 注册表由 API Connect管理。
directory 为目录类型指定下列其中一个值:
  • ad -指示 LDAP 是 Microsoft Active Directory
  • standard -(缺省值) 指示任何其他 LDAP
external_group_mapping_enabled 确定用户注册表是否支持 LDAP 组映射。 有效值为：
  • true
  • false
缺省值为 false。
case_sensitive 确定用户注册表是否区分大小写。 有效值为：
  • true
  • false
要确保正确处理用户名大写，必须确保此处的区分大小写设置与后端 LDAP 服务器上的设置匹配：
  • 仅当后端 LDAP 服务器支持区分大小写时，才将 case_sensitive 设置为 true。
  • 如果后端 LDAP 服务器不支持区分大小写，请将 case_sensitive 设置为 false。
注: 在至少有一个用户已加入注册表后，无法更改此设置。
email_required 确定在用户加入过程中是否需要电子邮件地址。 有效值为：
  • true
  • false
如果设置为 true，那么在加载期间，源身份提供者必须在认证过程中提供电子邮件地址。
注: 缺省情况下，加载到 Cloud Manager 或 API Manager时不需要电子邮件地址，但加载到 Developer Portal时需要电子邮件地址。
email_unique_if_exist 确定电子邮件地址在用户注册表中是否必须唯一。 有效值为：
  • true
  • false
注: Developer Portal中的每个帐户 (包括同一站点的不同用户注册表) 都必须具有唯一的电子邮件地址，包括站点管理员帐户。
identity_providers 包含 LDAP 服务器详细信息的数组，其中：
  • name - 是 LDAP 服务器的名称，也是在 CLI 命令中使用的名称
  • title - 是 LDAP 服务器的显示名称
endpoint LDAP 服务器的端点，由 URL 和端口组成，例如：
"ldap://server.com:389"
tls_profile （可选）设置 LDAP 服务器所需的 TLS 客户机概要文件。
protocol_version （可选）设置要使用的 LDAP 协议的版本号。 有效值为：
  • 2
  • 3
如果未显式设置，那么缺省为 3。
配置部分中的属性将根据选中的认证方法而异。 三种认证方法为：
  • compose_dn - 如果可以通过用户名来组成用户 LDAP 专有名称 (DN)，请设置此格式。 例如，uid=<username>,ou=People,dc=company,dc=com 是一种 DN 格式，可以由用户名组成。 如果不确定“组成 (DN)”是否为正确选项，请联系 LDAP 管理员。 如果您是使用 LDAP 注册表来保护 API，那么 DataPower API Gateway 不支持 compose_dn。
  • compose_upn - 如果 LDAP 目录支持与用户主体名称（例如 john@acme.com）进行绑定，请设置此格式。 Microsoft Active Directory 是支持组成 UPN 认证的 LDAP 目录的示例。 如果不确定 LDAP 目录是否支持与 UPN 绑定，请联系 LDAP 管理员。
    注: 管理绑定 DN 和管理绑定密码不与此认证方法配合使用。
  • search_dn - 如果不能通过用户名来组成用户 LDAP 专有名称，请选择此格式；例如，如果用户的基本 DN 不同。 此格式可能需要管理员 DN 和密码才能搜索 LDAP 目录中的用户。 如果 LDAP 目录允许匿名绑定，那么可省略管理员 DN 和密码。 如果不确定 LDAP 目录是否允许匿名绑定，请联系 LDAP 管理员。
对于认证方法 compose_dn，请设置以下配置属性：
属性 描述
authentication_method compose_dn
authenticated_bind 绑定方法。 有效值为：
  • "true" - 认证绑定
  • "false" - 匿名绑定
如果搜索注册表时不需要特定许可权，请选择 "false"。 如果需要特定许可权，请选择 "true"。
admin_dn 如果 authenticated_bind 设置为 "true"，请输入有权在 LDAP 目录中执行搜索的用户的专有名称 (DN)。 例如：
"cn=admin,dc=company,dc=com"
admin_password 如果 authenticated_bind 设置为 "true"，请输入 admin_dn 的用户密码。
search_dn_base （可选）设置基本 DN，例如：
"dc=company,dc=com"
bind_prefix 设置 DN 的前缀，例如：
(uid=
bind_suffix 设置 DN 的后缀，例如：
)
attribute_mapping 如果 user_managed 设置为 true，请提供源 LDAP 属性名称到目标 API Connect 值的映射。 此映射配置为名称/值对，如下指定：
ldap_registry_attribute_name: "apic_ldap_attribute_value"
其中：
  • ldap_registry_attribute_name - 是源 LDAP 属性的名称
  • apic_ldap_attribute_value -这是一个字符串，用于表示 API Connect 将通过将 [ ] 中包含的内容替换为用户在注册时提供的值来填充 LDAP 属性的值。
API Connect 在用户注册期间需要的用户概要文件属性为 username， first_name， last_name， email和 password。
截取的以下代码显示了属性映射的示例：
attribute_mapping:
  dn: "uid=[username],ou=users,dc=company,dc=com"
  cn: "[first_name] [last_name]"
  sn: "[last_name]"
  mail: "[email]"
  userPassword: "[password]"
对于认证方法 compose_upn，请设置以下配置属性：
属性 描述
authentication_method compose_upn
authenticated_bind 绑定方法。 有效值为：
  • "true" - 认证绑定
  • "false" - 匿名绑定
如果搜索注册表时不需要特定许可权，请选择 "false"。 如果需要特定许可权，请选择 "true"。
admin_dn 如果 authenticated_bind 设置为 "true"，请输入有权在 LDAP 目录中执行搜索的用户的专有名称 (DN)。 例如：
"cn=admin,dc=company,dc=com"
admin_password 如果 authenticated_bind 设置为 "true"，请输入 admin_dn 的用户密码。
bind_suffix 输入用户主体名称的域部分。 例如：
@acme.com
attribute_mapping 如果 user_managed 设置为 true，请提供源 LDAP 属性名称到目标 API Connect 值的映射。 此映射配置为名称/值对，如下指定：
ldap_registry_attribute_name: "apic_ldap_attribute_value"
其中：
  • ldap_registry_attribute_name - 是源 LDAP 属性的名称
  • apic_ldap_attribute_value -这是一个字符串，用于表示 API Connect 将通过将 [ ] 中包含的内容替换为用户在注册时提供的值来填充 LDAP 属性的值。
API Connect 在用户注册期间需要的用户概要文件属性为 username， first_name， last_name， email和 password。
截取的以下代码显示了属性映射的示例：
attribute_mapping:
  dn: "uid=[username],ou=users,dc=company,dc=com"
  cn: "[first_name] [last_name]"
  sn: "[last_name]"
  mail: "[email]"
  userPassword: "[password]"
对于认证方法 search_dn，请设置以下配置属性：
属性 描述
authentication_method search_dn
authenticated_bind 绑定方法。 有效值为：
  • "true" - 认证绑定
  • "false" - 匿名绑定
如果搜索注册表时不需要特定许可权，请选择 "false"。 如果需要特定许可权，请选择 "true"。
admin_dn 如果 authenticated_bind 设置为 "true"，请输入有权在 LDAP 目录中执行搜索的用户的专有名称 (DN)。 例如：
"cn=admin,dc=company,dc=com"
admin_password 如果 authenticated_bind 设置为 "true"，请输入 admin_dn 的用户密码。
search_dn_base （可选）设置基本 DN，例如：
"dc=company,dc=com"
search_dn_scope （可选）设置搜索 DN 作用域。 作用域确定检查目录信息树的哪个部分。 可能的值为：
  • base
  • one
  • sub (缺省值)
search_dn_filter_prefix 设置 DN 的前缀，例如：
(uid=
search_dn_filter_suffix 设置 DN 的后缀，例如：
)
attribute_mapping 如果 user_managed 设置为 true，请提供源 LDAP 属性名称到目标 API Connect 值的映射。 此映射配置为名称/值对，如下指定：
ldap_registry_attribute_name: "apic_ldap_attribute_value"
其中：
  • ldap_registry_attribute_name - 是源 LDAP 属性的名称
  • apic_ldap_attribute_value -这是一个字符串，用于表示 API Connect 将通过将 [ ] 中包含的内容替换为用户在注册时提供的值来填充 LDAP 属性的值。
API Connect 在用户注册期间需要的用户概要文件属性为 username， first_name， last_name， email和 password。
截取的以下代码显示了属性映射的示例：
attribute_mapping:
  dn: "uid=[username],ou=users,dc=company,dc=com"
  cn: "[first_name] [last_name]"
  sn: "[last_name]"
  mail: "[email]"
  userPassword: "[password]"

保存 ldap_config_file.yaml，以便可通过以下部分中的 user-registries:create 命令进行访问。 请参阅 示例 部分以获取示例配置文件。

创建 LDAP 用户注册表

要创建特定于组织的 LDAP 用户注册表，请运行以下 CLI 命令：
apic user-registries:create --server mgmt_endpoint_url --org organization_name ldap_config_file.yaml
其中：
  • mgmt_endpoint_url 是平台 API 端点 URL。
  • organization_name 是提供者组织的 name 属性值。
  • ldap_config_file 是用于定义 LDAP 用户注册表配置的 YAML 文件的名称。
完成注册表创建后，此命令会显示以下汇总详细信息：
registry_name registry_url
registry_name 派生自配置 YAML 文件中的 name 属性。 registry_url 是可用于访问注册表资源的 URL。

现在已创建 LDAP 用户注册表; 请参阅以下部分以获取有关如何使注册表在 Developer Portal中可用的指示信息。

在目录中配置 LDAP 注册表

如果要使 LDAP 注册表可用于认证 Developer Portal 用户，那么必须在与该 Developer Portal关联的目录中启用该注册表。 完成以下步骤：
  1. 使用以下命令来确定 LDAP 用户注册表的 URL（或者，可以从注册表创建的摘要复制粘贴）：
    apic user-registries:list --server mgmt_endpoint_url --org organization_name
  2. 以提供者组织的成员身份登录到管理服务器；然后输入以下命令：
    apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider
    通过输入以下命令查看所有可用身份提供者的列表（无需登录即可使用此命令），可以确定要在 --realm 参数中使用的身份提供者：
    apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm
    例如
    apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
    您可通过 title 值确定要使用的身份提供者；然后，可以直接从显示的 realm 值复制对应的 --realm 参数。 对于管理员在安装 API Connect 之后创建的任何身份提供者，将在创建时确定名称。 用于以提供者组织成员身份登录的缺省 API Manager 本地用户注册表为 default-idp-2。

    有关 apic login 命令的完整详细信息，请参阅 登录到管理服务器。

  3. 请输入以下命令（终止连字符表示此命令从命令行接受输入）：
    apic configured-catalog-user-registries:create --server mgmt_endpoint_url --org organization_name --catalog catalog_name -
    其中 catalog_name 是name所需目录的属性。 该命令会返回：
    Reading CONFIGURED_CATALOG_USER_REGISTRY_FILE arg from stdin
  4. 输入以下数据，后接新的一行：
    user_registry_url: ldap_registry_url
    其中， ldap_registry_url 是您LDAP注册表的 URL ，在步骤1 中获取。
  5. 按 CTRL D 以终止输入。

在可写和只读之间切换 LDAP 注册表

创建 LDAP 用户注册表后，可以通过更新注册表配置中的 user_managed 属性在可写和只读之间切换注册表。 请完成下列步骤。
  1. 通过运行以下命令（或者可以使用注册表创建中的摘要），确定要更新的 LDAP 用户注册表的名称或标识：
    apic user-registries:list --server mgmt_endpoint_url --org organization_name
    该命令返回该组织的所有用户注册表的列表，按后跟其注册表 URL 的名称显示。 注册表标识位于 URL 的末尾，例如，https://company.com/api/user-registries/x-x-x-x-x/registry_id。
  2. 请输入以下命令（终止连字符表示此命令从命令行接受输入）：
    apic user-registries:update --server mgmt_endpoint_url --org organization_name registry_name_or_id -
    其中，registry_name_or_id 是想要更新的 LDAP 用户注册表的名称或标识（如先前步骤中所确定）。 该命令返回：
    Reading USER_REGISTRY_FILE arg from stdin
  3. 输入以下数据，后接新的一行：
    user_managed: true_or_false
    其中，true 使注册表变为可写，false 使注册表变为只读。
  4. 按 CTRL D 以终止输入。
请注意，如果要将注册表从只读更改为可写，那么还必须设置 attribute_mapping 配置，如先前注册表属性表中所述。

使用 LDAP 用户注册表来保护 API

如果想要使用 LDAP 用户注册表来保护 API，请参阅以下信息：

有关所有apic user-registries和apic configured-catalog-user-registries命令，请参见工具包 CLI 参考文档。

示例

以下示例显示使用“搜索 DN”认证方法来设置可写 LDAP 的配置文件：
name: sdn-ldap
title: "SDN LDAP User Registry"
integration_url: https://mycompany.com/api/cloud/integrations/user-registry/xxx-xxx-xxx
user_managed: true
user_registry_managed: false
directory_type: standard
case_sensitive: false
identity_providers:
  - name: ldap
    title: "SDN LDAP Identity Provider"
endpoint:
  endpoint: "ldap://mycompany.com:389"
configuration:
  authentication_method: search_dn
  authenticated_bind: "true"
  admin_dn: "cn=admin,dc=company,dc=com"
  admin_password: xxxx
  search_dn_base: "dc=company,dc=com"
  search_dn_scope: sub
  search_dn_filter_prefix: (uid=
  search_dn_filter_suffix: )
  attribute_mapping:
    dn: "uid=[username],ou=users,dc=company,dc=com"
    cn: "[first_name] [last_name]"
    sn: "[last_name]"
    mail: "[email]"
    userPassword: "[password]"