Spec-Zone .ru
спецификации, руководства, описания, API
|
|
JAAS | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.sun.security.auth.module.LdapLoginModule
public class LdapLoginModule
This LoginModule
performs LDAP-based authentication.
A username and password is verified against the corresponding user
credentials stored in an LDAP directory.
This module requires the supplied CallbackHandler
to support a
NameCallback
and a PasswordCallback
.
If authentication is successful then a new LdapPrincipal
is created
using the user's distinguished name and a new UserPrincipal
is
created using the user's username and both are associated
with the current Subject
.
This module operates in one of three modes: search-first, authentication-first or authentication-only. A mode is selected by specifying a particular set of options.
In search-first mode, the LDAP directory is searched to determine the
user's distinguished name and then authentication is attempted.
An (anonymous) search is performed using the supplied username in
conjunction with a specified search filter.
If successful then authentication is attempted using the user's
distinguished name and the supplied password.
To enable this mode, set the userFilter
option and omit the
authIdentity
option.
Use search-first mode when the user's distinguished name is not
known in advance.
In authentication-first mode, authentication is attempted using the
supplied username and password and then the LDAP directory is searched.
If authentication is successful then a search is performed using the
supplied username in conjunction with a specified search filter.
To enable this mode, set the authIdentity
and the
userFilter
options.
Use authentication-first mode when accessing an LDAP directory
that has been configured to disallow anonymous searches.
In authentication-only mode, authentication is attempted using the
supplied username and password. The LDAP directory is not searched because
the user's distinguished name is already known.
To enable this mode, set the authIdentity
option to a valid
distinguished name and omit the userFilter
option.
Use authentication-only mode when the user's distinguished name is
known in advance.
The following option is mandatory and must be specified in this
module's login Configuration
:
userProvider=ldap_urls
%
')
followed by two hexadecimal digits (see URI
).
Query components must also be omitted from the URL.
Automatic discovery of the LDAP server via DNS
(
This module also recognizes the following optional Configuration
options:
userFilter=ldap_filter
ldap_filter
is an LDAP filter string
({USERNAME}
"
then that token will be replaced with the supplied username value
before the filter is used to search the directory. authIdentity=auth_id
auth_id
may be an LDAP distinguished name string
({USERNAME}
"
which will be replaced with the supplied username value before the
name is used for authentication.
Note that if this option does not contain a distinguished name then
the userFilter
option must also be specified. authzIdentity=authz_id
authz_id
is any string name.
If it comprises a single special token with curly braces then
that token is treated as a attribute name and will be replaced with a
single value of that attribute from the user's LDAP entry.
If the attribute cannot be found then the option is ignored.
When this option is supplied and the user has been successfully
authenticated then an additional UserPrincipal
is created using the authorization identity and it is assocated with
the current Subject
. useSSL
false
, this module does not establish an SSL connection
to the LDAP server before attempting authentication. SSL is used to
protect the privacy of the user's password because it is transmitted
in the clear over LDAP.
By default, this module uses SSL. useFirstPass
true
, this module retrieves the username and password
from the module's shared state, using "javax.security.auth.login.name"
and "javax.security.auth.login.password" as the respective keys. The
retrieved values are used for authentication. If authentication fails,
no attempt for a retry is made, and the failure is reported back to
the calling application.tryFirstPass
true
, this module retrieves the username and password
from the module's shared state, using "javax.security.auth.login.name"
and "javax.security.auth.login.password" as the respective keys. The
retrieved values are used for authentication. If authentication fails,
the module uses the CallbackHandler
to retrieve a new username
and password, and another attempt to authenticate is made. If the
authentication fails, the failure is reported back to the calling
application.storePass
true
, this module stores the username and password
obtained from the CallbackHandler
in the module's shared state,
using
"javax.security.auth.login.name" and
"javax.security.auth.login.password" as the respective keys. This is
not performed if existing values already exist for the username and
password in the shared state, or if authentication fails.clearPass
true
, this module clears the username and password
stored in the module's shared state after both phases of authentication
(login and commit) have completed.debug
true
, debug messages are displayed on the standard
output stream.
Arbitrary
JNDI properties
may also be specified in the Configuration
.
They are added to the environment and passed to the LDAP provider.
Note that the following four JNDI properties are set by this module directly
and are ignored if also present in the configuration:
java.naming.provider.url
java.naming.security.principal
java.naming.security.credentials
java.naming.security.protocol
Three sample Configuration
s are shown below.
The first one activates search-first mode. It identifies the LDAP server
and specifies that users' entries be located by their uid
and
objectClass
attributes. It also specifies that an identity
based on the user's employeeNumber
attribute should be created.
The second one activates authentication-first mode. It requests that the
LDAP server be located dynamically, that authentication be performed using
the supplied username directly but without the protection of SSL and that
users' entries be located by one of three naming attributes and their
objectClass
attribute.
The third one activates authentication-only mode. It identifies alternative
LDAP servers, it specifies the distinguished name to use for
authentication and a fixed identity to use for authorization. No directory
search is performed.
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
is active then an application
that creates a LoginContext
and uses a LoginModule
must be granted certain permissions.
If the application creates a login context using an installed
Configuration
then the application must be granted the
AuthPermission
to create login contexts.
For example, the following security policy allows an application in
the user's current directory to instantiate any login context:
grant codebase "file:${user.dir}/" { permission javax.security.auth.AuthPermission "createLoginContext.*"; };Alternatively, if the application creates a login context using a caller-specified
Configuration
then the application
must be granted the permissions required by the LoginModule
.
This module requires the following two permissions:
SocketPermission
to connect to an LDAP server.
AuthPermission
to modify the set of Principal
s
associated with a Subject
.
For example, the following security policy grants an application in the user's current directory all the permissions required by this module:
grant codebase "file:${user.dir}/" { permission java.net.SocketPermission "*:389", "connect"; permission java.net.SocketPermission "*:636", "connect"; permission javax.security.auth.AuthPermission "modifyPrincipals"; };
Constructor Summary | |
---|---|
LdapLoginModule()
|
Method Summary | |
---|---|
boolean |
abort()
Abort user authentication. |
boolean |
commit()
Complete user authentication. |
void |
initialize(Subject subject,
CallbackHandler callbackHandler,
Map<String,?> sharedState,
Map<String,?> options)
Initialize this LoginModule . |
boolean |
login()
Begin user authentication. |
boolean |
logout()
Logout a user. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public LdapLoginModule()
Method Detail |
---|
public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)
LoginModule
.
initialize
in interface LoginModule
subject
- the Subject
to be authenticated.callbackHandler
- a CallbackHandler
to acquire the
username and password.sharedState
- shared LoginModule
state.options
- options specified in the login
Configuration
for this particular
LoginModule
.public boolean login() throws LoginException
Acquire the user's credentials and verify them against the specified LDAP directory.
login
in interface LoginModule
LoginModule
should not be ignored.
FailedLoginException
- if the authentication fails.
LoginException
- if this LoginModule
is unable to perform the authentication.public boolean commit() throws LoginException
This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded).
If this LoginModule's own authentication attempt
succeeded (checked by retrieving the private state saved by the
login
method), then this method associates an
LdapPrincipal
and one or more UserPrincipal
s
with the Subject
located in the
LoginModule
. If this LoginModule's own
authentication attempted failed, then this method removes
any state that was originally saved.
commit
in interface LoginModule
LoginException
- if the commit failspublic boolean abort() throws LoginException
This method is called if the overall authentication failed. (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed).
If this LoginModule's own authentication attempt
succeeded (checked by retrieving the private state saved by the
login
and commit
methods),
then this method cleans up any state that was originally saved.
abort
in interface LoginModule
LoginException
- if the abort fails.public boolean logout() throws LoginException
This method removes the Principals
that were added by the commit
method.
logout
in interface LoginModule
LoginModule
should not be ignored.
LoginException
- if the logout fails.
|
JAAS | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |