From Fedora Directory Server

About the Directory Server DSML Gateway

Fedora Directory Server can work with a Java gateway application based on Directory Service Markup Language (DSML) version 2.0.

Directory Service Markup Language (DSML) is an open, extensible format that allows directories to exchange information across Directory Server types. The flexibility of DSML enables clients to interact with customers, partners, and remote locations, regardless of the type of directory service used.

DSML version 2.0, the basis for Directory Server's DSML gateway, allows directory contents to be accessed, modified, and controlled through XML (eXtensible Markup Language). Delivering directory information in XML allows customized markup languages to be created for different uses by extending the XML schema.

As a web services protocol, DSML closely mirrors Lightweight Directory Access Protocol (LDAP). DSML is designed to allow arbitrary web services clients to access directory services using the client's native protocols, so that content stored in a directory service can be easily accessed by standard web service applications and development tools. DSML is useful in web applications because it can access directories when a firewall would normally screen out an LDAP request.

The Directory Server DSML gateway uses SOAP as a services layer. Simple Object Access Protocol (SOAP) is an XML-based protocol that can access and relay information in a distributed database over regular HTTP/HTTPS. The DSML gateway uses SOAP to bind to a Directory Server over the web so LDAP directories, such as Directory Server, can be effectively rendered in XML.

Links

• Design
• Building
• License - GPLv2 with GNU Classpathx exception

DSML Authentication Mapping

The DSML authentication mechanism is native to HTTP/SOAP, but the gateway interacts cleanly with LDAP. Client credentials sent through either standard HTTP client authentication or SSL connections are mapped to a distinguished name (DN), and then proceed as if an LDAP client had bound with that DN.

The gateway DN mapping works essentially as follows:

1. The client's authentication credentials are obtained from the servlet container (username/password from HTTP/SOAP or client certification DN from SSL).
2. A mapping function is applied to yield a target DN in the host Directory Server's directory information tree.
3. The gateway attempts to verify the presented credentials by binding as the mapped DN against the host Directory Server.
4. If the gateway binds successfully, the session is marked as authenticated.
5. For authenticated sessions, LDAP proxy authorization controls are sent with every operation to the Directory Server. This ensures that operations are done in the security context of the presented credentials (as mapped).

NOTE Since the bind DN and password for a user in the DSML gateway is the same bind DN and password used to access the Directory Server, proxy authorization is the same proxy right that is determined by access control rules. This is an extremely powerful right, and there is not way to limit as whom a user with proxy rights may bind. Proxy rights should be limited to privileged users, such as root.

Response times for a gateway are slightly higher compared to a native Directory Server session because each request must be forwarded through the gateway. Overall, though, implementation as a gateway, as opposed to natively within the Directory Server, offers two major benefits for how the gateway can be integrated into your broader network:

• Improved throughput since XML-parsing, which is CPU-intensive, can be done on a different CPU than the server uses.
• Simpler integration with emerging web services protocols can be added without affecting Directory Server performance.

The DSML gateway is implemented as a Java application, which offers several benefits:

• Execution in a wide range of operating system and hardware environments, including those that do not support Directory Server.
• Leverage of existing Java web services implementations.
• Deployment within almost any execution environment. Installation is easy even without experience using Java web services.

Using DSML Gateway with Directory Server

To use the DSML gateway application as part of the Directory Server deployment:

1. Make sure the machine or application that uses the gateway must be SOAP compatible since the DSML gateway natively runs over HTTP/SOAP.
2. Install Directory Server, then build and install the DSML gateway on the same machine.
3. Directory Server has other web applications — the Directory Server Gateway, Admin Express, Directory Express, and Org Chart — along with the DSML gateway. The DSML gateway can run simultaneously with the other web applications; however, it does not interact with them.
4. Activate the the DSML gateway. The DSML gateway is not running by default and has to be enabled, as covered in Activating the Gateway.
5. Modify the configuration files, if necessary.
   
   

During installation and setup, the files relevant to the DSML gateway are placed in /usr/share/dirsrv/dsmlgw. The configuration information is stored in /etc/dirsrv/dsmlgw/dsmlgw.cfg. You can modify desired settings in the file and customize the application to suit an organization.

The gateway connects to the default port (389) of Directory Server. See "Editing the DSML Gateway Configuration" for detailed information on configuration parameters. The default settings (created during setup) are usually sufficient.

Building the DSML Gateway

The DSML gateway is built from source; pre-built packages are not yet available.

Build Requirements

In order to build the DSML gateway, you need the following:

• Java 1.5 or later
• Ant 1.6 or later
• Axis 1.4 (The DSML gateway code will not currently work with Axis2). axis.jar, saaj.jar, and jaxrpc.jar are usually provided with your OS distro, or with binary distributions of Axis, but they can be built from the Axis 1.4 source code if necessary.
• Mozilla LDAP Java SDK 4.17 or later. ldapjdk.jar is usually provided with your OS distro, but it is also available from jpackage.org.
• Java Activation Framework 1.0 or later. activation.jar is usually provided with your OS distro, but the Sun or the GNU Classpathx versions are also acceptable.
• Apache Commons Codec. commons-codec.jar is usually provided with your OS distro, but it can also be downloaded from apache.org.

NOTE JavaMail is required at runtime and at build time if you are creating a redistributable package. You can use either the Sun JavaMail or the GNU Classpathx JavaMail. This is usually available from your OS distro

