Starting and Stopping Your Server Instance
Configuring the Server Instance
Configuring the Proxy Components
Configuring Security Between Clients and Servers
Getting SSL Up and Running Quickly
To Accept SSL-Based Connections Using a Self-Signed Certificate
Configuring Key Manager Providers
Using the JKS Key Manager Provider
To Sign the Certificate by Using an External Certificate Authority
To Configure the JKS Key Manager Provider
Using the PKCS #12 Key Manager Provider
Using the PKCS #11 Key Manager Provider
Configuring Trust Manager Providers
Overview of Certificate Trust Mechanisms
Using the Blind Trust Manager Provider
Using the JKS Trust Manager Provider
Using the PKCS #12 Trust Manager Provider
Configuring Certificate Mappers
Using the Subject Equals DN Certificate Mapper
Using the Subject Attribute to User Attribute Certificate Mapper
Using the Subject DN to User Attribute Certificate Mapper
Using the Fingerprint Certificate Mapper
Configuring SSL and StartTLS for LDAP and JMX
Configuring the LDAP and LDAPS Connection Handlers
To Enable a Connection Handler
To Specify a Connection Handler's Listening Port
To Specify a Connection Handler's Authorization Policy
To Specify a Nickname for a Connection Handler's Certificate
To Specify a Connection Handler's Key Manager Provider
To Specify a Connection Handler's Trust Manager Provider
To Enable SSL-Based Communication
Enabling SSL in the JMX Connection Handler
SASL Options for the ANONYMOUS Mechanism
SASL Options for the CRAM-MD5 Mechanism
SASL Options for the DIGEST-MD5 Mechanism
SASL Options for the EXTERNAL Mechanism
SASL Options for the GSSAPI Mechanism
SASL Options for the PLAIN Mechanism
Configuring SASL Authentication
Configuring SASL External Authentication
Configuring SASL DIGEST-MD5 Authentication
Configuring SASL GSSAPI Authentication
To Configure Kerberos V5 on a Host
To Specify SASL Options for Kerberos Authentication
Troubleshooting Kerberos Configuration
Testing SSL, StartTLS, and SASL Authentication With ldapsearch
ldapsearch Command Line Arguments Applicable To Security
Testing SASL External Authentication
Controlling Connection Access using Allowed and Denied Rules
Configuring Security Between the Proxy and the Data Source
Configuring Servers With the Control Panel
Configuring Kerberos for the Sun OpenDS Standard Edition directory server can be complicated. Your first point of reference should be the Kerberos documentation.
For more help, use the following example procedure to get an idea of which steps to follow. Be aware, however, that this procedure is an example. You must modify the procedure to suit your own configuration and your own environment.
Additional information about configuring and using Kerberos in the Solaris OS can be found in System Administration Guide: Security Services. This guide is a part of the Solaris documentation set. You can also consult the man pages.
Information about this example and the steps used are as follows:
All Machines: Edit the Administration Server ACL Configuration File
KDC Machine: Add Host Principals for the KDC and OpenDS Machines
Directory Server Machine: Configure the Directory Server to Enable GSSAPI
Directory Server Machine: Create and Configure the Directory Server LDAP Principal
Directory Server Machine: Add a Test User to the Directory Server
Directory Server Machine: Obtain a Kerberos Ticket as the Test User
Client Machine: Authenticate to the Directory Server Through GSSAPI
This example procedure describes the process of configuring one machine to operate as a Key Distribution Center (KDC), and a second machine to run the directory server. The result of this procedure is that users can perform Kerberos authentication through GSSAPI.
It is possible to run both the KDC and the directory server on the same machine. If you choose to run both on the same machine, use the same procedure, but omit the steps for the directory server machine that have already been done for the KDC machine.
This procedure makes a number of assumptions about the environment that is used. When using the example procedure, modify the values accordingly to suit your environment. These assumptions are:
This system has a fresh installation of the Solaris 10 software with the latest recommended patch cluster installed. Kerberos authentication to the directory server can fail if the appropriate Solaris patches are not installed.
The machine that is running the Kerberos daemons has the fully qualified domain name of kdc.example.com. The machine must be configured to use DNS as a naming service. This configuration is a requirement of Kerberos. Certain operations might fail if other naming services such as file are used instead.
The machine that is running the directory server has the fully qualified domain name of directory.example.com. This machine must also be configured to use DNS as a naming service.
The directory server machine serves as the client system for authenticating to the directory server through Kerberos. This authentication can be performed from any system that can communicate with both the directory server and Kerberos daemons. However, all of the necessary components for this example are provided with the Sun OpenDS Standard Edition directory server, and the authentication is performed from that system.
Users in the directory server have DNs of the form uid=username,ou=People,dc=example,dc=com. The corresponding Kerberos principal is username@EXAMPLE.COM. If a different naming scheme is used, a different GSSAPI identity mapping must be used.
The /etc/krb5/krb5.conf configuration file provides information that Kerberos clients require in order to communicate with the KDC.
Edit the /etc/krb5/krb5.conf configuration file on the KDC machine, the directory server machine, and any client machines that will authenticate to the directory server using Kerberos.
Replace every occurrence of "___default_realm___" with "EXAMPLE.COM".
Replace every occurrence of "___master_kdc___" with "kdc.example.com".
Remove the lines that contain "___slave_kdcs___" as there will be only a single Kerberos server.
Replace "___domain_mapping___" with ".example.com = EXAMPLE.COM" (note the initial period in .example.com).
The updated /etc/krb5/krb5.conf configuration file should look like the contents of the following example.
#pragma ident "@(#)krb5.conf 1.2 99/07/20 SMI" # Copyright (c) 1999, by Sun Microsystems, Inc. # All rights reserved. # # krb5.conf template # In order to complete this configuration file # you will need to replace the __<name\>__ placeholders # with appropriate values for your network. # [libdefaults] default_realm = EXAMPLE.COM [realms] EXAMPLE.COM = { kdc = kdc.example.com admin_server = kdc.example.com } [domain_realm] .example.com = EXAMPLE.COM [logging] default = FILE:/var/krb5/kdc.log kdc = FILE:/var/krb5/kdc.log kdc_rotate = { # How often to rotate kdc.log. Logs will get rotated no more # often than the period, and less often if the KDC is not used # frequently. period = 1d # how many versions of kdc.log to keep around (kdc.log.0, kdc.log.1, ...) versions = 10 } [appdefaults] kinit = { renewable = true forwardable= true } gkadmin = { help_url = http://docs.sun.com:80/ab2/coll.384.1/SEAM/@AB2PageView/1195 }
Replace "___default_realm___" with "EXAMPLE.COM" in the /etc/krb5/kadm5.acl configuration file. The updated file should look like the following example.
# # Copyright (c) 1998-2000 by Sun Microsystems, Inc. # All rights reserved. # # pragma ident "@(#)kadm5.acl 1.1 01/03/19 SMI" */admin@EXAMPLE.COM *
Edit the /etc/krb5/kdc.conf file to replace "___default_realm___" with "EXAMPLE.COM". The updated file should look like the following example.
# Copyright 1998-2002 Sun Microsystems, Inc. All rights reserved. # Use is subject to license terms. # #ident "@(#)kdc.conf 1.2 02/02/14 SMI" [kdcdefaults] kdc_ports = 88,750 [realms] EXAMPLE.COM = { profile = /etc/krb5/krb5.conf database_name = /var/krb5/principal admin_keytab = /etc/krb5/kadm5.keytab acl_file = /etc/krb5/kadm5.acl kadmind_port = 749 max_life = 8h 0m 0s max_renewable_life = 7d 0h 0m 0s default_principal_flags = +preauth }
$ /usr/sbin/kdb5_util create -r EXAMPLE.COM -s Initializing database ’/var/krb5/principal’ for realm ’EXAMPLE.COM’, master key name ’K/M@EXAMPLE.COM’ You will be prompted for the database Master Password. It is important that you NOT FORGET this password. Enter KDC database master key: password Re-enter KDC database master key to verify: password $
Use the following command to create an administration user with a Principal of kws/admin@EXAMPLE.COM and service keys that will be used by the administration daemon.
$ /usr/sbin/kadmin.local kadmin.local: add_principal kws/admin Enter password for principal "kws/admin@EXAMPLE.COM": secret Re-enter password for principal "kws/admin@EXAMPLE.COM": secret Principal "kws/admin@EXAMPLE.COM" created. kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/kdc.example.com Entry for principal kadmin/kdc.example.com with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab. kadmin.local: ktadd -k /etc/krb5/kadm5.keytab changepw/kdc.example.com Entry for principal changepw/kdc.example.com with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab. kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/changepw Entry for principal kadmin/changepw with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab. kadmin.local: quit$
The Kerberos daemons are managed by the Service Management Facility (SMF) framework. Run the following commands to start the KDC and administration daemons:
$ /etc/init.d/kdc start $ /etc/init.d/kdc.master start $
$ svcadm disable network/security/krb5kdc $ svcadm enable network/security/krb5kdc $ svcadm disable network/security/kadmin $ svcadm enable network/security/kadmin $
The KDC process appears in the process list as /usr/lib/krb5/krb5kdc. The administration daemon appears as /usr/lib/krb5/kadmind.
Use the following sequence of commands to add host Principals to the Kerberos database for the KDC and the directory server machines. The host Principal is used by certain Kerberos utilities such as klist.
$ /usr/sbin/kadmin -p kws/admin Enter Password: secret kadmin: add_principal -randkey host/kdc.example.com Principal "host/kdc.example.com@EXAMPLE.COM" created. kadmin: ktadd host/kdc.example.com Entry for principal host/kdc.example.com with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab. kadmin: add_principal -randkey host/directory.example.com Principal "host/directory.example.com@EXAMPLE.COM" created. kadmin: ktadd host/directory.example.com Entry for principal host/directory.example.com with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab. kadmin: quit $
For the directory server to be able to validate the Kerberos tickets that are held by authenticating users, the directory server must have its own Principal. Currently, the Sun OpenDS Standard Edition directory server is hard coded to require a Principal of ldap/fqdn@realm where fqdn is the fully-qualified domain name of the directory server and realm is the Kerberos realm. The fqdn must match the fully qualified name that is provided when you install the directory server. In this case, the Principal for the directory server would be ldap/directory.example.com@EXAMPLE.COM.
Use the following sequence of commands to create an LDAP Principal for the directory server:
$ /usr/sbin/kadmin -p kws/admin Enter Password: secret kadmin: add_principal -randkey ldap/directory.example.com Principal "ldap/directory.example.com@EXAMPLE.COM" created. kadmin: quit $
To perform Kerberos authentication, the user authenticating must exist in the Kerberos database. In this example, the user has the user name kerberos-test, which means that the Kerberos Principal is kerberos-test@EXAMPLE.COM.
Create the user by using the command sequence in this example:
$ /usr/sbin/kadmin -p kws/admin Enter Password: secret kadmin: add_principal kerberos-test Enter password for principal "kerberos-test@EXAMPLE.COM": secret Re-enter password for principal "kerberos-test@EXAMPLE.COM": secret Principal "kerberos-test@EXAMPLE.COM" created. kadmin: quit $
Install the directory server using at least version 1.3. Versions of the directory server earlier than 1.3 do not offer full support of GSSAPI SASL. The following table lists the installation settings that this section uses in examples.
|
Note - The fully qualified directory server DNS name must resolve to the same IP address on all of the servers, namely the OpenDS servers and the Kerberos Key Distribution Center (KDC) and client machines that expect to bind to the server using GSSAPI SASL.
As mentioned previously, to authenticate Kerberos users through GSSAPI, the directory server must have its own Principal in the KDC. For authentication to work properly, the Principal information must reside in a Kerberos keytab on the directory server machine. This information must be in a file that is readable by the user account under which the directory server operates.
Note - This step must be performed before the OpenDS GSSAPI SASL mechanism handler is configured. The handler checks to make sure the keytab file exists before it will initialize.
Create a keytab file with the correct properties by using the following command sequence:
$ kadmin -p kws/admin@EXAMPLE.COM kadmin: addprinc -randkey ldap/directory.example.com WARNING: no policy specified for ldap/directory.example.com@EXAMPLE.COM; defaulting to no policy Principal "ldap/directory.example.com@EXAMPLE.COM" created. kadmin: ktadd -k /opt/opends/config/opends.keytab ldap/directory.example.com Entry for principal ldap/directory.example.com with kvno 3, encryption type AES-128 CTS mode with 96-bit SHA-1 HMAC added to keytab WRFILE:/opt/opends/config/opends.keytab. Entry for principal ldap/directory.example.com with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/opt/opends/config/opends.keytab. Entry for principal ldap/directory.example.com with kvno 3, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/opt/opends/config/opends.keytab. Entry for principal ldap/directory.example.com with kvno 3, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/opt/opends/config/opends.keytab. kadmin: quit
Change the permissions and ownership on this custom keytab. Make the keytab owned by the user account used to run the directory server and readable only by that user:
$ chown opends:opends /opt/opends/config/opends.keytab $ chmod 600 /opt/opends/config/opends.keytab
Finally, to allow these changes to take effect, use one of the following ways to stop and restart the directory server:
Click the Restart button on the Control Panel.
Run the stop-ds -r command.
This step shows examples of managing the OpenDS GSSAPI SASL mechanism handler on the directory server host directory.example.com.
Use the dsconfig command as shown in the following example to enable the GSSAPI SASL mechanism handler on the directory server host directory.example.com and configure it to use the /opt/opends/config/opends.keytab.
$ dsconfig -X -n -p 4444 -h directory.example.com \ -D "cn=directory manager" -w password set-sasl-mechanism-handler-prop \ --handler-name GSSAPI \ --set enabled:true \ --set keytab:/opt/opends/config/opends.keytab \ --set server-fqdn:directory.example.com
The last line in this command sets the GSSAPI SASL mechanism property server-fqdn to directory.example.com. This is an optional parameter, which can be left out only if it is assured that a hostname lookup on the directory server host returns the exact hostname that was used in creating the LDAP principal. Setting this property explicitly assures that the two names are the same (in this example, directory.example.com).
Confirm that the configuration is correct by examining the properties of the GSSAPI SASL mechanism handler on the directory server host directory.example.com.
$ dsconfig -X -n -p 4444 -h directory.example.com \ -D "cn=directory manager" -w password \ get-sasl-mechanism-handler-prop \ --handler-name GSSAPI Property : Value(s) ----------------------:---------------------- enabled : true identity-mapper : Regular Expression kdc-address : - keytab : /opt/opends/config/opends.keytab principal-name : - quality-of-protection : none realm : - server-fqdn : directory.example.com
If necessary for troubleshooting, you can use dsconfig to list the status of all the SASL mechanism handlers on the directory server host directory.example.com.
$ dsconfig -X -n -p 4444 -h directory.example.com \ -D "cn=directory manager" -w password \ list-sasl-mechanism-handlers SASL Mechanism Handler : Type : enabled -----------------------:------------:-------- ANONYMOUS : anonymous : false CRAM-MD5 : cram-md5 : true DIGEST-MD5 : digest-md5 : true EXTERNAL : external : true GSSAPI : gssapi : true PLAIN : plain : true
If necessary, you can use dsconfig to disable the GSSAPI SASL mechanism handler on the directory server host directory.example.com.
$ dsconfig -X -n -p 4444 -h directory.example.com \ -D "cn=directory manager" -w password \ set-sasl-mechanism-handler-prop \ --handler-name GSSAPI \ --set enabled:false
To authenticate a Kerberos user to the directory server, there must be a directory entry for the user that corresponds to the Kerberos Principal for that user.
In a previous step, a test user was added to the Kerberos database with a Principal of kerberos-test@EXAMPLE.COM. Because of the identity mapping configuration added to the directory, the corresponding directory entry for that user must have a DN of uid=kerberos-test,ou=People,dc=example,dc=com.
Before you can add the user to the directory, you must create the file testuser.ldif with the following contents.
dn: uid=kerberos-test,ou=People,dc=example,dc=com changetype: add objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson uid: kerberos-test givenName: Kerberos sn: Test cn: Kerberos Test description: An account for testing Kerberos authentication through GSSAPI
Next, use ldapmodify to add this entry to the server:
$ ldapmodify -D "cn=Directory Manager" -w - -f testuser.ldif adding new entry uid=kerberos-test,ou=People,dc=example,dc=com $
The test user exists in the Kerberos database, the directory server, and the KDC. Therefore, it is now possible to authenticate as the test user to the directory server over Kerberos through GSSAPI.
First, use the kinit command to get a Kerberos ticket for the user, as shown in the following example:
$ kinit kerberos-test Password for kerberos-test@EXAMPLE.COM: secret $
Then, use the klist command to view information about this ticket:
$ klist Kerberos 5 ticket cache: 'API:6' Default principal: kerberos-test@EXAMPLE.COM Valid Starting Expires Service Principal 03/23/09 12:35:05 03/23/09 20:35:05 krbtgt/EXAMPLE.COM@EXAMPLE.COM renew until 03/30/09 12:34:15 $
The final step is to authenticate to the directory server by using GSSAPI. The ldapsearch utility provided with The directory server provides support for SASL authentication, including GSSAPI, DIGEST-MD5, and EXTERNAL mechanisms. However, to bind by using GSSAPI you must provide the client with the path to the SASL library. Provide the path by setting the SASL_PATH environment variable to the lib/sasl directory:
$ SASL_PATH=SASL-library $ export SASL_PATH $
To actually perform a Kerberos-based authentication to the directory server using ldapsearch, you must include the -o mech=GSSAPI and -o authzid=principal arguments.
You must also specify the fully qualified host name, shown here as -h directory.example.com, which must match the value of the nsslapd-localhost attribute on cn=config for the server. This use of the -h option is needed because the GSSAPI authentication process requires the host name provided by the client to match the host name provided by the server.
The following example retrieves the dc=example,dc=com entry while authenticated as the Kerberos test user account created previously:
$ ldapsearch -h directory.example.com -p 389 -o mech=GSSAPI \ -o authzid="kerberos-test@EXAMPLE.COM" -b "dc=example,dc=com" -s base "(objectClass=*)" version: 1 dn: dc=example,dc=com dc: example objectClass: top objectClass: domain $
Check the directory server access log to confirm that the authentication was processed as expected:
$ tail -12 /local/ds/logs/access [24/Jul/2004:00:30:47 -0500] conn=0 op=-1 msgId=-1 - fd=23 slot=23 LDAP connection from 1.1.1.8 to 1.1.1.8 [24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - BIND dn="" method=sasl version=3 mech=GSSAPI [24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - RESULT err=14 tag=97 nentries=0 etime=0, SASL bind in progress [24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - BIND dn="" method=sasl version=3 mech=GSSAPI [24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - RESULT err=14 tag=97 nentries=0 etime=0, SASL bind in progress [24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - BIND dn="" method=sasl version=3 mech=GSSAPI [24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - RESULT err=0 tag=97 nentries=0 etime=0 dn="uid=kerberos-test,ou=people,dc=example,dc=com" [24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - SRCH base="dc=example,dc=com" scope=0 filter="(objectClass=*)" attrs=ALL [24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - RESULT err=0 tag=101 nentries=1 etime=0 [24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=5 - UNBIND [24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=-1 - closing - U1 [24/Jul/2004:00:30:48 -0500] conn=0 op=-1 msgId=-1 - closed. $
This example shows that the bind is a three-step process. The first two steps return LDAP result 14 (SASL bind in progress), and the third step shows that the bind was successful. The method=sasl and mech=GSSAPI tags show that the bind used the GSSAPI SASL mechanism. The dn="uid=kerberos-test,ou=people,dc=example,dc=com" at the end of the successful bind response shows that the bind was performed as the appropriate user.