模块 jdk.security.auth

软件包 com.sun.security.auth.module

Class LdapLoginModule

java.lang.Object

com.sun.security.auth.module.LdapLoginModule

实现的所有接口

LoginModule

public class LdapLoginModule
extends Object
implements LoginModule

LoginModule执行基于LDAP的身份验证。 根据存储在LDAP目录中的相应用户凭据验证用户名和密码。 该模块要求提供CallbackHandler以支持NameCallback和PasswordCallback 。 如果认证成功，则新LdapPrincipal使用用户的专有名称创建一个新的UserPrincipal使用用户的用户名创建并且两者都与当前相关Subject 。

此模块以三种模式之一运行： 搜索优先 ， 身份验证优先或仅身份验证 。 通过指定一组特定选项来选择模式。

在搜索优先模式中，搜索LDAP目录以确定用户的可分辨名称，然后尝试进行身份验证。 使用提供的用户名和指定的搜索过滤器执行（匿名）搜索。 如果成功，则使用用户的可分辨名称和提供的密码尝试进行身份验证。 要启用此模式，请设置userFilter选项并省略authIdentity选项。 如果事先不知道用户的专有名称，请使用搜索优先模式。

在身份验证优先模式下，使用提供的用户名和密码尝试进行身份验证，然后搜索LDAP目录。 如果身份验证成功，则使用提供的用户名和指定的搜索过滤器执行搜索。 要启用此模式，请设置authIdentity和userFilter选项。 访问已配置为禁止匿名搜索的LDAP目录时，请使用authentication-first模式。

在仅身份验证模式下，使用提供的用户名和密码尝试进行身份验证。 不搜索LDAP目录，因为已知用户的可分辨名称。 要启用此模式，请将authIdentity选项设置为有效的可分辨名称，并省略userFilter选项。 当事先知道用户的可分辨名称时，请使用仅身份验证模式。

以下选项是必需的，必须在此模块的登录名Configuration中指定：

userProvider=ldap_urls

此选项标识存储用户条目的LDAP目录。 ldap_urls是一个空格分隔的LDAP URL列表（ RFC 2255 ），用于标识要使用的LDAP服务器以及用户条目所在目录树中的位置。 当指定多个LDAP URL时，依次尝试每个URL，直到建立第一个成功连接。 必须使用百分号字符的标准机制（' % '）后跟两个十六进制数字（参见URI ）来转义URL的可分辨名称组件中的空格 。 还必须从URL中省略查询组件。

支持通过DNS（ RFC 2782 ）自动发现LDAP服务器（一旦DNS配置为支持此类服务）。 通过省略LDAP URL中的主机名和端口号组件来启用它。

此模块还识别以下可选的Configuration选项：

userFilter=ldap_filter

此选项指定用于在LDAP目录中查找用户条目的搜索过滤器。 它用于确定用户的专有名称。 ldap_filter是LDAP过滤器字符串（ RFC 2254 ）。 如果它包含特殊标记“ {USERNAME} ”，则在使用过滤器搜索目录之前，该标记将替换为提供的用户名值。

authIdentity=auth_id

此选项指定在将用户验证到LDAP目录时要使用的标识。 auth_id可以是LDAP专有名称字符串（ RFC 2253 ）或其他一些字符串名称。 它必须包含特殊标记“ {USERNAME} ”，在使用名称进行身份验证之前，该标记将替换为提供的用户名值。 请注意，如果此选项不包含可分辨名称，则还必须指定userFilter选项。

authzIdentity=authz_id

此选项指定用户的授权标识。 authz_id是任何字符串名称。 如果它包含带花括号的单个特殊标记，则该标记将被视为属性名称，并将替换为用户LDAP条目中该属性的单个值。 如果找不到该属性，则忽略该选项。 提供此选项并且用户已成功通过身份验证后，将使用授权标识创建其他UserPrincipal，并将其与当前的Subject关联。

useSSL

如果是false ，则此模块在尝试身份验证之前未与LDAP服务器建立SSL连接。 SSL用于保护用户密码的隐私，因为它通过LDAP以明文形式传输。 默认情况下，此模块使用SSL。

useFirstPass

如果是true ，则此模块从模块的共享状态检索用户名和密码，使用“javax.security.auth.login.name”和“javax.security.auth.login.password”作为相应的密钥。 检索到的值用于身份验证。 如果身份验证失败，则不会尝试重试，并将失败报告回调用应用程序。

tryFirstPass

如果是true ，则此模块从模块的共享状态检索用户名和密码，使用“javax.security.auth.login.name”和“javax.security.auth.login.password”作为相应的密钥。 检索到的值用于身份验证。 如果身份验证失败，模块将使用CallbackHandler检索新的用户名和密码，并进行另一次身份验证尝试。 如果身份验证失败，则会将故障报告回调用应用程序。

storePass

如果是true ，则此模块将使用“javax.security.auth.login.name”和“javax.security.auth.login.password”作为相应的密钥存储在模块的共享状态下从CallbackHandler获取的用户名和密码。 如果共享状态下的用户名和密码已存在现有值，或者身份验证失败，则不会执行此操作。

clearPass

如果是true ，则在完成身份验证（登录和提交）两个阶段后，此模块将清除存储在模块共享状态中的用户名和密码。

debug

如果是true ，则调试消息将显示在标准输出流上。

任意"JNDI properties"也可以在指定的Configuration 。 它们被添加到环境中并传递给LDAP提供程序。 请注意，此模块直接设置以下四个JNDI属性，如果配置中也存在，则忽略这些属性：

