LDAP 政策

您正在查看 Apigee Edge 文档。
请查看 Apigee X 文档

是什么

LDAP 政策提供:

  • 身份验证:根据 LDAP 提供商中的凭据验证请求中提供的用户凭据。LDAP 政策为您提供了极大的灵活性,可让您使用身份验证和任何 DN 值(即使该 DN 值不在请求中)。例如,假设您需要使用电子邮件地址 / 密码进行身份验证。您可以使用以下选项:
    • 如果电子邮件在请求中,您可以直接将其与密码搭配使用来进行 LDAP 身份验证。
    • 如果请求中不存在该电子邮件地址,但其他 DN 属性(例如电话号码)可以使用该电话号码从 LDAP 获取对应的电子邮件地址,然后使用电子邮件地址/密码进行身份验证。
  • 可区分名称 (DN) 搜索:除了身份验证外,您还可以使用 LDAP 政策来识别请求中的用户属性(例如电子邮件),并执行查询以从 LDAP 中检索该用户的其他 DN 属性。检索到的 DN 存储在变量中。

如果只有您 LDAP 提供商中的用户(例如管理员用户、组织用户和开发者)才能访问受保护的资源,请使用 LDAP 政策,尤其是在 OAuth 令牌访问权限不必要或过于庞大的情况下。此政策还可用于检索域名元数据,以便在 API 代理流程中使用。

例如,您可以仅在用户成功通过 LDAP 身份验证后执行 API 调用,然后在身份验证成功后选择检索用户的 DN(域名)属性。

如需了解详情,请参阅:

示例

用户名/密码身份验证

<Ldap name="4GLdapPolicy">
   <LdapResource>ldap1</LdapResource>
   <Authentication>
       <UserName ref="request.header.username"/>
       <Password ref="request.header.password"/>
       <Scope>subtree</Scope>
       <BaseDN ref="apigee.baseDN"></BaseDN> <!-- default is dc=apigee,dc=com -->
    </Authentication>
 </Ldap>

此示例针对 LDAP 提供商进行身份验证。该政策将用户名和密码从请求传递到 LDAP 以进行身份验证。

DN 特性身份验证

<Ldap name="LdapPolicy">
   <LdapResource>ldap1</LdapResource>
   <Authentication>
       <Password ref="request.header.password"/>
       <SearchQuery>mail={request.header.mail}</SearchQuery>
       <Scope>subtree</Scope>
       <BaseDN ref="apigee.baseDN"></BaseDN> <!-- default is dc=apigee,dc=com -->
    </Authentication>
 </Ldap>

此政策使用请求标头中的电子邮件地址获取用户的 DN,然后使用请求标头中提供的密码对用户进行 LDAP 身份验证。

搜索 LDAP

<Ldap name="LdapPolicy">
    <!-- using a custom LDAP provider -->
    <LdapConnectorClass>com.custom.ldap.MyProvider</LdapConnectorClass>
    <LdapResource>MyLdap</LdapResource>
    <Search>
        <BaseDN ref="apigee.baseDN"></BaseDN> <!-- default is dc=apigee,dc=com -->
        <SearchQuery>mail={request.header.mail}</SearchQuery>
        <Attributes>
            <Attribute>address</Attribute>
            <Attribute>phone</Attribute>
            <Attribute>title</Attribute>
        </Attributes>
        <Scope></Scope> <!-- default is ‘subtree’ -->
    </Search>
</Ldap>

此政策引用的是自定义 LDAP 提供商。它使用请求标头中的电子邮件地址来识别用户,然后从 LDAP 中检索用户的地址、电话和标题。检索到的 DN 属性存储在变量中。请参阅“政策专用变量”。

如需搜索 LDAP 并检索 DN 属性,请求必须包含管理员凭据。

元素参考

以下是 LDAP 政策元素和属性的说明。

元素

说明

Ldap

具有名称特性的父元素,用于输入政策名称。

LdapConnectorClass

