LDAP Publisher/LDAP Search Publisher

LDAP Naming

The recommended method of choosing a naming suffix is the one described in RFC2247 that maps a DNS domain to a DN. If my DNS domain is bigcorp.com it will map to the DN "dc=bigcorp,dc=com". The top node in my LDAP directory will then be "dc=bigcorp,dc=com". For more information and to understand LDAP naming, we recommend the book Understanding and Deploying LDAP Directory Services.

The dc component support is mandated by all of the X.509 RFCs now. For example, if I have this directory:

dc=bigcorp,dc=com
|
+-dc=fi
|
|
+-dc=se
|
+-cn=Mike Jackson 

The most understandable method is taking the subject name in forward order, like: cn=Mike Jackson,dc=se,dc=bigcorp,dc=com

If the DN is ordered like this it should be published to the correct object in the tree.

If the DN is ordered reverse, like: dc=bigcorp,dc=com,dc=se,cn=Mike Jackson EJBCA will reorder it incorrectly to forward order, so the publishing will be wrong.

Thus, use forward order like this: 'cn=Mike Jackson,dc=se,dc=bigcorp,dc=com' if using the dc model or 'cn=Mike Jackson,o=bigcorp,c=se' if using the o,c model.

Making unique LDAP DNs is the next challenge. If you are in a small organization having the CN will probably work fine, but in a larger organization there are probably several people with the same name. Somehow the names must be made unique, and one way is to introduce numbers, initials etc in the CN. Another way that we recommend is to use uid in the LDAP DN instead. LDAP DNs will then look like "uid=tomas,dc=bigcorp,dc=com". Uid is the username, normally used for login etc, and you probably already have some procedure to create unique usernames already.

LDAP Basics

If you are not used to X.500 style naming, the LDAP structure of branches and leaf nodes may seem unusual. You can't just drop an object anywhere you like; You need to create the framework to support it. Sort of like if you wanted to put entries in /etc/hosts if the directory /etc did not exist.

First you mkdir /etc, then you create the file. Then you start putting things in the file. The difference with LDAP and x.500 is that instead of paths separate by slashes, you have paths separated by commas and '=' signs.

For example, if you want to make an object "cn=ldaphost,ou=hosts,dc=yourdom,dc=com", you first have to make sure "dc=yourdom,dc=com" exists. Then make sure "ou=hosts,dc=yourdom,dc=com" exists. THEN you can try "cn=ldaphost,ou=hosts,dc=yourdom,dc=com"

EJBCA does not create branches in LDAP. You have to put them there with other means before you start publishing.

Using LDAP

In Firefox you can for example enter a URL like: ldap://ip-address-of-ldap-server:389/cn=Tomas Gustavsson,dc=se,dc=bigcorp,dc=com and it will fetch an address book entry with the information about the user, including the certificate.

The LDAP url format is described in RFC2255.

To use LDAP top fetch user certificates and use them for encrypting email there seems to be a requirement to use SSL connection to the LDAP server (Account Options > Compositions & Addressing > Edit directories > Edit > Use Secure Connection), see also below how to configure OpenLDAP for SSL.

When fetching certificates from LDAP with Firefox, for example with URL: ldap://ldap-server-host/dc=bigcorp,dc=com??sub?(cn=MyName)?(objectclass=*), the CA certificate must be installed in the Windows truststore, not only in Firefox's, to enable a checkbox at the fetched certificate.

To use SSL against an LDAP server with MS Outlook you must make sure the CN in the LDAP servers certificate is the same as the hostname. An example of adding a user for the LDAP server with the CLI interface is:

bin/ejbca.sh ra addendentity ldap password "C=SE,O=Foo,CN=ldap.foo.se" MyCA 1 PEM SERVER

where ldap.foo.se is the hostname of the LDAP server that Outlook should use.

The CA certificate must also be imported into Windows properly.

Configure LDAP Publishers

A Publisher is a session bean that implements the IPublishSession interface and is used to store certificates and CRLs for entities. EJBCA have support for endless number of publishers simply by defining publishers in the Admin GUI. The user of EJBCA can implement own publishers, but EJBCA already comes with a publisher for LDAP.

EJBCA uses a notion of base DN to publish to different LDAP structures. The DN used in the certificate can be different from the LDAP structure.

