Configuring DSML

In addition to processing requests in the Lightweight Directory Access Protocol (LDAP), Directory Server 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. The server processes DSML as any other request, with all of the same access control and security features. 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 for examples of DSML requests, see Chapter 13, Directory Server DSMLv2, in Oracle Directory Server Enterprise Edition Reference.

This section covers the following topics:

• To Enable the DSML-over-HTTP Service

• To Disable the DSML-over-HTTP Service

• DSML Identity Mapping

To Enable the DSML-over-HTTP Service

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. Set the DSML mode to on.

   $ dsconf set-server-prop -h host -p port dsml-enabled:on

2. Set the secure DSML port.

   $ dsconf set-server-prop -h host -p port dsml-secure-port:port

3. Set the non—secure DSML port.

   $ dsconf set-server-prop -h host -p port dsml-port:port

   By default, this port is set to disabled

4. Restart the server.

   $ dsadm restart instance-path

Next Steps

According to the parameters and attribute values you defined, DSML clients may use the following URLs to send requests to this server:

http://host:DSML-port/relative-URL

https://host:secure-DSML-port/relative-URL

To Disable the DSML-over-HTTP Service

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. Set the DSML mode to off.

   $ dsconf set-server-prop -h host -p port dsml-enabled:off

2. Set the secure DSML port to disabled.

   $ dsconf set-server-prop -h host -p port dsml-secure-port:disabled

3. Restart the server.

   $ dsasm restart instance-path

To Configure DSML Security

You can configure the level of security that is required to accept DSML requests. To do this, you must configure DSML client authentication.

• Set the DSML client authentication mode.

  $ dsconf set-server-prop -h host -p port dsml-client-auth-mode:dsml-mode

  By default the dsml-client-auth-mode property is set to client-cert-first.

  dsml-mode can be one of:

  • http-basic-only - This is the default value. The server uses 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 encrypted through SSL but do not use client certification. This is described in DSML Identity Mapping.

  • client-cert-only - The server uses 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 checks that the client certificate matches an entry in the directory. See Chapter 5, Directory Server Security for more information.

  • client-cert-first - 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 performs the 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 client-cert-only is specified.

  • The client provides a valid certificate but no Authorization header when http-basic-only is specified.

  Regardless of the client authentication method, 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 is rejected with error message 403: “Forbidden”.

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.

The default identity mapping for DSML/HTTP is given by the following entry in your server configuration.

dn: cn=default,cn=HTTP-BASIC,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
cn: default
dsSearchBaseDN: ou=people
dsSearchFilter: (uid=${Authorization})

This configuration indicates that the server should use the HTTP user ID as the uid value for a DN stored in a Directory Server suffix. For example, if the HTTP user is bjensen, the server tries to execute the bind using the DN uid=bjensen,ou=people.

For the mapping to work properly you must therefore complete the value of dsSearchBaseDN. For example, you can change the value of dsSearchBaseDN to ou=people,dc=example,dc=com. Then if the HTTP user is bjensen, the server tries to execute the bind using the DN uid=bjensen,ou=people,dc=example,dc=com.

dn: cn=default,cn=HTTP-BASIC,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
cn: default
dsSearchBaseDN: ou=people,dc=example,dc=com
dsSearchFilter: (uid=${Authorization})

Within the mapping entry attribute dsSearchFilter, you can use placeholders of the format ${header} where header is the name of an HTTP header.

The following are the most common headers used in DSML mappings.

${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 placeholder.

${From}

This string is replaced with the email address that might 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.

To have DSML requests perform a different kind of identity mapping, define a new identity mapping for HTTP headers.

To Define a New Identity Mapping for HTTP Headers

1. Edit the default DSML-over-HTTP identity mapping or create custom mappings for this protocol.

   The mapping entries must be located below the entry cn=HTTP-BASIC,cn=identity mapping,cn=config.

   Use the ldapmodify command to add this entry from the command line, as described in Adding Entries Using ldapmodify.

2. Restart Directory Server for your new mappings to take effect.

   Custom mappings are evaluated first. If no custom mapping is successful, the default mapping is evaluated. If all mappings fail to determine the bind DN for the DSML request, the DSML request is forbidden and rejected (error 403).