将 LDAP 政策与自定义 LDAP 提供商(而非 Apigee 提供)搭配使用时,请指定完全限定的 LDAP 连接器类。 这是您实现 Apigee ExternalLdapConProvider 接口的类。

LdapResource

输入 LDAP 资源的环境名称。如需了解详情,请参阅创建 LDAP 资源

BaseDN

LDAP 的基础级别,您的所有数据都在该级别下使用。例如,在 Apigee 的 LDAP 提供商中,所有数据都位于 dc=apigee,dc=com 下。

  • ref:用于指定包含 BaseDN 值(如 apigee.baseDN)的流变量。ref 的优先级高于明确的 BaseDN 值。如果您同时指定 ref 和值,则 ref 的优先级更高。如果引用在运行时未解析,则系统会使用值。

Scope

  • object:身份验证或搜索仅在 LDAP 的基本级别进行。
  • 一级:身份验证或搜索会在基本层级下一级进行。
  • subtree(默认):身份验证或搜索在基本级别进行,并以递归方式在基本级别下方进行。

身份验证

Authentication

您实现的身份验证行为的父元素。

UserName

接受下列属性的空元素:

  • ref:对请求中的用户名的引用,例如 request.header.username
  • value:用户名本身

如果您未使用用户名进行身份验证,或者请求中未包含用户名,则无需添加此元素。

如果请求中包括用户名,但您希望使用 DN 属性(例如用户名)验证用户身份,请添加 SearchQuery 以获取与密码关联的用户电子邮件地址。LDAP 政策使用用户名来查询 LDAP 提供商的相应电子邮件地址,该地址随后会用于身份验证。

Password

接受下列属性的空元素:

  • ref:对请求中的密码的引用,例如 request.header.password
  • value:加密密码本身

SearchQuery

如果您希望使用除用户名以外的 DN 属性(例如电子邮件地址)进行身份验证,请配置 LDAP 政策以从请求中获取 DN 属性(例如用户名),以用于在 LDAP 中识别用户、检索电子邮件以及对用户进行身份验证。

例如,假设 LDAP 定义了“mail”属性,用于存储电子邮件地址:

<SearchQuery>mail={request.header.mail}</SearchQuery>

搜索广告系列

Search

您实现的搜索行为的父元素。

SearchQuery

通过在请求或响应中使用元数据来识别用户,您可以使用此元素从 LDAP 检索用户的其他 DN 属性。例如,如果请求中包含用户电子邮件地址,并且您的 LDAP 定义了用于存储用户电子邮件地址的 mail 属性,您可以使用以下设置:

<SearchQuery>mail={request.header.mail}</SearchQuery>

此查询在 LDAP 中搜索与请求中的电子邮件地址匹配的电子邮件,现在政策可以使用 Attributes 元素检索该用户的其他 DN 属性。

Attributes

使用一个或多个 <Attribute> 元素来标识您要为用户检索的 DN 元数据。至少需要一个特性。

例如,在 SearchQuery 识别用户后,此政策现在可以检索用户的 DN 属性(例如地址、电话号码和用户的标题),如以下示例所示。

属性值是 LDAP 中定义的 DN 属性名称。

<Attributes>
  <Attribute>address</Attribute>
  <Attribute>phone</Attribute>
  <Attribute>title</Attribute>
</Attributes>

使用说明

借助 Apigee Edge for Private Cloud,您可以在 API 调用中利用 LDAP 提供商。利用 LDAP 政策,应用可以针对存储在 LDAP 中的用户进行身份验证凭据,并且您可以从 LDAP 中检索不同的名称 (DN),也就是与每个用户关联的元数据或特性(例如电子邮件地址、地址和电话号码)。返回的 DN 存储在变量中,供 API 代理进一步使用。

创建 LDAP 资源

LDAP 政策利用您在 Apigee Edge 中创建的 LDAP 资源。LDAP 资源提供到 LDAP 代码库的连接信息。

如需创建和管理 LDAP 资源,请使用以下 API 和载荷:

API