Configuring EJBCA

To configure the publisher for LDAP:

  1. Select Admin GUI > Edit Publishers.

  2. Add a new publisher by specifying a name, edit the publisher and specify the necessary fields.

The following lists generic parameters to the LDAP Publisher:

Field

Description

Hostnames

';' separated list of the hosts where the LDAP servers are located. E.g. "ldap.company.com" or "ldap1.company.com;ldap2.company.com". Only the first available of the listed hosts will be used.

Port

Port on which the LDAP server listens, default non-SSL is 389. Available choices:
Plaintext Connection: unencrypted connection, the easiest to get started with, and the mosts robust if network is secure.
STARTTLS Extension: this gives the server and client a chance to negotiate a TLS (encrypted) connection if the server supports encrypted connections. It starts with a plaintext connection, and upgrades to a TLS connection using the same port as plaintext connection. Requires configuration both on the server (TLS server key and certificate) and on the client (CA certificate in truststore).
TLS Connection: this always uses an encrypted TLS connection and fails if it is not available. Requires TLS configuration both on the server (TLS server key and certificate) and on the client (CA certificate in truststore).

Login DN

The DN of a user on the LDAP server with permissions to add and update entities.

Login Password

Password for the user above.

Connection timeout

Number of milliseconds a server has to respond before it is considered unavailable and the next server in the list of hostnames (if any) is used instead. This timeout is used to probe LDAP servers, to create connections, to bind and to disconnect.

Read timeout

Number of milliseconds a server has to complete a LDAP search or read operation before it times out and fails.

Store timeout

Number of milliseconds a server has to complete a LDAP store operation before it times out and fails. This can take a little longer if you store very large CRLs in LDAP.

Create Nonexisting Users

Defines if an LDAP object should be created by EJBCA if it is no existing object when EJBCA publishes the certificate.

Modify Existing Users

Defines if attributes (such as email) in existing LDAP objects are replaced with new values and/or added when an entry is updated with a new certificate. If this option is not activated, existing users will not be touched at all, even not updated with a new certificate.

Overwrite Existing Attributes when Modify Existing Users is set to true

Whether to change values of attributes when they already exist.

Add Nonexisting Attributes when Modify Existing Users is set to true

Whether to add attributes when they do not already exist.

Add multiple certificates per user

Defines if we should use multiple certificate entries for each user or only one. Default only one certificate is added to a user entry in LDAP and if the user gets a new certificate the old one is deleted and replaced with the new one. If this checkbox is checked certificates are instead appended in LDAP so each user can have multiple certificate entries in LDAP. Make sure your applications can handle this before enabling this option. Revoking a user will remove all certificates entries for the user.

Remove certificates when revoked

If selected, causes the publisher to remove a certificate from LDAP when the certificate is revoked or suspended.

Remove ldap user when certificate revoked

If selected, causes the publisher to remove the whole LDAP user entry when a certificate is revoked or suspended.

Set userPassword attribute

Specifies if the LDAP publisher should set the userPassword attribute in the LDAP object. If a user entry with a non-null password is published, and this checkbox is checked, the userPassword attribute will be populated with the user's password.

User Object Class

The objectclass for the LDAP entries for users, where user certificates are published. The entry is hierarchical separated by ';' to build a structure like: objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson This objectclass must allow the attribute userCertificate;binary. Default top;person;organizationalPerson;inetOrgPerson

CA Object Class

The objectclass for the LDAP entries for CAs, where CA certificates and CRLs are published. The entry is hierarchical separated by ';' to build a structure. This objectclass must allow the attributes cACertificate;binary, certificateRevocationList;binary and authorityRevocationList;binary. Default top;applicationProcess;certificationAuthority

User Certificate Attribute

Attribute name, in the userObjectClass, for the user certificate. Default userCertificate;binary.

CA Certificate Attribute

Attribute name, in the cAObjectClass, for the CAs certificate. Default cACertificate;binary.

CRL Attribute

Attribute name, in the cAObjectClass, for CRLs (user CRLs) publisher by the CA. Default certificateRevocationList;binary.

ARL Attribute

Attribute name, in the cAObjectClass, for ARLs (CA CRLs) publisher by the CA. Default authorityRevocationList;binary (note that pure ARLs are not implemented yet in EJBCA).

