|
|
|
LDAP user service
To use the LDAP UserService, you need to modify the <apphome>/config/zero.config configuration file.
For more information about directory server configuration, see the documentation of each directory server implementation.
Sample configuration and the zero.config file
To get started with the LDAP user service, the first simple example assumes that you created the following directory:
o=hq,dc=myco,dc=com
|
+ + ou=people,o=hq,dc=myco,dc=com
| |
| + uid=mdavis,ou=people,o=hq,dc=myco,dc=com
| |
| + uid=afranklin,ou=people,o=hq,dc=myco,dc=com
|
+ ou=group,o=hq,dc=myco,dc=com
|
+ cn=Manager,ou=group,o=hq,dc=myco,dc=com
|
+ cn=Employee,ou=group,o=hq,dc=myco,dc=com
The following sample configuration in the zero.config file is for the preceding sample directory:
/config/security/userservice/registryType="ldap"
/config/security/userservice/ldap += {
"jndiProviderUrl" : ""ldap://localhost:10389/",
"jndiSecurityPrincipal" : "uid=admin,ou=system",
"jndiSecurityCredentials" : "secret"
"ldapUserIdRdnPattern" : "uid={0}",
"ldapUserIdBaseDn" : "ou=people,o=hq,dc=myco,dc=com",
"ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
}
Configuring the LDAP user service in the zero.config file
When you use an LDAP based directory as the registry, you must configure the LDAP user service in the /config/security/userservice/ldap section of the zero.config file. You can use the configuration parameters shown in the following table to do this.
| Key | Value | Default Value | Mandatory ? |
|---|
| registryType | file or ldap | file | To use LDAP user service, ldap must be set. |
| jndiProviderUrl | JNDI provider URL | - | Mandatory |
| jndiSecurityAuthentication | The level of authentication used by JNDI. | simple | Optional |
| jndiSecurityPrincipal | Administrator's principal | - | Mandatory in the directory server disallowing anonymous access |
| jndiSecurityCredentials | Administrator's credential (See Leveraging XOREncoding) | - | Mandatory in the directory server disallowing anonymous access |
| jndiInitialContextFactory | Initial context factory name | com.sun.jndi.ldap.LdapCtxFactory | Optional |
| ldapSearchScope | The search scope set to javax.naming.directory.SearchControls: 0(SearchControls.OBJECT_SCOPE) 1(SearchControls.ONELEVEL_SCOPE) 2(SearchControls.SUBTREE_SCOPE) | 2 | Optional |
| ldapSearchTimeLimit | The search time limit, in milliseconds, set to javax.naming.directory.SearchControls. | 30000 | Optional |
| ldapUserIdRdnPattern | The pattern of user entries' RDN. A user ID is embedded in the place holder "{0}" . | - | Mandatory if the search mode is fixed; must be commented out if the mode is flex. Combined with ldapUserIsBaseDN to generate the user entries' DN. |
| ldapUserIdSearchFilterPattern | The pattern of the user search filter. A user ID is embedded in the place holder "{0}" . | (&(uid={0}) (objectclass=inetOrgPerson)) | Optional (Mandatory if the search mode is flex and you need another pattern different from the default) |
| ldapUserIdBaseDn | The root from which the LDAP user service starts to search a user. | - | Mandatory |
| ldapGroupAttributeType | The attribute type of the group name. | cn | Optional |
| ldapGroupBaseDn | The base DN of groups. | - | Mandatory |
| ldapGroupSearchFilterPattern | The filter to search groups to which a user ID belongs. A user ID is embedded in the place holder "{0}" . | (&(uniqueMember={0}) (objectclass=groupOfUniqueNames)) | Optional |
| ignoreBaseDN | Boolean flag support fully qualified domain name (FQDN) lookups. If false, FQDN lookups will be disabled. | true | Optional |
| fullBaseDNFilterPattern | The filter to search for a user based upon the full qualified domain name. | (objectclass=*) | Optional |
The LDAP user service implicitly uses simple as java.naming.security.authentication. No configuration is required but only the simple option is supported. When you specify the attribute type for a user ID, you must set appropriate values for ldapUserIdBaseDn, and ldapUserIdDnPattern or ldapUserIdSearchFilterPattern . When you specify the LDAP object class and its configuration for groups, you must set appropriate values for ldapGroupAttributeType, ldapGroupBaseDn, and ldapGroupSearchFilterPattern.
There are two ways to perform a user search, the fixed mode and the flex mode:
- Fixed mode
- Searches a user with its complete DN that is produced by the
ldapUserIdDnPattern value and a user ID. In this type of search ldapUserIdDnPattern and ldapUserIdBaseDn must be configured.
- Flex mode
- Searches a user with a search filter. It starts the search from a base directory and moves to the sub directories. In this type of search:
-
ldapUserIdBaseDn must be configured. And also ldapUserIdSearchFilterPattern must be configured if the search filter pattern defined in ldapUserIdRdnPattern is different from the default.
-
ldapSearchScope must be the default value, 2 (SearchControls.SUBTREE_SCOPE).
- Remove or comment out
ldapUserIdRdnPattern in the zero.config file. (If this is not removed from the zero.config file, then the LDAP user service searches a user in fixed mode.)
Advanced sample configurations
For an advanced setup of the LDAP user service, these examples assume that you created the following directory:
o=hq,dc=myco,dc=com
|
+ + ou=people,o=hq,dc=myco,dc=com
| |
| + uid=mdavis,ou=people,o=hq,dc=myco,dc=com
| |
| + uid=afranklin,ou=people,o=hq,dc=myco,dc=com
|
+ ou=group,o=hq,dc=myco,dc=com
| |
| + cn=Manager,ou=group,o=hq,dc=myco,dc=com
| |
| + cn=Employee,ou=group,o=hq,dc=myco,dc=com
|
+ o=us,o=hq,dc=myco,dc=com
|
+ ou=people,o=us,o=hq,dc=myco,dc=com
| |
| + uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com
| |
| + uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com
|
+ ou=group,o=us,o=hq,dc=myco,dc=com
|
+ cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com
A zero.config file sample for fixed search
The following sample configuration is for a fixed search based on the same directory structure shown in the preceding Advanced sample configurations section:
/config/security/userservice/registryType="ldap"
/config/security/userservice/ldap += {
"jndiProviderUrl" : ""ldap://localhost:10389/",
"jndiSecurityPrincipal" : "uid=admin,ou=system",
"jndiSecurityCredentials" : "secret"
"ldapUserIdRdnPattern" : "uid={0}",
"ldapUserIdBaseDn" : "ou=people,o=hq,dc=myco,dc=com",
"ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
}
In this example, the LDAP user service:
- Accesses the directory server using LDAP, the URL of which is ldap://localhost:10389/.
- Searches a user in the fixed mode in which:
- It uses the attribute type
uid as the user ID because ldapUserIdRdnPattern contains a uid for the user ID.
- It searches a user entry defined in ldapUserIdBaseDn as
ou=people,o=hq,dc=myco,dc=com in the directory.
- Only
uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
-
uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can never be hit by this search because these are on a sub tree.
- Includes search groups in which:
- The attribute type equals
cn.
- Users are stored with the
uniqueMember attribute type.
- Entries and sub trees are under
o=hq,dc=myco,dc=com.
-
cn=Manager,ou=group,o=hq,dc=myco,dc=com, cn=Employee,ou=group,o=hq,dc=myco,dc=com and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.
A zero.config file sample for flex search
The following sample configuration is for a flex search based on the same directory structure shown in the preceding Advanced sample configurations section:
/config/security/userservice/registryType="ldap"
/config/security/userservice/ldap += {
"jndiProviderUrl" : ""ldap://localhost:10389/",
"jndiSecurityPrincipal" : "uid=admin,ou=system",
"jndiSecurityCredentials" : "secret"
"ldapUserIdBaseDn" : "o=hq,dc=myco,dc=com",
"ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
}
In this example, the LDAP user service:
- Accesses the directory server using LDAP, the URL for which is ldap://localhost:10389/.
- Searches a user in the flex mode in which:
- It uses the attribute type
uid as the user ID because the default value of ldapUserIdSearchFilterPattern includes uid as the user ID.
- It searches a user entry under
o=hq,dc=myco,dc=com and sub trees.
-
uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
-
uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can also be found by this search because it searches for sub trees.
- Includes search groups in which:
- The attribute type is
cn.
- Users are stored with the
uniqueMember attribute type.
- Entries and sub trees under
o=hq,dc=myco,dc=com are included.
-
cn=Manager,ou=group,o=hq,dc=myco,dc=com, cn=Employee,ou=group,o=hq,dc=myco,dc=com and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.
A zero.config file sample for anonymous access
Suppose that the same sample directory (shown in the Advanced sample configurations section) is in the directory server allowing anonymous access. You can have the following configuration to access the directory anonymously:
/config/security/userservice/registryType="ldap"
/config/security/userservice/ldap += {
"jndiProviderUrl" : ""ldap://localhost:10388/",
"ldapUserIdBaseDn" : "o=hq,dc=myco,dc=com",
"ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
}
In this example, the LDAP user service:
- Accesses the directory server using LDAP, the URL for which is ldap://localhost:10388/.
- Searches a user in the flex mode in which:
- It uses the attribute type
uid as the user Id because the default value of ldapUserIdSearchFilterPattern has a uid for the user ID.
- It searches a user entry under
o=hq,dc=myco,dc=com and sub trees.
-
uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
-
uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can also be found by this search because it searches for sub trees.
- Includes search groups in which:
- The attribute type is
cn.
- Users are stored with the attribute type
uniqueMember.
- Entries and sub trees under
o=hq,dc=myco,dc=com are searched.
-
cn=Manager,ou=group,o=hq,dc=myco,dc=com, cn=Employee,ou=group,o=hq,dc=myco,dc=com, and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.
- UserService API behavior would be:
-
Set<Principal> login(String username, String password)
- When
login() is invoked with a correct username and a correct password, authentication is successfully done. Returning set should include all principles about a user itself and groups.
- When
login() is invoked with an incorrect username or an incorrect password, authentication fails. Returning set should be empty.
-
Set<Principal> getUsers(String username)
- Returning set should include all principles about a user itself and groups.
A zero.config sample with security authentication none
Using the same sample directory, as shown above in the Advanced sample configurations section, suppose the directory server allows anonymous access. You can have the following configuration to access the directory anonymously:
/config/security/userservice/registryType="ldap"
/config/security/userservice/ldap += {
"jndiProviderUrl" : ""ldap://localhost:10388/",
"jndiSecurityAuthentication" : "none"
"ldapUserIdBaseDn" : "o=hq,dc=myco,dc=com",
"ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
}
In this example, the LDAP user service:
- Accesses the directory server using LDAP, the URL for which is ldap://localhost:10388/.
- Searches a user in the flex mode in which:
- It uses the attribute type
uid as the user ID because the default value of ldapUserIdSearchFilterPattern has a uid for the user ID.
- It searches a user entry under
o=hq,dc=myco,dc=com and sub trees.
-
uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
-
uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can also be found by this search because it searches for sub trees.
- Includes search groups in which:
- The attribute type is
cn.
- Users are stored with the attribute type
uniqueMember.
- Entries and sub trees under
o=hq,dc=myco,dc=com are searched.
-
cn=Manager,ou=group,o=hq,dc=myco,dc=com cn=Employee,ou=group,o=hq,dc=myco,dc=com, and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.
- UserService API behavior
-
Set<Principal> login(String username, String password)
- When
login() is invoked with a correct username and a correct password, authentication is successfully done. Returning set should include all principles about a user itself and groups.
- Even when
login() is invoked with a correct username and an incorrect password, authentication is successfully done because security authentication is set to none. Returning set should include all principles about a user itself and groups.
-
Set<Principal> getUsers(String username)
- Returning set should include all principles about a user itself and groups.
Note:
- To create, update, and delete entries on a directory, you can make use of any other LDAP tools like JXplorer or LDAPStudio, for example. The LDAP user service provides read-only functions for authentication and authorization of Project Zero.
|
