|
| Sun ONE Directory Server Administration Guide |
Chapter 1 Introduction to Sun™ ONE Directory Server
The Sun™ ONE Directory Server product includes a Directory Server, an Administration Server to manage multiple directories, and Sun ONE Server Console to manage both servers through a graphical interface. This chapter provides overview information about the Directory Server, and the most basic tasks you need to start administering a directory service using the console.
Two new features of Directory Server 5.2 covered in this chapter are plug-in signatures and the DSML-over-HTTP protocol. Verifying plug-in signatures is an additional security feature that allows the server to detect or prevent unauthorized plug-ins from being loaded. Directory Server Markup Language (DSML) is a new XML-based format for sending requests to a directory server.
This chapter includes the following sections:
- Overview of Directory Server Management
- Starting and Stopping the Directory Server
- Starting the Server with SSL Enabled
- Using the Directory Server Console
- Configuring LDAP Parameters
- Verifying Plug-In Signatures
- Configuring DSML
Overview of Directory Server Management
Sun ONE Directory Server is a robust, scalable server designed to manage an enterprise-wide directory of users and resources. It is based on an open-systems server protocol called the Lightweight Directory Access Protocol (LDAP). The Directory Server runs as the ns-slapd process or service on your machine. The server manages the directory contents and responds to client requests.
You perform most Directory Server administrative tasks through the Administration Server, a second server that Sun ONE provides to help you manage Directory Server (and all other Sun ONE servers). Sun ONE Server Console is the graphical interface to the Administration Server. Directory Server console is a part of Sun ONE Server Console designed specifically for use with Sun ONE Directory Server.
You can perform most Directory Server administrative tasks from the Directory Server console. You can also perform administrative tasks manually by editing the configuration files or by using command-line utilities. For more information about the Sun ONE Server Console see Sun ONE Server Console Server Management Guide.
Starting and Stopping the Directory Server
If you are not using Secure Sockets Layer (SSL), you can start and stop the Directory Server using the methods listed here. If you are using SSL, see "Starting the Server with SSL Enabled".
Starting and Stopping the Server From the Command Line (Unix)
If your directory server is stopped and the Directory Server console is not running, you must start the server from the command line. If you do not wish to use the Directory Server console, you may also stop the server from the command line. With root privileges, run one of the following commands:
Solaris Packages
# /usr/sbin/directoryserver start
Other Installations
# ServerRoot/slapd-serverID/start-slapd
or
Solaris Packages
# /usr/sbin/directoryserver stop
Other Installations
# ServerRoot/slapd-serverID/stop-slapd
where serverID is the identifier you specified for the server during installation.
On UNIX, both of these scripts must run with the same UID and GID as the Directory Server. For example, if the Directory Server runs as nobody, you must run the start-slapd and stop-slapd utilities as nobody.
Note that referral mode is no longer available.You can set global referrals by using the Directory Server console. This procedure is explained in "Setting the Default Referrals".
Starting and Stopping the Server From the Control Panel (Windows)
If you are using a Windows system, perform the following steps from the Services Control Panel:
- Select Start > Settings > Control Panel from the desktop.
- Double-click the Services icon.
- Scroll through the list of services and select the Sun ONE Directory Server.
The service name is Sun ONE Directory Server 5.2 (serverID), where serverID is the identifier you specified during server installation or configuration.
- Click the Start or Stop button to perform the desired action.
When stopping the Directory Server, you will be asked to confirm that you want to stop the service.
Starting and Stopping the Server From the Console (All Platforms)
When the Directory Server console is running, you may start, stop, and restart your directory server through its graphical interface. For instructions on running the console, see "Starting Directory Server Console".
- On the top-level Tasks tab of the Directory Server console, click the button beside "Start Directory Server", "Stop Directory Server", or "Restart Directory Server," as appropriate.
When you successfully start or stop your Directory Server from the Directory Server console, the console displays a message dialog stating that the server has been either started or shut down. In case of an error, the console will show all messages pertaining to the error.
Starting the Server with SSL Enabled
Before enabling SSL, you must install and configure certificates on your server. For instructions on managing certificates and enabling SSL, see Chapter 11 "Implementing Security." For information on certificates, certificate databases, and obtaining a server certificate, see Chapter 10, "Using SSL and TLS with Sun ONE Servers," in the Sun ONE Server Console Server Management Guide.
To start the server with SSL enabled, you must provide the password which protects the server's certificates:
- On Windows, you must start the server from the server's host machine. For security reasons, the dialog box prompting you for the password will appear only on the server's host machine.
- On UNIX, you must start the server from the command line.
Alternatively, on either platform, you can create a password file to store your certificate password. By placing your certificate database password in a file, you can start your server from the server console, and also allow your server to automatically restart when running unattended.
The password file must be placed in the following location:
where serverID is the identifier you specified for the server when you installed it.
You need to include the name of the security token and its password in the file as follows:
The device name for the internal certificate database is shown in this example (capitalization and spacing must be exactly as shown):
If you store certificates in an alternate device, use the name of the device that appears in the drop-down menu at the top of the Manage Certificates Dialog. To create certificate databases, you must use the administration server and the Certificate Setup Wizard. For information on using SSL with your Directory Server, see Chapter 11 "Implementing Security."
Using the Directory Server Console
The Directory Server console is an interface that you access as a separate window of the Sun ONE Server Console. You start the Directory Server console from Sun ONE Server Console, as described in the following procedure.
Starting Directory Server Console
- Check that the directory server daemon, slapd-serverID is running. If it is not, as root or administrative user, enter the following command to start it:
Solaris Packages
# /usr/sbin/directoryserver start
Other Installations
# ServerRoot/slapd-serverID/start-slapd
- Check that the administration server daemon, admin-serv is running. If it is not, as root or administrative user, enter the following command to start it:
Solaris Packages
# /usr/sbin/directoryserver start-admin
Other Installations
# ServerRoot/start-admin
- Start Sun ONE Server Console by entering the following command:
Solaris Packages
# /usr/sbin/directoryserver startconsole
Other Installations
# ServerRoot/startconsole
If you are running the Sun ONE Server Console on a machine other than the one where the Sun ONE Administration Server is installed, you may need to configure the connection restrictions on the Administration Server, as described in "Network Settings" in Chapter 7 of the Sun ONE Server Console Server Management Guide.
The Console login window is displayed. Or, if your configuration directory (the directory that contains the o=NetscapeRoot suffix) is stored in a separate instance of Directory Server, a window is displayed requesting the administrator user DN, password, and the URL of the Administration Server for that directory server.
- Log in using the bind DN and password of a user with sufficient access permissions for the operations you want to perform. For example, use cn=Directory Manager, and the appropriate password.
The Sun ONE Server Console is displayed.
- Navigate through the tree in the left-hand panel to find the machine hosting your Directory Server and click on its name or icon to display its general properties.
Figure 1-1 The Sun ONE Server Console
To edit the name and description of your directory server, click the Edit button. Enter the new name and description in the text boxes. Click OK to set the new name and description. The name will appear in the tree on the left, as shown in the previous figure.
Double-click the name of your Directory Server in the tree or click the Open button to display the Directory Server console for managing this directory server. Navigating the Directory Server Console
The Directory Server console provides the interface for browsing and performing administration operations on your Directory Server instance. It always displays four tabs from which you can access all Directory Server functionality:
- Tasks Tab - Contains buttons for administrative tasks such as restarting the server.
- Configuration Tab - Provides access to all parameters for managing the server.
- Directory Tab - Displays and edits the data entries contained in the directory.
- Status Tab - Displays the statistics, logs and replication status of the server.
Tasks Tab
The Tasks tab is the first interface visible when opening the Directory Server console. It contains buttons for all of the major administrative tasks such as starting or stopping the Directory Server as shown in the following figure. To view all of the tasks and their buttons, you may need to scroll through the list.
Figure 1-2 Tasks Tab of the Directory Server Console
You must be logged in as a user with administrator rights in order to perform these tasks. The task buttons will not be visible to users with insufficient rights.
Configuration Tab
The Configuration tab of the Directory Server console provides interfaces and dialogs to view and modify all directory settings such as those for suffixes, replication, schema, logs, and plug-ins. These dialogs are only available or will only take effect if you are logged in as a user with administrator rights.
The left side of this tab contains a tree of all configuration functions and the right-hand side displays the interface specific to managing each function. These interfaces often contain other tabs, dialogs or pop-up windows. For example, the following figure shows the general settings for the entire directory.
Figure 1-3 Configuration Tab of the Directory Server Console
When you select a configurable item in the left-hand tree, the current settings for that item will appear in one or more tabs in the right-hand panel. For the explanation and behavior of these settings, please refer to the chapter in this guide that describes each functionality. Depending on the setting, some changes will take effect immediately when saved, and others not until the server is restarted. The console will display a dialog informing you when the server needs to be restarted.
Unsaved changes in a tab are signalled by a red mark next to the tab name. Unsaved changes will remain on the tab even if you configure another item or view one of the other major tabs. The Save and Reset buttons apply to all tabs of a given configurable item, but do not affect the unsaved settings of other items.
Most text fields will only allow you to enter values that have the correct syntax for the setting. By default, the label of the setting and the value that you type will be highlighted in red until its syntax is correct. The Save button will be disabled until all settings have valid syntax. You may choose italic font for highlighting incorrect values, as described in "Visual Configuration Preferences".
Directory Tab
The Directory Tab of the console displays the directory entries as a tree for easy navigation. In this tab, all entries and the attributes they contain can be browsed, displayed and edited.
Figure 1-4 Directory Tab of the Directory Server Console
If the bind DN given during the login has sufficient access rights, the configuration entries are viewed as normal entries and may be modified directly. However, you should always use the dialogs available through the Configuration Tab to change the configuration settings safely.
Several options are available through the View menu to change the layout and contents of the Directory Tab. New layout options include viewing all entries in a single tree, including leaf entries, and also displaying attributes in the right-hand pane. The default is to view leaf entries on the right and not in the left-hand tree.
The View>Display options enable ACI counts, role counts, and inactivation state icons for all entries in the directory tree. In the previous figure, ACI counts and leaf entries are displayed in the left-hand tree, and attribute values for the selected entry are displayed in the right-hand pane. For more information, see "Directory Tree View Options".
Status Tab
The status tab displays server statistics and log messages. The tree on the left lists all status items, and when selected, the contents of each is displayed in the right-hand pane. For example, the following figure shows a table of log entries.
Figure 1-5 Status Tab of the Directory Server Console
Viewing the Current Bind DN From the Console
You can view the bind DN you used to log in to the Directory Server console by clicking the login icon in the lower-left corner of the display. The current bind DN then appears next to the login icon as shown here:
Changing Your Login Identity
When you create or manage entries from the Directory Server console, and when you first access the Sun ONE Server Console, you are given the option to log in by providing a bind DN and a password. This identifies who is accessing the directory tree and determines the access permissions granted to perform operations.
You can log in with the Directory Manager DN when you first start the Sun ONE Server Console. At any time, you can choose to log in as a different user, without having to stop and restart the Console.
To change your login in Sun ONE Server Console:
- On the Directory Server console, select the Tasks tab and click the button next to the label "Log on to the Directory Server as a New User." Or, when in another console tab, select the Console>Log in as New User menu item.
A login dialog box appears.
- Enter the new DN and password and click OK.
Enter the full distinguished name of the entry with which you want to bind to the server. For example, if you want to bind as the Directory Manager, then enter the following DN in the Distinguished Name text box:
cn=Directory Manager
The Directory Manager DN and password are further explained in the following section.
Using the Online Help
The online help provides context-sensitive information for most tabs and dialogs of the Directory Server console. The Help button is usually located in the bottom right-hand corner of these interfaces. The keyboard shortcut for invoking the context-sensitive help on any screen is always Alt-P.
Invoking the online help will display an HTML-based page in the Console's built-in browser. From there, you may click the Launch in Browser button to open the same page in an external browser such as Netscape Communicator. Within the online help, links to further information will also open an external browser window.
Each online help page gives an explanation of the fields and buttons contained in the corresponding tab or dialog. Use this information to guide you when interpreting, entering or modifying values through the console.
The help system for Sun ONE Directory Server is dependent upon Sun ONE Administration Server. If you are running Directory Server console on a machine remote to your Administration Server, you will need to verify the following:
- You may need to configure the connection restrictions enforced on the Administration Server to allow access from your machine, as described in "Network Settings" in Chapter 7 of the Sun ONE Server Console Server Management Guide.
- If you wish to use an external browser to view the online help pages, and your browser is configured to use proxies, you must do one of the following:
- Disable proxies in your browser configuration. In Netscape Communicator, select the Edit>Preferences menu item. Then select the Advanced>Proxies category to access the proxy configuration. In Internet Explorer, select Internet Options from the Tools menu.
- Configure the connection restrictions in the Administration Server to allow access from the proxy server.
Caution
Configuring Administration Server to allow access from a proxy server creates a potential security hole in your system.
The Console Clipboard
The Directory Server console uses your system clipboard to copy, cut, and paste text. To reduce typing, you can copy the DN or URL of an entry into the clipboard when navigating within the Directory tab.
Before opening a dialog or another tab where you need to paste the DN or URL in a text field:
- On the top-level Directory tab of the Directory Server console, browse through the tree and select (left-click) the entry whose DN or URL you want to copy.
- Then select either Edit>Copy DN or Edit>Copy URL from the menu.
Console Settings
The Directory Server console provides many settings for customizing how information in displayed in the Configuration and Directory tabs.
Visual Configuration Preferences
When you modify configuration parameters and enter values in fields on the top-level configuration tab, Directory Server console uses colored text to indicate valid input. For example, if you enable a feature that requires you to enter further configuration values, the labels of the required fields will appear red and then turn blue once you enter valid value.
By default the console uses red and blue colors, but you may modify this behavior as follows:
- On any tab of the Directory Server console, select the Edit>Preferences menu item. In the Console Preferences dialog, select the Misc. tab.
- Choose the radio button for the visual configuration indicator that you prefer. You may choose colored fonts or font appearances or both.
- For a description of the settings on the other tabs of the Console Preferences dialog, see "Customizing Sun ONE Server Console" in Chapter 3 of the Sun ONE Server Console Server Management Guide.
Then click OK to save your changes.
- Exit all windows of the Sun ONE Server Console and restart it.
Directory Tree View Options
On the top-level Directory tab of the Directory Server console, the items of the View menu allow you to display additional information in the directory tree and select what appears in the right-hand panel.
The following View options affect the contents of the Directory tab:
- Follow Referrals - When this checkbox is selected, the directory tree will show the entries and all children of the target of the referral, as if they were in the directory. When the checkbox is empty, referrals are shown as referral entries. For more information, see "Creating Smart Referrals".
- Sort Objects - When this checkbox is empty, entries are displayed in the order in which they are returned by the server. When this checkbox is selected, entries at the same level in the directory tree are sorted according their display attribute describe below. For information on how to sort large subtrees without impacting server performance, see "Browsing Indexes for the Console".
Entries displayed by the following attributes will be sorted: cn, givenname, o, ou, sn, and then uid. Entries displayed by other attributes will not be sorted.
- Display>ACI Count - If an entry contains one or more access control instructions (ACIs) in the aci attribute, the directory tree will show how many beside the entry. For more information, see Chapter 6 "Managing Access Control."
- Display>Role Count - If an entry is a member of one or more roles, the directory tree will show how many beside the entry. For more information, see "Assigning Roles".
- Display>Inactivation State - If a user or group entry has been deactivated to prevent binding to the server, the directory tree will show a red box and line through the entry's icon. For more information, see "Inactivating and Activating Users and Roles".
- Layout>View Children - When you choose this layout option, the tree in the left-hand panel does not show leaf entries of the directory, and selecting a parent node in the left-hand panel displays all of its children, including leaf entries, in the right-hand panel. You may select entries in either panel.
- Layout>View Only Tree - With this layout option, the Directory tab has only one panel that displays a tree containing all entries in the directory.
- Layout>View Attributes - In this layout, the left-hand panel displays a tree containing all entries in the directory, and the right-hand panel displays the attributes and values stored in the entry selected in the tree.
- Display Attribute - Click this menu item to see the Display Attribute dialog and choose the label for entries displayed in the Directory tab. By default, the label is the value of the entry's first RDN attribute, for example People. For base entries that do not have an RDN, the label is entire DN, for example dc=example,dc=com.
To use a different attribute to display entries in the directory tree, choose the other radio button and select an attribute. Entries without the chosen attribute will still use the entry's first RDN attribute. By default, only the attribute value is used in the label. If you select the "Show attribute name" checkbox, the label will look like ou=People.
- Refresh - After certain operations you must refresh the display of the directory tree to view the new value. Selecting this item will reload the entire directory tree from the server.
Configuring LDAP Parameters
The LDAP parameters are the basic settings in your directory server, such as the distinguished name (DN) of the Directory Manager, the global read-only setting, the port configuration, and the ability to track all directory modification times.
Configuring the Directory Manager
The Directory Manager is the privileged server administrator, comparable to the root user in UNIX. Access control does not apply to the entry you define as Directory Manager. You initially defined this entry during installation. The default is cn=Directory Manager.
The DN of the directory manager is stored in the nsslapd-rootDN attribute and the password in the nsslapd-rootpw attribute of the cn=config branch.
Use the Directory Server console to change the Directory Manager DN, its password, and the encryption scheme used for this password:
- Log in to the Console as Directory Manager.
If you are already logged in to the Console, see "Changing Your Login Identity" for instructions on how to log in as a different user.
- On the top-level Configuration tab, select the server node at the root of the navigation tree, and select the Settings tab in the right-hand panel.
- Enter the new distinguished name in the Directory Manager DN field. The default value is the one defined during installation.
- From the Manager Password Encryption pull-down menu, select the storage scheme you want the server to use to store the password for Directory Manager.
- Enter the new password and confirm it using the text fields provided.
- Click Save.
Changing Directory Server Port Numbers
You can modify the port or secure port number of your user directory server using the Directory Server console or by changing the value of the nsslapd-port attribute under the cn=config entry.
If you want to modify the port or secure port for a Sun ONE Directory Server that contains the Sun ONE configuration information (o=NetscapeRoot subtree), you may do so through Directory Server console.
If you change the configuration directory or user directory port or secure port numbers, you should be aware of the following repercussions:
- You need to change the configuration or user directory port or secure port number configured for the Administration Server. See "Network Settings" in Chapter 7 of the Sun ONE Server Console Server Management Guide.
- If you have other Sun ONE Servers installed that point to the configuration or user directory, you need to update those servers to point to the new port number.
Use the following procedure to modify the port or secure port on which the directory server listens for incoming LDAP requests. To modify the ports for DSML requests, see "Configuring DSML".
- On the top-level Configuration tab of the Directory Server console, select the root node with the server name, and then select the Network tab in the right-hand panel.
The tab displays the server's current port settings for the LDAP protocol.
- Enter the port number you want the server to use for non-SSL communications in the Port field. The default value is 389.
- If you have activated SSL on this server as described in Chapter 11 "Implementing Security", you may allow connections on a secure port:
- Select the option to use both secure and non secure ports.
- Enter the port number you want the server to use for SSL communications in the Secure Port field. The default value is 636.
The encrypted port number that you specify must not be the same port number as you are using for normal LDAP communications.
- Click Save and then restart the server.
See "Starting and Stopping the Directory Server" for information.
Setting Global Read-Only Mode
Each suffix in your directory may be placed in read-only mode independently and may return a specific referral if one is defined. Directory Server also provides a global read-only mode that will apply to all suffixes and may return a global referral when one is defined.
The global read-only mode is designed to allow administrators to prevent modifications to the directory contents while performing tasks such as reindexing the suffixes. For this reason, global read-only mode does not apply to the following configuration branches:
- cn=config
- cn=monitor
- cn=schema
These branches should be protected at all times by Access Control Instructions (ACIs) against modifications by non-administrative users, regardless of the read-only setting (see Chapter 6 "Managing Access Control"). Global read-only mode will prevent update operations on all other suffixes in the directory, including update operations initiated by the Directory Manager.
Read-only mode will also interrupt replication on a suffix if it is enabled. A master replica will no longer have any changes to replicate, although it will continue to replicate any changes that were made before read-only mode was enabled. A consumer replica will not receive updates until read-only mode is disabled. A master in a multi-master replication scenario will neither have any changes to replicate nor be able to receive updates from the other masters.
To enable or disable the global read-only mode:
- On the top-level Configuration tab of the Directory Server console, select the root node in the configuration tree, then select the Settings tab in the right panel.
- Select or deselect the "Server is read only" checkbox.
- Click Save. The change will take effect immediately.
For information on placing an individual suffix in read-only mode, refer to "Setting Suffix Read-Only Mode".
Tracking Modifications to Directory Entries
You can configure the server to maintain special attributes for newly created or modified entries:
- creatorsName—The distinguished name of the person who initially created the entry.
- createTimestamp—The timestamp for when the entry was created in GMT (Greenwich Mean Time) format.
- modifiersName—The distinguished name of the person who last modified the entry.
- modifyTimestamp—The timestamp for when the entry was last modified in GMT format.
Note When a client application to create or modify entries in a chained suffix, the creatorsName and modifiersName attributes do not reflect the real creator or modifier of the entries. These attributes contain the name of the chaining proxy needed to bind to the remote server. For information on proxy authorization, refer to "Creating a Proxy Identity".
When tracking modification times of replicated suffixes, the name and timestamp attributes are replicated as normal attributes. As a result, these attributes reflect the time of the original modification to the entry on the master server, not the time that the entry was replicated to a consumer.
To enable the Directory Server to track this information:
- On the top-level Configuration tab of the Directory Server console, select the root node in the configuration tree, then select the Settings tab in the right-hand panel.
- Select the "Track entry modification times" checkbox.
The server will add the creatorsName, createTimestamp, modifiersName, and modifyTimestamp attributes to every newly created or modified entry. Existing entries will not contain the creation attributes.
- Click Save and then restart the server.
See "Starting and Stopping the Directory Server" for more information.
Verifying Plug-In Signatures
The verification of plug-in signatures is a new feature of Directory Server 5.2. Plug-ins provided with Directory Server each have a digital signature which may be verified by the server at startup. By default, the server will verify plug-in signatures, but it will load every plug-in regardless of the presence or validity of a signature.
Verifying signatures has the following advantages:
- A signature on a plug-in provided with Directory Server indicates that it has been rigorously tested and is officially supported.
- Using a checksum of the plug-in binary itself, the signature verification can detect whether the plug-in has been tampered with. Therefore the signature protects sensitive code that runs in the server itself.
- You may configure your server to load only the signed plug-ins, which may help detect problems with unsigned and unsupported plug-ins.
Configuring the Verification of Plug-In Signatures
- On the top-level Configuration tab of the Directory Server console, select the Plugins node in the configuration tree. The current signature verification policy is displayed in the right-hand panel.
- Select one of the following options:
- Do not verify plug-in signatures - All plug-ins defined in the server configuration will be loaded regardless of their signature. No warnings or errors will be shown because of a plug-in signature.
- Flag plug-ins with invalid signatures - All plug-ins defined in the server configuration will be loaded, but the server will verify the signature of each one. If a plug-in binary is altered in any way, the signature will no longer be valid, and the server will display a warning message on startup and in the error log. Plug-ins without signatures will also be flagged.
This is the recommended option if you have custom, unsigned plug-ins. Your plug-ins will be loaded, but you will still be able to view the status of all signed plug-ins.
- Reject plug-ins with invalid signatures - The server will verify the signature of all plug-ins defined in the configuration and will only load plug-ins with valid signatures. The server will display a warning message on startup and in the error log that indicates which plug-ins have an invalid signature or no signature.
This is the most secure option, however, you will not be able to load custom, unsigned plug-ins.
- Click Save, and then restart the directory server as described in "Starting and Stopping the Directory Server".
Viewing the Status of a Plug-In
- On the top-level Configuration tab of the Directory Server console, expand the Plugins node in the configuration tree, and select the plug-in you wish to verify. The current configuration of the plug-in is displayed in the right-hand panel.
- The "Signature state" field shows the signature verification status of the plug-in with one of the following values:
- Unknown - This signature state occurs in all plug-ins when the server is configured to not verify plug-in signatures. The following states are visible only if you verify plug-in signatures.
- Valid signature - The plug-in configuration provides a signature that matches the checksum of the plug-in binary. This plug-in is officially supported. The following states are visible only if you flag but not reject invalid signatures.
- Invalid signature - The plug-in configuration contains a signature which does not match the checksum of the plug-in binary. This state indicates that the plug-in may have been tampered with.
- No signature - The plug-in configuration did not provide a signature for the server to verify.
Configuring DSML
In addition to processing requests in the Lightweight Directory Access Protocol (LDAP), Sun ONE Directory Server 5.2 now also responds to requests sent in the Directory Service Markup Language version 2 (DSMLv2). DSML is another way for a client to encode directory operations, but the server processes DSML as any other request, with all of the same access control and security features. In fact, DSML processing allows many other types of clients to access your directory contents.
Directory Server supports the use of DSMLv2 over the Hypertext Transfer Protocol (HTTP/1.1) and uses the Simple Object Access Protocol (SOAP) version 1.1 as a programming protocol to transport the DSML content. For more information about these protocols and examples of DSML requests, see Appendix A, "Accessing Data using DSMLv2 over HTTP/SOAP" in the Sun ONE Directory Server Deployment Guide.
Enabling DSML Requests
Because LDAP is the standard protocol for accessing a directory, DSML requests are not enabled by default after installing Directory Server. If you want your server to respond to DSML requests sent over HTTP/SOAP, you must explicitly enable this feature.
To enable DSML requests on your server through the console:
- On the top-level Configuration tab of the Directory Server console, select the root node in the configuration tree, and select the Network tab in the right-hand panel.
- Select the Enable DSML checkbox and choose one of the following security options. The secure port options are only available if you have activated SSL, as described in Chapter 11 "Implementing Security."
- Only non-secure port - Only DSML requests over unencrypted HTTP will be accepted on the non-secure port.
- Only secure port - Only DSML requests over HTTPS will be accepted on the secure port.
- Both secure and non-secure ports - Both ports will be active and clients may choose either one.
- Then edit any of the following fields:
- Port - The HTTP port for receiving DSML requests.
- Encrypted Port - The HTTPS port using SSL to received encrypted DSML requests.
- Relative URL - A relative URL that, when appended to the host and port, determines the full URL that clients must use to send DSML requests.
By default, the server will process requests sent to the following URL:
- Click Save and you will be reminded that you must restart the server to begin responding to DSML requests.
To enable DSML requests through the command line:
- Perform the following ldapmodify command to enable the DSML front-end plug-in and modify its settings. Modifying the ds-hdsml-port, ds-hdsml-secureport, and ds-hdsml-rooturl attributes is optional:
dn: cn=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
-
replace: ds-hdsml-port
ds-hdsml-port: DSMLport
-
add: ds-hdsml-secureport
ds-hdsml-port: secureDSMLport
-
replace: ds-hdsml-rooturl
ds-hdsml-root: relativeURL
-
^D
According to the parameters and attribute values you defined, DSML clients may use the following URLs to send requests to this server:
- When the DSML front-end plug-in has been modified, you must restart the server for the changes to take effect. However, before you restart the server, you may wish to configure the security and identity mappings for DSML authentication as described in the following sections.
Configuring DSML Security
In addition to the secure port setting described in the previous section, you may configure the level of security that is required to accept DSML requests. The ds-hdsml-clientauthmethod attribute of DSML front-end plug-in determines what authentication methods are required of the client. This attribute may have the following values:
- httpBasicOnly - The server will use the contents of the HTTP Authorization header to find a user name that can be mapped to an entry in the directory. This process and its configuration are further described in "DSML Identity Mapping". With this setting, DSML requests to a secure HTTPS port will be encrypted through SSL but not use client certification.
- clientCertOnly - The server will use credentials from the client certificate to identify the client. With this value, all DSML clients must use the secure HTTPS port to send DSML requests and provide a certificate. The server will check that the client certificate matches an entry in the directory. See Chapter 11 "Implementing Security" for more information about client certificates.
- clientCertFirst - The server will attempt to authenticate clients first with a client certificate if one is provided. Otherwise, the server will authenticate clients using the contents of the Authorization header.
If no certificate and no Authorization header is provided in the HTTP request, the server will perform that DSML request with anonymous binding. Anonymous binding is also used in the following cases:
- The client provides a valid Authorization header but no certificate when clientCertOnly is specified.
- The client provides a valid certificate but no Authorization header when httpBasicOnly is specified.
Regardless of the ds-hdsml-clientauthmethod attribute value, if a certificate is provided but it cannot be matched to an entry, or if the HTTP Authorization header is specified but cannot be mapped to a user entry, the DSML request will be rejected with error message 403: "Forbidden."
To set the DSML security requirements through the console:
- On the top-level Configuration tab of the Directory Server console, select the root node in the configuration tree, and select the Encryption tab in the right-hand panel.
You must have already configured and enabled SSL as described in Chapter 11 "Implementing Security."
- Select one of the choices for the drop-down menu in the DSML Client Authentication field.
- Click Save and then restart the server to enforce this new security setting.
To set the DSML security requirements through the command line:
- Run the following ldapmodify command to edit the attribute of the DSML front-end plug-in:
dn: cn=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config
changetype: modify
replace: ds-hdsml-clientauthmethod
ds-hdsml-clientauthmethod: httpBasicOnly or
clientCertOnly or clientCertFirst
^D
- When the DSML front-end plug-in has been modified, you will need to restart the server to enforce this new security setting.
DSML Identity Mapping
When performing basic authentication without a certificate, Directory Server uses a mechanism called identity mapping to determine the bind DN to use when accepting DSML requests. This mechanism extracts information from the Authorization header of the HTTP request to determine the identity to use for binding. See "Identity Mapping" for a complete description of this mechanism.
The default identity mapping for DSML-over-HTTP is given by the following entry in your server configuration:
objectclass: top
objectclass: nsContainer
objectclass: dsIdentityMapping
cn: default
dssearchbasedn: ou=People,userRoot
dssearchfilter: (uid=${Authorization})This mapping searches the ou=People,userRoot subtree for an entry whose uid attribute matches the user name given in the Authorization header. The userRoot is the suffix you defined when installing the directory, for example dc=example,dc=com.
Within the mapping entry attributes, you may use place-holders of the format ${header} where header is the name of an HTTP header. The most common headers used in DSML mappings are:
- ${Authorization} - This string is replaced with the user name contained in an HTTP Authorization header. An authorization header contains both a username and its password, but only the user name is substituted in this place-holder.
- ${From} - This string is replaced with the email address that may be contained in an HTTP From header.
- ${host} - This string is replaced with the hostname and port number in the URL of the DSML request, which are those of the server itself.
To have DSML requests perform a different identity mapping, define a new identity mapping for HTTP headers:
- Edit the default DSML-over-HTTP identity mapping or create custom mappings for this protocol. See "Identity Mapping" for the definition of the attributes in an identity mapping entry. These mapping entries must be located below the following entry: cn=HTTP-BASIC, cn=identity mapping, cn=config.
You may create new mapping entry in one of two ways:
- Use the top-level Directory tab of the Directory Server console to create a new entry with the appropriate object classes, as described in "Managing Entries Using the Console".
- Use the ldapmodify tool to add this entry from the command line, as described in "Adding Entries Using ldapmodify".
- Restart the Directory Server for your new mappings to take effect.
Custom mappings are evaluated first, and if no custom mapping is successful, then the default mapping is evaluated. If all mappings fail to determine the bind DN for the DSML request, the DSML request will be forbidden and rejected (error 403).