LDAP location fields from cert DN

When configuring the LDAP publisher the BaseDN will be used as the base for the DN published in LDAP, and it will be appended to the LDAP location fields selected to be used. example: If the user DN in EJBCA is "cn=tomas gustavsson, uid=tomasg, O=PrimeKey Solutions AB, C=SE" and the BaseDN is "dc=PrimeKey,dc=SE" and the selected LDAP location fields are "CN". The LDAP DN used for publishing will be "cn=tomas gustavsson, dc=PrimeKey, dc=SE", and the "uid=tomasg" will be added as an attribute in LDAP. The certificate stored under "cn=tomas gustavsson, dc=PrimeKey, dc=SE" will have the subjectDN "cn=tomas gustavsson, uid=tomasg, O=PrimeKey Solutions AB, C=SE".

Setting up Certificate Profiles

To allow publishing in LDAP, you must create an EJBCA custom Certificate profile.

To publish in LDAP, you must create a Certificate profile in EJBCA that publishes to LDAP. If the publisher for LDAP is configured according to Configuring EJBCA above, there will be a section for Publishers available when creating/editing a certificate profile (with Edit Certificate Profiles).

Choose this, and then when adding end-entities, make sure they use the new certificate profile and voila, the certs will be published.

Different LDAP Publishers

LDAP Publisher

The regular LDAP Publisher works by searching the DN in LDAP.

When EJCA creates an object to publish a certificate to LDAP it firsts builds the DN from the baseDN and 'LDAP location fields for cert DN'. It checks if the entry exists in the LDAP and either creates or modifies the entry.

Example: The certificate DN is "CN=Tomas Gustavsson,O=Foo,C=SE", the BaseDN in the publisher is "DC=primekey,DC=se" and the CN is selected in "LDAP location fields from cert DN". The resulting DN that EJBCA will search for in the LDAP and create if it does not already exist is "CN=Tomas Gustavsson,DC=primekey,DC=se".

Using this publisher, if you have multiple trees in your LDAP (for example "ou=foo,dc=primekey,dc=se" and "ou=bar,dc=primekey,dc=se") you can either:

  1. Include both CN and OU in 'LDAP location fields from cert DN' and have your cert DNs like "CN=Tomas,OU=foo,O=MyOrg,C=SE.

  2. Use different publishers for ou=foo and ou=bar and issue certificates for the different OUs with different certificate profiles.

LDAP Search Publisher

The LDAP Search Publisher works by searching the LDAP for existing entries using a user defined search filter. If no entries exist in the LDAP when searching for an entry, one is created just like in the regular LDAP Publisher.

The search filter is defined in the following fields under LDAP search settings:

  • Suffix base DN of LDAP Search - the base for your search filter.

  • LDAP filter of the search - your LDAP filter.

If you build your search filter on DN components, you also have to select those components as LDAP location fields.

The best example of such a search filter is if base is "dc=primekey,dc=se" and filter is "uid=$USERNAME". The search done by EJBCA will be equal to the search:ldapsearch -x -b "dc=primekey,dc=se" "(uid=$USERNAME)"

$USERNAME is replaced by the EJBCA username of the user that has had a new certificate just generated. Other variables apart from $USERNAME is $EMAIL, $UID, $CN, $O, $OU and $C where these values are taken from the certificate DN.

When a certificate is generated for say user "ldap" EJBCA will perform the search:
ldapsearch -x -b "dc=primekey,dc=se" "(uid=ldap)"

The certificate generated for LDAP will be published in the object returned by the search. This is very useful if you want to publish certificates to an LDAP directory where your users already exists such as an email directory. The DN in the LDAP does not have to match the DN in the certificates at all.

If more than one entry matches the search, the first returned search result will be used.

What EJBCA stores/creates/modifies

Apart from the DN in the entry, a number of attributes are also stored. Some are required by schema, some are optional. EJBCA find attributes in the certificate, if it is an OU (organizational unit) in the certificate EJBCA uses that to populate the OU attribute in the LDAP entry.

When updating an entry that already exists EJBCA uses replace on the existing attributes, so if an email attributes already exists and EJBCA finds an email address in the certificate, the email attribute in LDAP is replaced with the email address from the certificate.