Getting the Source Code

Check out the source code from CVS. The CVS user and root are :pserver:anonymous@cvs.fedoraproject.org:/cvs/dirsec, and the gateway module is dsmlgw.

cvs -d :pserver:anonymous@cvs.fedoraproject.org:/cvs/dirsec co dsmlgw

Setting the PATH

Make sure the correct version of Java and Ant are in your PATH:

java -version
ant -version

Build Properties

Some of the default values are in the build.properties file. There are also build.properties files for each of the pkg.type used by the makepkg build target.

Other build properties are specified on the ant command. For example:

ant -Dbuild.dir=/path/to/build -Ddist.dir=/path/to/dist .... [targets]

The build takes many different options depending on how you want to build and what is provided by your platform:

Build Targets

These are the targets you can provide to ant, depending on the desired build type:

• dist (default). This just builds the dsmlgw.jar file.
• makewar. This builds the dsmlgw.jar file, bundles Axis and the other jar files, and creates an Axis web application with DSML gateway that can be deployed into Tomcat or other compliant servlet container.
• makepkg. This creates a full redistributable package, including the shell scripts and config files, in a .tar.gz file. The layout is based on the pkg.type specified:
  • prefix puts all files and directories under a given prefix; the default directory is /opt/dirsrv.
  • fhs puts all files and directories under their FHS locations; the main directory is under /usr/share/dirsrv/dsmlgw.
  • fhsopt uses the FHS /opt layout (/opt/dirsrv, /etc/opt/dirsrv, and /var/opt/dirsrv) .

DSML Gateway Tools

The DSML gateway is controlled through a single command-line utility, /usr/sbin/setup-ds-dsmlgw. The setup-ds-dsmlgw tool has one option, listed in "Table: Gateway Command-Line Options,".

Scripts

These scripts are provided with the full package distribution (i.e. not jar or war only):

• sbin/setup-ds-dsmlgw - sets up the Tomcat app environment and the DSMLGW configuration
• sbin/start-ds-dsmlgw - start up tomcat + axis + dsmlgw service
• sbin/stop-ds-dsmlgw - shutdown
• sbin/restart-ds-dsmlgw - restart
• bin/dsmlgw-search - a very simple script to use to test DSMLv2 searches via the DSMLGW
• bin/dsml2ldif - converts DSMLv1 data files to LDIF format
• bin/ldif2dsml - converts LDIF files to DSMLv1 data files

Editing the DSML Gateway Configuration

The gateway is configured by running setup-ds-dsmlgw.

The configuration settings are stored in a Java properties text file, /etc/dirsrv/dsmlgw/dsmlgw.cfg.

"Table: Configuration Parameters" lists the DSML gateway configuration file parameters.

Changing the Host

1. Open the dsmlgw.cfg file in the /etc/dirsrv/dsmlgw directory.
2. Edit the value of the ServerHost attribute to reflect the server you wish to use. For example:
   ServerHost=localhost=> ServerHost=ldap.example.com
3. Restart the gateway /usr/sbin/restart-ds-dsmlgw

Changing the Bind DN and Password

The default setting allows read-only access since the default bind DN is anonymous. Changing the bind DN to a DN that has read-write permissions will allow read-write access for the directory.

NOTE Everyone can read from the DSML gateway in its default configuration. To restrict access further, set the UseAuth value to true.

If the UseAuth attribute value is set to true, the gateway requires standard HTTP headers, consisting of the user's full distinguished name and password. Any operations done over the gateway will be done with proxy authorization and will require a distinguished name with proxy rights. For more about proxy authorization, see the Directory Server Administrator's Guide.

1. Open the dsmlgw.cfg file in the /etc/dirsrv/dsmlgw directory.
2. Edit the value of the BindDN attribute to reflect the user for whom you are allowing access. For example:
   BindDN=anonymous=> BindDN=uid=fred,ou=people,dc=example,dc=com
3. Edit the value of the BindPW attribute; for anonymous access, this parameter is usually blank. The new password must be the same as the password for authentication to the directory to keep access controls functioning. For example:
   BindPW= --> BindPW=password
4. Restart the gateway /usr/sbin/restart-ds-dsmlgw

Example Configuration

The following is an example gateway configuration for example.com Corporation. Parameters not listed in the file are set to the default value.

# DSMLGW configuration for example.com Corporation
ServerHost=ldap.example.com
ServerPort=389
BindDN=uid=fred,ou=people,dc=example,dc=com
BindPW=password
UseAuth=false

DSML Samples

Sample DSML data files are provided with the full package distribution in the share/dirsrv/dsmlgw/data directory.

Debugging

In the full package distribution, the log files are written to the directory share/dirsrv/dsmlgw/webapps/logs which will be symlinked to your "real" log file directory.

For Axis debugging, edit the file share/dirsrv/dsmlgw/webapps/axis/WEB-INF/log4j.properties. This uses standard Log4j properties. The file axis.log (in the log directory above) will contain Axis specific log messages.

For DSMLGW debugging, edit the file share/dirsrv/dsmlgw/webapps/axis/WEB-INF/logging.properties. The log file name is dsmlgw.<date>.log (in the log directory above).

See Also

• Back to the overview
• How to install and setup the web apps
• Org Chart
• Directory Server Gateway
• Admin Express
• Directory Express
• Help with basic HTML editing