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:
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:
The DSML gateway is implemented as a Java application, which offers several benefits:
To use the DSML gateway application as part of the Directory Server deployment:
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.
The DSML gateway is built from source; pre-built packages are not yet available.
In order to build the DSML gateway, you need the following:
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.ldapjdk.jar is usually provided with your OS distro, but it is also available from jpackage.org.activation.jar is usually provided with your OS distro, but the Sun or the GNU Classpathx versions are also acceptable.commons-codec.jar is usually provided with your OS distro, but it can also be downloaded from apache.org.git clone git://git.fedorahosted.org/cgit/389/dsmlgw.git/
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:
| Option | Default | Description |
|---|---|---|
| globaldist.dir | /usr/share/java | Common shared jar directory - some distros put all jars in this directory |
| ldapdist.dir | /usr/share/java | Directory containing ldapjdk.jar |
| axisdist.dir | /usr/share/java/axis | Home directory for all Axis files |
| axis.lib.dir | /usr/share/java/axis | Directory containing axis.jar, saaj.jar, jaxrpc.jar |
| axis.jar | ${axis.lib.dir}/axis.jar | Explicitly specify path and filename of axis jar to use |
| saaj.jar | ${axis.lib.dir}/saaj.jar | Explicitly specify path and filename of saaj jar to use |
| jaxrpc.jar | ${axis.lib.dir}/jaxrpc.jar | Explicitly specify path and filename of jaxrpc jar to use |
| ldapjdk.jar | ${ldapdist.dir}/ldapjdk.jar | Explicitly specify path and filename of ldapjdk jar to use |
| activation.jar | ${globaldist.dir}/activation.jar | Explicitly specify path and filename of JAF jar to use |
| codec.jar | ${globaldist.dir}/commons-codec.jar | Explicitly specify path and filename of codec jar to use |
| mail.jar | ${globaldist.dir}/mail.jar | Not needed at build time, but required by Axis and DSMLGW service at runtime |
| build.dir | built | Where to write .class files and other files generated during build |
| dist.dir | dist | Where to write jar and war files and directories |
| pkg.dir | ${dist.dir}/pkg | Where to write the .tar.gz files and packaging directories |
| pkg.type | prefix | Type of package to create - prefix, fhs, or fhsopt |
| tomcat.home | no default value | The CATALINA_HOME or tomcat home directory to use at runtime - must be specified if packaging |
| tomcat.cmd | ${tomcat.home}/bin/startup.sh | Command to use at runtime to startup Tomcat - must be specified if packaging |
These are the targets you can provide to ant, depending on the desired build type:
dsmlgw.jar file.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..tar.gz file. The layout is based on the pkg.type specified:
/opt/dirsrv./usr/share/dirsrv/dsmlgw./opt layout (/opt/dirsrv, /etc/opt/dirsrv, and /var/opt/dirsrv) .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,”.
| Option | Description |
| -r | Optional. Rewrites the configuration. By default, setup-ds-dsmlgw will not overwrite any existing config. |
These scripts are provided with the full package distribution (i.e. not jar or war only):
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.
| Parameter | Description | Default Setting |
|---|---|---|
| ServerHost | Host name for its peer Directory Server. | localhost |
| ServerPort | Port number for its peer Directory Server. | 389 |
| BindDN | Bind DN. | anonymous |
| BindPW | Bind password. | (empty) |
| MinimumConnectionPool | Minimum connections the DSML gateway will make to the Directory Server for operations. | 3 |
| MaximumConnectionPool | Maximum connections the DSML gateway will make to the Directory Server for operations. | 15 |
| MinimumLoginPool | Minimum connections the DSML gateway will make to the Directory Server for user authentication. | 1 |
| MaximumLoginPool | Maximum connections the DSML gateway will make to the Directory Server for user authentication. | 2 |
| UseAuth | true|false expression. If the expression is true, it requires the user to authenticate in order to bind; if it is false, it accepts the user ID and password offered. |
false |
dsmlgw.cfg file in the /etc/dirsrv/dsmlgw directory.ServerHost attribute to reflect the server you wish to use. For example:
ServerHost=ldap.example.com/usr/sbin/restart-ds-dsmlgwThe 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.
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.
dsmlgw.cfg file in the /etc/dirsrv/dsmlgw directory.BindDN=uid=fred,ou=people,dc=example,dc=comBindPW 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=password/usr/sbin/restart-ds-dsmlgwThe 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`
Sample DSML data files are provided with the full package distribution in the share/dirsrv/dsmlgw/data directory.
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).