创建 (POST) LDAP 资源或列表 (GET) 所有 LDAP 资源:

/v1/organizations/org_name/environments/environment/ldapresources

获取 (GET)、更新 (POST) 和删除 (DELETE) LDAP 资源的详细信息:

/v1/organizations/org_name/environments/environment/ldapresources/ldap_resource_name

载荷

以下是带有用法注释的 XML 载荷示例。

<LdapResource name="ldap1">
  <Connection>
    <Hosts>
      <!-- port is optional: defaults to 389 for ldap:// and 636 for ldaps:// -->
      <Host port="636">foo.com</Host>
    </Hosts>
    <SSLEnabled>false</SSLEnabled> <!-- optional, defaults to false -->
    <Version>3</Version> <!-- optional, defaults to 3-->
    <Authentication>simple</Authentication> <!-- optional, only simple supported -->
    <ConnectionProvider>jndi|unboundid</ConnectionProvider> <!-- required -->
    <ServerSetType>single|round robin|failover</ServerSetType> <!-- not applicable for jndi -->
    <!-- If using a custom LDAP provider, the fully qualified class: -->
    <LdapConnectorClass>com.custom.ldap.MyProvider</LdapConnectorClass>
  </Connection>
  <ConnectPool enabled="true"> <!-- enabled is optional, defaults to true -->
    <Timeout>30000</Timeout> <!-- optional, in milliseconds; if not set, no timeout -->
    <Maxsize>50</Maxsize> <!-- optional; if not set, no max connections -->
    <Prefsize>30</Prefsize> <!-- optional; if not set, no pref size -->
    <Initsize></Initsize> <!-- optional; if not set, defaults to 1 -->
    <Protocol></Protocol> <!-- optional; if not set, defaults to 'ssl plain' -->
  </ConnectPool>
  <Admin>
    <DN>cn=manager,dc=apigee,dc=com</DN>
    <Password>secret</Password>
  </Admin>
</LdapResource>

curl 示例:创建 LDAP 资源

以下示例创建了一个名为 ldap1 的 LDAP 资源。

curl -X POST -H "Content-Type: application/xml" \
  https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/ldapresources \
  -u apigee_email:password -d \
  '<LdapResource name="ldap1">
    <Connection>
      <Hosts>
      <Host>foo.com</Host>
      </Hosts>
      <SSLEnabled>false</SSLEnabled>
      <Version>3</Version>
      <Authentication>simple</Authentication>
      <ConnectionProvider>unboundid</ConnectionProvider>
      <ServerSetType>round robin</ServerSetType>
    </Connection>
    <ConnectPool enabled="true">
      <Timeout>30000</Timeout>
      <Maxsize>50</Maxsize>
      <Prefsize>30</Prefsize>
      <Initsize></Initsize>
      <Protocol></Protocol>
    </ConnectPool>
    <Admin>
      <DN>cn=manager,dc=apigee,dc=com</DN>
      <Password>secret</Password>
    </Admin>
  </LdapResource>'

响应代码

以下是政策成功或失败后返回的 HTML 响应代码:

  • 成功:200
  • 失败:401

在 Edge 中针对私有云使用自定义 LDAP 提供商

使用自定义 LDAP 提供商

适用于私有云的 Apigee Edge 附带一个已经配置为与 LDAP 政策交互的 LDAP 提供商。但是,如果您使用的是自定义 LDAP 提供商,则必须允许该提供商支持 LDAP 政策。操作方法如下:

  1. 在 LDAP 提供商类中,实现 ExternalLdapConProvider 接口。
    public interface ExternalLdapConProvider {
      void doAuthentication(LdapBean LlapBean, String userDN, String password, String baseDN);
    
      void doSearchAndAuthentication(LdapBean LlapBean, String password, String baseDN, String query, int scope);
    
      Collection<Map<String, String[]>> doSearch(LdapBean LlapBean, String query,
        String baseDN, Collection<String> requiredAttributes, int scope);
    
      void closeConnections();
    }
  2. 在政策配置的 <LdapConnectorClass> 中(下一部分),添加自定义 LDAP 提供商的完全限定类名。
  3. 下载以下文件:custom-ldap.jar_.zip。 (您可能需要右键点击并选择另存为)。
  4. 解压缩。
  5. 将 custom-ldap.jar 文件添加到您的环境中,并确保该文件位于您的类路径中。
  6. 为您的 LDAP 提供商创建环境资源。您将在 LDAP 政策的 <LdapResource> 元素中使用环境资源名称。