• java.naming.provider.url
• java.naming.security.principal
• java.naming.security.credentials
• java.naming.security.protocol

三个样本Configuration如下所示。 第一个激活搜索优先模式。 它标识LDAP服务器并指定用户的条目由其uid和objectClass属性定位。 它还指定应创建基于用户的employeeNumber属性的标识。 第二个激活身份验证优先模式。 它要求动态定位LDAP服务器，直接使用提供的用户名执行身份验证，但不保护SSL，并且用户的条目可以通过三个命名属性之一及其objectClass属性来定位。 第三个激活仅验证模式。 它标识备用LDAP服务器，它指定用于身份验证的可分辨名称和用于授权的固定标识。 不执行目录搜索。

  ExampleApplication {
         com.sun.security.auth.module.LdapLoginModule REQUIRED
              userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
              userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))"
              authzIdentity="{EMPLOYEENUMBER}"
              debug=true;
     };

     ExampleApplication {
         com.sun.security.auth.module.LdapLoginModule REQUIRED
             userProvider="ldap:///cn=users,dc=example,dc=com"
             authIdentity="{USERNAME}"
             userFilter="(&(|(samAccountName={USERNAME})(userPrincipalName={USERNAME})(cn={USERNAME}))(objectClass=user))"
             useSSL=false
             debug=true;
     };

     ExampleApplication {
         com.sun.security.auth.module.LdapLoginModule REQUIRED
             userProvider="ldap://ldap-svr1 ldap://ldap-svr2"
             authIdentity="cn={USERNAME},ou=people,dc=example,dc=com"
             authzIdentity="staff"
             debug=true;
     }; 

注意：

当SecurityManager处于活动状态时，必须为创建LoginContext并使用LoginModule的应用程序授予某些权限。

如果应用程序使用已安装的 Configuration创建登录上下文，则必须为应用程序授予AuthPermission以创建登录上下文。 例如，以下安全策略允许用户当前目录中的应用程序实例化任何登录上下文：

  grant codebase "file:${user.dir}/" {
         permission javax.security.auth.AuthPermission "createLoginContext.*";
     }; 

或者，如果应用程序使用调用者指定的 Configuration创建登录上下文，则必须为应用程序授予LoginModule所需的权限。 此模块需要以下两个权限：

• SocketPermission连接到LDAP服务器。
• AuthPermission修改了与5253607610548相关联的Principal的设置 。

例如，以下安全策略在用户的当前目录中授予此模块所需的所有权限：

  grant codebase "file:${user.dir}/" {
         permission java.net.SocketPermission "*:389", "connect";
         permission java.net.SocketPermission "*:636", "connect";
         permission javax.security.auth.AuthPermission "modifyPrincipals";
     }; 

从以下版本开始：

1.6

构造方法摘要

构造方法

构造器	描述
LdapLoginModule()

方法摘要

变量和类型	方法	描述
boolean	abort()	中止用户身份验证。
boolean	commit()	完成用户认证。
void	initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)	初始化这个 LoginModule 。
boolean	login()	开始用户验证。
boolean	logout()	注销用户。

声明方法的类 java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

LdapLoginModule

public LdapLoginModule()

方法详细信息

initialize

public void initialize(Subject subject,
                       CallbackHandler callbackHandler,
                       Map<String,?> sharedState,
                       Map<String,?> options)

初始化这个 LoginModule 。

Specified by:

initialize在界面 LoginModule

参数

subject - 要经过身份验证的 Subject 。

callbackHandler - 获取用户名和密码的 CallbackHandler 。

sharedState - 共享 LoginModule州。

options - 此特定 LoginModule的登录名 Configuration指定的选项。

login

public boolean login()
              throws LoginException

开始用户验证。

获取用户的凭据并根据指定的LDAP目录验证它们。

Specified by:

login在接口 LoginModule

结果

总是如此，因为这个 LoginModule不应该被忽略。

异常

FailedLoginException - 如果身份验证失败。

LoginException - 如果此 LoginModule无法执行身份验证。

commit

public boolean commit()
               throws LoginException

完成用户认证。

如果LoginContext的整体身份验证成功（相关的REQUIRED，REQUISITE，SUFFICIENT和OPTIONAL LoginModules成功），则调用此方法。

如果此LoginModule自己的身份验证尝试成功（通过检索login方法保存的私有状态进行检查），则此方法将LdapPrincipal和一个或多个UserPrincipal与位于Subject中的LoginModule 。 如果此LoginModule自己的身份验证尝试失败，则此方法将删除最初保存的任何状态。

Specified by:

commit在接口 LoginModule

结果

如果此LoginModule自己的登录和提交尝试成功，则返回true，否则返回false。

异常

LoginException - 如果提交失败

abort

public boolean abort()
              throws LoginException

中止用户身份验证。

如果整体验证失败，则调用此方法。 （相关的必需，要求，充足和可选的LoginModule没有成功）。

如果此LoginModule自己的身份验证尝试成功（通过检索login和commit方法保存的私有状态进行检查），则此方法将清除最初保存的任何状态。

Specified by:

abort在接口 LoginModule

结果

如果此LoginModule自己的登录和/或提交尝试失败，则返回false，否则返回true。

异常

LoginException - 如果中止失败。

logout

public boolean logout()
               throws LoginException

注销用户。

此方法删除由commit方法添加的commit 。

Specified by:

logout在接口 LoginModule

结果

在所有情况下都是如此，因为 LoginModule不应该被忽略。

异常

LoginException - 如果注销失败。