Liberty 中配置 LDAP 用户注册表

可在 Liberty 中配置一个或多个轻量级目录访问协议 (LDAP) 服务器以进行认证。

开始之前

确保 LDAP 服务器已启动且运行,而且 LDAP 服务器的主机名和端口号已经在已知列表中。

关于此任务

可在 Liberty 上使用现有 LDAP 服务器进行应用程序认证。需要将 appSecurity-2.0 功能部件添加至 server.xml 文件,并在 server.xml 文件中指定 ldapRegistry-3.0 功能部件以及用于连接至 LDAP 服务器的配置信息。

避免故障: 在 Liberty 上配置应用程序的安全性时,可以参考 WASdev.net Web 站点上的若干个安全性配置示例。有关更多信息,请参阅相关参考中配置片段的链接。

过程

  1. appSecurity-2.0ldapRegistry-3.0 Liberty 功能部件添加至 server.xml 文件。
  2. 可选: 要与启用了 SSL 的 LDAP 服务器进行通信,请将 ssl-1.0 Liberty 功能部件添加到 server.xml 文件。
  3. 可选: 将信任库复制到服务器配置目录。例如,可以使用 ${server.config.dir} 变量。

    要成功地与 LDAP 服务器进行 SSL 通信,必须将 LDAP 服务器的签署者证书添加到 <ldapRegistry> 元素的 sslAlias 属性所引用的信任库。在以下示例中,必须将签署者证书添加到 LdapSSLTrustStore.jks

  4. 配置服务器的 LDAP 条目。

    如果不想对 LDAP 服务器使用 SSL,请从以下示例中移除所有基于 SSL 和密钥库的行。

    可以在 server.xml 文件中或者使用 WebSphere® Application Server Developer Tools for Eclipse 来配置 LDAP 服务器。在 Liberty 上配置应用程序的安全性时,可以参考 WASdev.net Web 站点上的若干个安全性配置示例。
    • 对于 IBM® Directory Server:
      <ldapRegistry id="ldap" realm="SampleLdapIDSRealm"
          host="ldapserver.mycity.mycompany.com" port="389" ignoreCase="true"
          baseDN="o=mycompany,c=us" 
          ldapType="IBM Tivoli Directory Server"
          sslEnabled="true" 
          sslRef="LDAPSSLSettings">
          <idsFilters
          		    userFilter="(&amp;(uid=%v)(objectclass=ePerson))"
          		    groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
                           (objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"
          	userIdMap="*:uid"
          	groupIdMap="*:cn"
          	groupMemberIdMap="mycompany-allGroups:member;mycompany-allGroups:uniqueMember;
      			  groupOfNames:member;groupOfUniqueNames:uniqueMember">
          </idsFilters>    
      </ldapRegistry>
      <ssl id="LDAPSSLSettings" keyStoreRef="LDAPKeyStore" trustStoreRef="LDAPTrustStore" />
      
      <keyStore id="LDAPKeyStore" location="${server.config.dir}/LdapSSLKeyStore.jks"
           type="JKS" password="{xor}CDo9Hgw=" />   <keyStore id="LDAPTrustStore" location="${server.config.dir}/LdapSSLTrustStore.jks"
          type="JKS" password="{xor}CDo9Hgw=" />   
    • 对于 Microsoft Active Directory Server:
      <ldapRegistry id="ldap" realm="SampleLdapADRealm"
          host="ldapserver.mycity.mycompany.com" port="389" ignoreCase="true"
          baseDN="cn=users,dc=adtest,dc=mycity,dc=mycompany,dc=com" 
          bindDN="cn=testuser,cn=users,dc=adtest,dc=mycity,dc=mycompany,dc=com" 
          bindPassword="testuserpwd" 
          ldapType="Microsoft Active Directory" 
          sslEnabled="true" 
          sslRef="LDAPSSLSettings">
          <activedFilters
          userFilter="(&amp;(sAMAccountName=%v)(objectcategory=user))"
      groupFilter="(&amp;(cn=%v)(objectcategory=group))"
         userIdMap="user:sAMAccountName" 
          groupIdMap="*:cn"
          groupMemberIdMap="memberOf:member" >
      </activedFilters>
          </ldapRegistry>
      
      <ssl id="LDAPSSLSettings" keyStoreRef="LDAPKeyStore" trustStoreRef="LDAPTrustStore" />
      
      <keyStore id="LDAPKeyStore" location="${server.config.dir}/LdapSSLKeyStore.jks"
                type="JKS" password="{xor}CDo9Hgw=" />   <keyStore id="LDAPTrustStore" location="${server.config.dir}/LdapSSLTrustStore.jks"
                type="JKS" password="{xor}CDo9Hgw=" />   

    如果使用 WebSphere Application Server Developer Tools for Eclipse,那么系统自动对 bindPassword 密码进行编码。如果直接编辑 server.xml 文件,那么您可使用 securityUtility encode 命令对 bindPassword 密码进行编码。securityUtility 命令行工具位于 $INSTALL_ROOT/bin 目录中。运行 securityUtility encode 命令时,将要编码的密码作为命令行输入来提供,或者如果未指定任何参数,那么工具会提示您输入密码。工具随后会输出已编码的值。复制工具输出的值,然后将该值用作 bindPassword 密码。

  5. 可选: 为 LDAP 服务器配置证书过滤方式。
    <ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"
          host="myldap.ibm.com" port="389" ignoreCase="true"
          baseDN="o=ibm,c=us"
          ldapType="IBM Tivoli Directory Server" searchTimeout="8m"
          certificateMapMode="CERTIFICATE_FILTER" 
          certificateFilter="uid=${SubjectCN}"> 
          <idsFilters
          	    userFilter="(&amp;(uid=%v)(objectclass=ePerson))"
          	    groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
              (objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"
          userIdMap="*:uid"
          groupIdMap="*:cn"
          groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;
              groupOfNames:member;groupOfUniqueNames:uniqueMember">
    </idsFilters>    
          </ldapRegistry>
    有关 Liberty 中证书映射方式的更多信息,请参阅LDAP 证书映射方式
  6. 可选: 您可以定义 LDAP 属性与用户注册表模式属性之间的映射。

    配置该映射后,将用户注册表属性用于任何对其定义了该映射的操作时,用户注册表属性值将是 LDAP 属性的值。在以下示例中,您可以看到 server.xml 文件中针对 LDAP 属性 <userPassword> 与用户注册表属性 <password> 定义了映射。 <defaultValue> 属性是可选的。

    <ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"
          host="myldap.ibm.com" port="389" ignoreCase="true"
          baseDN="o=ibm,c=us"
          ldapType="IBM Tivoli Directory Server" searchTimeout="8m">
          <attributeConfiguration>
                 <attribute name="userPassword" propertyName="password" entityType="PersonAccount" defaultValue="xyz123"/>
          </attributeConfiguration>
    </ldapRegistry>
  7. 可选: 您可定义 LDAP 属性以及用户注册表 <externalId> 属性之间的映射。

    您可定义 LDAP 属性以及用户注册表 <externalId> 属性之间的映射。配置映射后,将用户注册表 <externalId> 属性用于任何操作时,值将等于映射的 LDAP 属性的值。以下示例代码显示针对实体类型 <PersonAccount> 为用户注册表 <externalId> 属性以及 LDAP <distinguishedName> 属性定义的映射。 <autoGenerate> 属性是可选的,缺省情况下,值为 false

    <ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"
          host="myldap.ibm.com" port="389" ignoreCase="true"
          baseDN="o=ibm,c=us"
          ldapType="IBM Tivoli Directory Server" searchTimeout="8m">
          <attributeConfiguration>
                 <externalIdAttribute name="distinguishedName" entityType="PersonAccount" autoGenerate="false"></externalIdAttribute>
          </attributeConfiguration>
    </ldapRegistry>
  8. 可选: 为多个 LDAP 服务器配置故障转移。
    <ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"
        		host="ldapserver1.mycity.mycompany.com" port="389" ignoreCase="true"
         		baseDN="o=ibm,c=us" ldapType="IBM Tivoli Directory Server" idsFilters="ibm_dir_server">
    		<failoverServers name="failoverLdapServersGroup1">
    				<server host="ldapserver2.mycity.mycompany.com" port="389" />
    				<server host="ldapserver3.mycity.mycompany.com" port="389" />
    		</failoverServers>
    		<failoverServers name="failoverLdapServersGroup2">
    				<server host="ldapserver4.mycity.mycompany.com" port="389" />
    		</failoverServers>
    </ldapRegistry>
    
    <idsLdapFilterProperties id="ibm_dir_server"
    	    	    userFilter="(&amp;(uid=%v)(objectclass=ePerson))"
    	    	    groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
                     (objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"
    	    	    userIdMap="*:uid" groupIdMap="*:cn"
    	    groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;
                          groupOfNames:member;groupOfUniqueNames:uniqueMember">
    </idsLdapFilterProperties>

    有关 ldapRegistryfailoverServers 元素的更多信息,请参阅 LDAP 用户注册表

  9. 可选: 配置多个 LDAP 注册表。如果在 server.xml 文件中配置了多个 LDAP 注册表,那么会自动地联合这些注册表。请确保这些用户在所有联合存储库中唯一,否则用户注册表操作不会成功。
    注: 如果使用多个联合 LDAP 存储库,那么每个存储库必须定义唯一 baseDN。
    <ldapRegistry host="ldapserver1.mycity1.mycompany.com" baseDN="o=mycompany,c=us"
        port="123" ldapType="IBM Tivoli Directory Server"> 
    </ldapRegistry>
    
    <ldapRegistry host="ldapserver2.mycity2.mycompany.com" 
        baseDN="cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
        port="456"
        ldapType="Microsoft Active Directory" 
        bindDN="cn=testuser,cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
        bindPassword="{xor}KzosKyosOi0vKDs=">
    </ldapRegistry>
    注:
    • 最佳做法是,指定 federatedRepository 元素以联合多个 LDAP 注册表,但并非必需这样做,因为这些注册表会自动联合。如果指定了 federatedRepository 元素来配置 participatingBaseEntryprimaryRealm 元素,那么仅对 primaryRealm 元素中定义的存储库执行用户注册表操作。可在 primaryRealm 元素下对不同用户注册表 API 定义输入和输出属性映射。
    • participatingBaseEntry 元素的 name 属性必须与 ldapRegistry 元素中所指定 baseDN 属性的值相同。在下列示例中,对主机 ldapserver1.mycity1.mycompany.com 上的 LDAP 注册表配置了 baseDNname 属性。baseDN 属性的值必须与 LDAP 服务器中子树的值相同,而 name 属性的值必须为联合用户注册表中该子树的名称。可选择性地指定 name 属性。缺省情况下,name 属性和 baseDN 属性使用相同的值。如果在 ldapRegistry 元素中指定了 name 属性,那么 participatingBaseEntry 元素中的 name 属性和 ldapRegistry 元素中的 name 属性必须使用相同的值。
    <ldapRegistry host="ldapserver1.mycity1.mycompany.com" baseDN="o=mycompany,ou=myou,c=us"
        port="123" ldapType="IBM Tivoli Directory Server" name="o=mybaseentry">
    </ldapRegistry>
    
    <ldapRegistry host="ldapserver2.mycity2.mycompany.com" 
        baseDN="cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
        port="456"
        ldapType="Microsoft Active Directory" 
        bindDN="cn=testuser,cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
        bindPassword="{xor}KzosKyosOi0vKDs=">
    </ldapRegistry>
    
    <federatedRepository>
    	 	 <primaryRealm name="RealmName" delimiter="@" allowOpIfRepoDown="true">
    	 		 	<participatingBaseEntry name="o=mybaseentry"/>
    		 		 <participatingBaseEntry name="cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com"/>
    	 	 	 	 <uniqueUserIdMapping inputProperty="uniqueName" outputProperty="uniqueName"/>
    	 	 	 	 <userSecurityNameMapping inputProperty="principalName" outputProperty="principalName"/>
            		 		 <userDisplayNameMapping inputProperty="principalName" outputProperty="principalName"/>
    		 		 <uniqueGroupIdMapping inputProperty="uniqueName" outputProperty="uniqueName"/>
            		 		 <groupSecurityNameMapping inputProperty="cn" outputProperty="cn"/>
            		 		 <groupDisplayNameMapping inputProperty="cn" outputProperty="cn"/>
            		</primaryRealm>
    </federatedRepository>

    有关联合 ldapRegistry 元素的更多信息,请参阅LDAP 用户注册表

  10. 可选: 可对 LDAP 注册表配置其他可选属性,例如 contextPoolldapCache,如以下示例所示:
    <ldapRegistry id="IBMDirectoryServerLDAP" realm="SampleLdapIDSRealm"
            host="host.domain.com" port="389" ignoreCase="true"
            		baseDN="o=domain,c=us"
            		bindDN="cn=testuser,o=domain,c=us"
            		bindPassword="mypassword"
            ldapType="IBM Tivoli Directory Server"
            searchTimeout="8m">
        <contextPool enabled="true" initialSize="1" maxSize="0" timeout="0s" waitTime="3000ms" preferredSize="3"/>
        	<ldapCache>
            		<attributesCache size="4000" timeout="1200s" enabled="true" sizeLimit="2000"/>
            		<searchResultsCache size="2000" timeout="600s" enabled="true" resultsSizeLimit="1000"/>
        	</ldapCache>
    </ldapRegistry>
    注:
    • 联合用户注册表使用上下文池机制来提高对 LDAP 服务器进行并行存取的性能。上下文池在高于连接池的级别工作。上下文池中的每个上下文条目对应一个与 LDAP 服务器的套接字连接。配置 LDAP 注册表时,指定此池所使用的绑定凭证。
    • 联合存储库使用高速缓存机制以增强性能。它根据所执行的用户操作对有关 LDAP 用户和组的信息进行高速缓存。例如,如果对 LDAP 用户和组执行搜索操作,那么会对该操作的结果进行高速缓存。可按先前示例中所示在 server.xml 文件中启用 ldapCache 元素。
    故障诊断提示: 要对所有 LDAP 认证问题进行故障诊断,请在 bootstrap.properties 文件中使用以下跟踪规范:
    com.ibm.ws.security.wim.*=all:com.ibm.websphere.security.wim.*=all
  11. 可选: [17.0.0.3 and later]可以在 SSL 配置中确定用来连接至 LDAP 服务器的 SSL 配置,而不是使用 sslRef 属性来指定该 SSL 配置。需要将 sslEnabled 属性设置为 true

    如果未指定 sslRef,那么 SSL 代码将了解是应该使用与 LDAP 主机和端口相匹配的出站过滤器,还是使用 SSL 出站缺省值。有关出站 SSL 选项的更多信息,请参阅配置用于出站通信的 SSL 设置。有关出站过滤器的更多信息,请参阅SSL 配置的出站过滤器

    <ldapRegistry id="ldap" realm="SampleLdapIDSRealm"
          host="ldapserver.mycity.mycompany.com" port="389" ignoreCase="true"
          baseDN="o=mycompany,c=us" 
          ldapType="IBM Tivoli Directory Server"
          sslEnabled="true" > 
          <idsFilters
          	    userFilter="(&amp;(uid=%v)(objectclass=ePerson))"
          	    groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
                       (objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"
          userIdMap="*:uid"
          groupIdMap="*:cn"
          groupMemberIdMap="mycompany-allGroups:member;mycompany-allGroups:uniqueMember;
          groupOfNames:member;groupOfUniqueNames:uniqueMember">
          </idsFilters> 
    </ldapRegistry>

用于指示主题类型的图标 任务主题

文件名:twlp_sec_ldap.html