使用适用于 Java 的 UnboundID LDAP SDK

您可以将 UnboundID LDAP SDK 与 LDAP 政策搭配使用,但必须先下载 2.3.1 版,并将其添加到每个消息处理器的类路径中。

要将 UnboundID LDAP SDK 与 LDAP 政策搭配使用,请按以下步骤操作:

  1. 打开浏览器,然后转到 UnboundID LDAP SDK 的 Sourceforge 文件代码库:
    https://sourceforge.net/projects/ldap-sdk/files/
  2. 找到该 SDK 的 2.3.1 版(SE 或标准版)并下载该版本的 ZIP 文件。例如,下载“unboundid-ldapsdk-2.3.1-se.zip”。
  3. 从 SDK ZIP 文件中提取 JAR 文件,如以下示例所示:
    unzip -j -d ~/tmp ~/Downloads/unboundid-ldapsdk-2.3.1-se.zip unboundid-ldapsdk-2.3.1-se/unboundid-ldapsdk-se.jar

    此命令仅将 JAR 文件提取到 ~/tmp 目录。它将使用 -j 丢弃目录结构(尽管这是可选的)。

  4. 在每个消息处理器节点上
    1. 将 JAR 文件复制到消息处理器的 /opt/apigee/edge-gateway/lib/thirdparty 目录。
    2. 如有必要,请为 Apigee 用户授予 JAR 文件的权限,以便消息处理器可以访问该文件。
    3. Edge 会将 /opt/apigee/edge-gateway/lib/thirdparty 目录中的所有第三方库添加到类路径中。

    4. 重启消息处理器:
      /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

流变量

以下是由 SearchQuery 填充的 LDAP 政策变量。

变量

说明

ldap.policyName.execution.success

执行政策后,根据结果,此流变量会包含“true”或“false”值。

ldap.policyName.search.result[index].
  attribute.attrName[index]=value

此变量的灵活格式,特别是索引:会考虑多个属性,以及具有多个值的属性。索引是一个从 1 开始的数字。如果未提供索引编号,则默认索引编号为 1。

如果此政策返回地址、电话和电子邮件地址,您可以使用以下变量检索第一个属性和值:

ldap.policyName.search.result.attribute.address
ldap.policyName.search.result.attribute.phone
ldap.policyName.search.result.attribute.email

如果要检索搜索结果中的第三个地址属性,请使用:

ldap.policyName.search.result[3].attribute.address

如果某个特性有多个值(例如,如果用户有多个电子邮件地址),您可以从结果中检索第二个电子邮件地址,如下所示:

ldap.policyName.search.result.attribute.mail[2]

错误代码

从 Edge 政策返回的错误遵循错误代码参考文档中所述的格式。

此政策使用以下错误代码:

错误代码 讯息
InvalidAttributeName Invalid attribute name {0}.
InvalidSearchBase Search base can not be empty.
InvalidValueForPassword Invalid value for password field. It can not be empty.
InvalidSearchScope Invalid scope {0}. Allowed scopes are {1}.
InvalidUserCredentials Invalid user credentials.
InvalidExternalLdapReference Invalid external ldap reference {0}.
LdapResourceNotFound Ldap resource {0} not found.
BaseDNRequired Base DN required.
OnlyReferenceOrValueIsAllowed Only value or reference is allowed for {0}.
AttributesRequired At least one attribute required for search action.
UserNameIsNull User name is null.
SearchQueryAndUserNameCannotBePresent Both search query and username can not be present in the authentication action. Please specify either one of them.