# Defining User Directories

User and group authentication is carried out against either an existing Windows NT domain, an LDAP directory, or an ODBC data source. When you set up Advanced security, you must specify at least one user directory. You can add as many user directories as you like. Once you define a user directory, it is available for you to use with any security context you define for this security server.

- Windows NT Domains -- Authenticating against a Windows NT domain makes sense if you are already working in a Windows NT environment or will be deploying your application code to a Windows NT environment. This method is a very quick way to implement ColdFusion Advanced security, since users and groups have already been defined. ColdFusion Advanced security doesn't provide any user/group management facilities; you must manage users and groups using the Windows NT User Manager for Domains administrative utility.
- LDAP Directories -- If you are running ColdFusion Server on a UNIX server, you can only use LDAP directories to store your security profile information.

  ColdFusion includes a restricted-use license of the Netscape Directory Server. This embedded Netscape Directory Server is restricted for use in conjunction with security access control, policy storage, and user authentication and cannot be used for any other purpose. Only Netscape-supplied Directory Server administration tools, command line programs and user interfaces, provided with the embedded version can be used to modify or access the database in a manner consistent with its restricted license. There is no user count restriction on your use of Directory Server. On UNIX, you can find the Netscape Directory Server tar file(s) in the `ldap` directory on the ColdFusion CD.

  To use the Netscape Direcotry Server on UNIX, you must install it before installing ColdFusion Server. If you have already installed ColdFusion Server and you want to use the Netscape Directory Server to store security profile information, you must reinstall ColdFusion after installing Netscape Directory Server.

- ODBC Data Sources -- If your ColdFusion applications are already using a Sybase, Oracle, or any other database that supports connections through ODBC, you can use your existing database to also store your security profile tables. You must register an ODBC data source with ColdFusion before you can use it to store security profile information. See Chapter 4, "Managing Data Sources" for more information about registering data sources with ColdFusion. See "Specifying Resources to Protect" to learn how to use an ODBC data source for username and password security authentication.

| To define a user directory:

1. In the Advanced Server Security page of the Administrator, click the User Directories button.
2. Enter a name for the user directory in the User Directory text box and click Add. The name you enter here is an internal name that ColdFusion uses to refer to this user directory. You can enter any name you want.

   You see the New User Directory page.

3. Select Windows NT, LDAP, or ODBC in the Namespace drop-down menu.
4. Enter the appropriate information the Location field:
   - If your user directory is an LDAP directory, enter the name of the LDAP server that hosts the directory.
   - If your user directory is an ODBC data source, enter the fully-qualified name of the database file to use.
   - If your user directory is an NT Domain, enter the domain name.
5. Enter a username and password if the domain, directory, or data source requires one. You can leave these fields blank if ColdFusion Server is running under Administrator access.
6. Select the Secure Connect check box to implement encrypted transmission of authentication information. Secure Connect must be enabled when accessing an LDAP server over Secure Sockets Layer (SSL).
7. Leave the Add User Directory to Existing Security Context check box selected to add users from this user directory to existing security contexts automatically. If you disable this option, you must manually associate users with each security context you create.
8. If your user directory is an NT Domain or ODBC data source, click Add to define the directory. If your user directory is an LDAP directory, complete the steps that follow to set LDAP directory options.

| To define LDAP options:

1. Enter a Search Root. The Search Root must point to the branch of the LDAP tree where a user namespace logically begins. Typically, this branch represents an "organization" or an "organizational unit" and corresponds to one user directory.
2. Enter a Lookup Start. ColdFusion uses the Lookup Start to construct the non-unique beginning of the DN string, for example, uid=.
3. Enter a Lookup End. ColdFusion uses the Lookup End to construct the part of the DN string that follows user ID, for example, ou=marketing,o=widgetinc.com.
4. Enter a Search Timeout. The Search Timeout indicates the maximum amount of time (in seconds) you want ColdFusion to spend searching a directory.
5. Enter the maximum number of results you want the search to return in the Search Results field.
6. Select a Search Scope from the drop-down list. Enter the depth of your search. For example, if you want to be able to access everything under the search root, select the Subtree option. Otherwise, select the One Level option.
7. Click Add to define the user directory.

The Add User Directory to Existing Security Context box is checked by default. This setting enables you to add users to existing security contexts automatically.

### Using the Sample ODBC Data Source as a User Directory

On Windows systems, you can use an ODBC data source for username/password security authentication. A sample ODBC access database, `SmSampleUsers.mdb`, is installed in the `cfusion\database` directory.

Follow these steps to use this sample database to test the ODBC username/password authentication:

1. Use the ColdFusion Administrator to create an ODBC data source using the Microsoft Access ODBC driver. Be sure to name the data source SmSampleUsers and point at the `SmSampleUsers.mdb` file installed in the `cfusion\database` directory.
2. Use the ColdFusion Administrator Advanced Security page to add a User Directory. Select the ODBC namespace and enter SmSampleUsers in the location form field. See "Defining User Directories" for more information.
3. Associate a user or group with a policy in your security context. Example username/passwords are admin/secret and vlander/firewall. You can browse the the username/passwords in the Access database file.

The ODBC username/password requires the `SmDsQuery.ini` file, which is installed in the `cfusion\bin` directory. The file contains the SQL for the SmSampleUsers data source:

    [SmSampleUsers]
    Query_Enumerate=select Name, 'User' as Class from SmUser Union
        select Name, 'Group' as Class from SmGroup order by Class

    Query_InitUser=select Name from SmUser where Name = '%s'

    Query_AuthenticateUser=select Name from SmUser where Name = '%s'
        and Password = '%s'

    Query_GetGroups=select SmGroup.Name from SmGroup, SmUser, SmUserGroup
        where SmUser.Name = '%s' and SmUser.Id  = SmUserGroup.UserId
        and SmGroup.Id = SmUserGroup.GroupId

    Query_GetUserProp=select %s from SmUser where Name = '%s'

    Query_SetUserProp=update SmUser set %s = %s where Name = '%s'

    Query_GetObjInfo=select Name, 'User' from SmUser where Name = '%s'
        Union select Name, 'Group' from SmGroup where Name = '%s'

    Query_GetUserProps=Name, Id, FirstName, LastName,
        TelephoneNumber, EmailAddress

    Query_IsGroupMember=select Id from SmUserGroup
        where UserId = (select Id from SmUser where Name = '%s')
        and GroupId = (select Id from SmGroup where Name = '%s')

Each ODBC data source you use for authenticating users requires a section of the same name in this INI file. The section must contain the appropriate SQL statements to authenticate users. You can use the SmSampleUsers section as an example.