Attributes are only replaced/updated if the flag Modify Existing Users in the Publisher is active. The certificate attribute is always updated though. Attributes that are part of the DN, i.e. that reflects the location of the entry in LDAP is not modified, since this is usually not allowed.

The attributes that EJBCA creates or replaces are:

  • cn (common name)

  • l (locality)

  • ou (organizational unit)

  • sn (surname)

  • gn (givenname)

  • st (state)

  • o (organization)

  • uid (user id)

  • initials

  • title

  • serialnumber - If we have selected to use the SN (serialNUmber DN field) in Ldap Location fields, we will also add it as an attribute.

Configure OpenLDAP

The objectclass inetOrgPerson is used by default to store certificates.

Example:

dn: cn=Mike Jackson,ou=people,dc=company,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Mike Jackson
sn: Jackson
userCertificate;binary::

CAs are published in the form:

dn: cn=ejbca,dc=jackson,dc=net
objectClass: top
objectClass: applicationProcess
objectClass: certificationAuthority
cn: ejbca
cACertificate;binary:
certificateRevocationList;binary:
authorityRevocationList;binary:

To configure OpenLDAP (version 2.2.5) to include the inetOrgPerson, add the following lines to slapd.conf. This is already the default in recent releases:

include /etc/ldap/schema/cosine.schema
include /etc/ldap/schema/inetorgperson.schema

Add the top object by creating an LDIF file (org.ldif):

dn: o=AnaTom,c=SE
objectclass: dcObject
objectclass: organization
o: AnaTom
dc: AnaTom
dn: cn=Admin,o=AnaTom,c=SE
objectclass: organizationalRole
cn: Admin

And using the command:

ldapadd -x -D "cn=Admin,o=AnaTom,c=SE" -W -f org.ldif

Check what you have in the LDAP by:

ldapsearch -x -b 'o=AnaTom,c=SE' '(objectclass=*)'

Configure SSL

Create a user in EJBCA (this example is for adding a user with the cli interface, adding a user with the admin-GUI works just as fine). In the mail EJBCA directory type (use simply 'ra' on windows):

bin/ejbca.sh ra addendentity ldap foo123 "C=SE,O=Foo,CN=ldap" null ManagementCA null 1 PEM SERVER
bin/ejbca.sh ra setclearpwd ldap foo123

Where foo123 is the ldap users password, C=SE... is the users DN and ManagementCA is the name you chose for your CA. The user type is end-user (1), keystore type is PEM, and if using the admin-GUI check use batch).

Batch generate the PEM keystore:

bin/ejbca.sh batch

Copy the resulting files p12/pem/ldap.pem, p12/pem/ldap-CA.pem and p12/pem/ldap-Key.pem to your LDAP server. In this example the slapd.conf is located in /etc/ldap so we copy the files to that directory. Protect these files so they are only readable by the LDAP server.

Add the following to your slapd.conf:

# Use SSL
TLSCipherSuite HIGH:MEDIUM:+SSLv3
TLSCertificateFile /etc/ldap/ldap.pem
TLSCertificateKeyFile /etc/ldap/ldap-Key.pem
TLSCACertificateFile /etc/ldap/ldap-CA.pem 

Restart slapd:

./slapd -h "ldap:/// ldaps:///"

and check that it is running with ps -ef|grep slapd.

On SuSE, if using the built-in OpenLDAP you have to enable ldaps in /etc/sysconfig/openldap:

OPENLDAP_START_LDAPS="yes"

and then run:

SuSEconfig

and then:

rcldap start

Configure your LDAP publisher in EJBCA to use SSL by checking the checkbox Use SSL, the port should change to port 636.

Note! The CA certificate of the (root)CA used to sign the LDAP server certificate must be present in the java trust cert store ($JAVA_HOME/jre/lib/security/cacerts). Otherwise you will have to add it using something like: First get the CA cert:

bin/ejbca.sh ca getcacert MyCA myca.der -der

Then add it to the java trust store:

keytool -import -trustcacert -alias MyCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file myca.der

You have to re-start JBoss after adding anything to the java trust store.

For more information on configuring OpenLDAP on Solaris, refer to bolthole.com

Sample Ubuntu installation

