When using the GSSAPI mechanism in clients, you do not need to install a user certificate, but you must configure the Kerberos V5 security system. Also, if you want to use encrypted SSL connections, you must trust the server certificate as described in Managing Certificates.
You must configure Kerberos V5 on the host machine where your LDAP clients will run.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Install Kerberos V5 according to its installation instructions.
Sun recommends installing the Sun Enterprise Authentication Mechanism 1.0.1 client software.
Configure the Kerberos software.
Using the Sun Enterprise Authentication Mechanism software, configure the files under /etc/krb5. This configuration sets up the kdc server, and defines the default realm and any other configuration required by your Kerberos system.
If necessary, modify the file /etc/gss/mech so that the first value that is listed is kerberos_v5 .
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Before using a client application that is enabled with the GSSAPI mechanism, initialize the Kerberos security system with your user Principal.
$ kinit user-principal |
where the user-principal is your SASL identity, for example, bjensen@example.com.
Specify SASL options for using Kerberos.
Note that in the UNIX environment, you must set the SASL_PATH environment variable to the correct path for the SASL libraries. For example in the Korn shell:
$ export SASL_PATH=SASL-library |
This path assumes that Directory Server is installed on the same host where the LDAP tools are invoked.
The following example of the ldapsearch tool shows the use of the -o (lowercase letter o) option to specify SASL options for using Kerberos:
$ ldapsearch -h www.host1.com -p 1389 -o mech=GSSAPI -o authid="bjensen@EXAMPLE.COM" \ -o authzid="bjensen@EXAMPLE.COM" -b "dc=example,dc=com" "(givenname=Richard)" |
The authid can be omitted because it is present in the Kerberos cache that was initialized by the kinit command. If authid is present, authid and authzid must be identical, although the authzid intended for proxy operations is not used. The value of authid is the Principal that is used in identity mapping. The Principal must be the full Principal, including the realm. See GSSAPI Identity Mappings.
Configuring Kerberos for 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 Directory Server Machines
Directory Server Machine: Configure the Directory Server to Enable GSSAPI
Directory Server Machine: Add a Test User to the Directory Server
Directory Server Machine: Get 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 a 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 9 software with the latest recommended patch cluster installed. Kerberos authentication to the Directory Server can fail if the appropriate Solaris patches are not installed.
Note that although the documented procedure is largely the same for Solaris 10, there are some differences. The configuration file format is slightly different, and the output of some of the commands might not be the same.
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 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 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 line that contains "___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$ |
Run the following commands to start the KDC and administration daemons:
$ /etc/init.d/kdc start $ /etc/init.d/kdc.master start $ |
The KDC process will appear in the process list as /usr/lib/krb5/krb5kdc. The administration daemon will appear as /usr/lib/krb5/kadmind.
Note than in the Solaris 10 OS, the daemons are managed by the Service Management Facility (SMF) framework. Start the daemons on the Solaris 10 OS:
$ svcadm disable network/security/krb5kdc $ svcadm enable network/security/krb5kdc $ svcadm disable network/security/kadmin $ svcadm enable network/security/kadmin $ |
Use the following sequence of commands to add host Principals to the Kerberos database for the KDC and 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 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 provided when installing 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 Directory Server 6.0 and the latest patches. Following are example settings.
Variable Type |
Example Value |
---|---|
Fully qualified computer name |
directory.example.com |
Installation directory |
/opt/SUNWdsee |
Instance path |
/local/ds |
Server user |
unixuser |
Server group |
unixgroup |
Server port |
389 |
Suffix |
dc=example,dc=com |
First, create the file /data/ds/shared/bin/gssapi.ldif to define the mapping that should be used by the Directory Server, and to identify which Kerberos user is authenticating, based on the Principal. Create the file contents to be the same as what is shown in the following example.
dn: cn=GSSAPI,cn=identity mapping,cn=config changetype: add objectClass: top objectClass: nsContainer cn: GSSAPI dn: cn=default,cn=GSSAPI,cn=identity mapping,cn=config changetype: add objectClass: top objectClass: nsContainer objectClass: dsIdentityMapping objectClass: dsPatternMatching cn: default dsMatching-pattern: \${Principal} dsMatching-regexp: (.*)@EXAMPLE.COM dsMappedDN: uid=\$1,ou=People,dc=example,dc=com dn: cn=SASL,cn=security,cn=config changetype: modify replace: dsSaslPluginsPath dsSaslPluginsPath: /usr/lib/mps/sasl2/libsasl.so |
Next, use the ldapmodify command to update the Directory Server to enable GSSAPI with the appropriate mappings, as shown in the following example:
$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -a -f /data/ds/shared/bin/gssapi.ldif adding new entry cn=GSSAPI,cn=identity mapping,cn=config adding new entry cn=default,cn=GSSAPI,cn=identity mapping,cn=config modifying entry cn=SASL,cn=security,cn=config $ |
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.
Create a keytab file with the correct properties by using the following command sequence:
$ /usr/sbin/kadmin -p kws/admin Enter Password: secret kadmin: ktadd -k /local/ds/config/ldap.keytab ldap/directory.example.com Entry for principal ldap/directory.example.com with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/local/ds/config/ldap.keytab. kadmin: quit $ |
Change the permissions and ownership on this custom keytab. Make the keytab owned by the user account used to run Directory Server and readable only by that user:
$ chown unixuser:unixgroup /local/ds/config /ldap.keytab $ chmod 600 /local/ds/config/ldap.keytab $ |
By default, the Directory Server tries to use the standard Kerberos keytab in the file /etc/kerb5/krb5.keytab. However, making this file readable by the Directory Server user could constitute a security risk, which is why a custom keytab was created for the Directory Server.
Configure the Directory Server to use the new custom keytab. Do this by setting the KRB5_KTNAME environment variable.
Finally, restart the Directory Server to allow these changes to take effect:
$ KRB5_KTNAME=/etc/krb5/ldap.keytab dsadm restart /local/ds |
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=admin,cn=Administrators,cn=config -w - -f testuser.ldif adding new entry uid=kerberos-test,ou=People,dc=example,dc=com $ |
The test user exists in the Kerberos database and 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 Ticket cache: /tmp/krb5cc_0 Default principal: kerberos-test@EXAMPLE.COM Valid starting Expires Service principal Sat Jul 24 00:24:15 2004 Sat Jul 24 08:24:15 2004 krbtgt/EXAMPLE.COM@EXAMPLE.COM renew until Sat Jul 31 00:24:15 2004 $ |
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.