- sudo apt-get install slapd ldap-utils
- sudo dpkg-reconfigure slapd
Configure slapd with your domain and admin password (primekey.com in this case).
- sudo /etc/init.d/slapd restart
- 'ps -ef|grep slap'
should show a slapd running
- ldapsearch -x -b 'dc=primekey,dc=se' '(objectclass=*)'
To look at the results
- slapcat -l backup.ldif
Make backup
- slapadd -l backup.ldif
- /etc/init.d/slapd restart
Restore backup 

Run the following command to add new LDAP nodes:

- ldapadd -x -D "cn=admin,dc=PrimeKey,dc=com" -W -f primekey.ldif
where primekey.ldif is:
 
dn: dc=PrimeKey,dc=com
dc: PrimeKey
objectclass: dcObject
objectclass: organization
o: PrimeKey Solutions AB
description: Parent Object for PrimeKey LDAP Directory
 
dn: ou=Standard,dc=PrimeKey,dc=com
ou: Standard
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all Standard Certificates
 
dn: ou=High,dc=PrimeKey,dc=com
ou: High
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all High Certificates 

OpenDJ

OpenDJ is a modern, standards compliant, java based, LDAP server that is easy to set up and use. It also comes with GUI tools to manage and query.

Installing OpenDJ

This example uses OpenDJ 2.5.0 as an example, but other versions should work similarly.

  • unzip OpenDJ-2.5.0-Xpress1.zipthe Control Panel

  • cd OpenDJ-2.5.0-Xpress1

  • ./setup

    • This launches graphical setup, you can run setup --cli to install without GUI.

    • Use default Root User DN: cn=Directory Manager

    • Directory Base DN: dc=example,dc=com)

    • If you want to be able to run OpenDJ on the same server as JBoss/EJBCA, choose another port for management, i.e. 5555 instead of 4444.

  • You can end by starting Launch Control Panel, or you can start it later with bin/control-panel.

An EJBCA publisher for a default installation is then configured with:

  • Base DN: dc=example,dc=com

  • Administrator: cn=Directory Manager

The graphical LDAP browser is accessible from the Control Panel > Manage Entries. You can start/stop OpenDJ from within the Control Panel or with bin/start-ds and stop-ds.

Management tasks such as creating new attributes and object types easy to do in the Control Panel GUI.

OpenDJ listens to port 1389 by default, but it also occupies other ports stopping it from running on the same server as JBoss. If you want to change the management port (default 4444) after installation you can edit confif/config.ldif and config/tools.properties.

Configure SSL/TLS

For information on configuring SSL/TLS with OpenDJ, refer to OpenDJ documentation.

If you run setup using the command line (--cli) you will be prompted with TLS questions, having the possibility to set up TLS directly.

Custom Schemas

See doc/ldapschema for files with custom schemas and attribute types to add to your LDAP schema.

Certificate Serial Number

This is an attribute and a schema extension to allow storage of certificate serial number in the inetOrgPerson LDAP object, for end user entries. This is done by adding an extension to inetOrgPerson called inetOrgPersonWithCertSerno with a new optional attribute called certificateSerialNumber.

Once you have installed the new schema in the LDAP server you use it by configuring the LDAP publisher with:

  • User Object Class: top;person;organizationalPerson;inetOrgPerson;inetOrgPersonWithCertSerno

instead of the befault value:

  • User Object Class: top;person;organizationalPerson;inetOrgPerson

The certificateSerialNumber attribute will then automatically be added/modified when publishing to LDAP.

Extra Device Schema

To store certificates for devices (e.g. routers, toasters etc) in LDAP it is no really suitable standard object class. inetOrgPerson requires surnames etc, and the device objectclass does not include a certificate attribute.

Mike Jackson has kindly contributed additional objects that extend the standard device class with a certificate attribute. The ejbcaDevice uses object ids from PrimeKey Solutions AB.

Installation

For the Netscape/SUN servers, on UNIX, copy the 85ejbca.ldif file into:

/usr/netscape/servers/slapd-hostname/config/schema/

and restart the LDAP server.

For OpenLDAP, copy the ejbca.schema file into, e.g.:

/etc/ldap/schema/

and edit slapd.conf to add the following line:

include /etc/ldap/schema/ejbca.schema

then restart the server.