Oracle® Fusion Middleware Administrator's Guide for Oracle Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0) Part Number E28972-01 |
|
|
PDF · Mobi · ePub |
Directory Server supports several mechanisms that provide secure and trusted communications over the network. LDAPS is the standard LDAP protocol that runs on top of the Secure Sockets Layer (SSL). LDAPS encrypts data and optionally uses certificates for authentication. When the term SSL is used in this chapter, it means the supported protocols SSL2, SSL3 and TLS 1.0.
Directory Server also supports the Start Transport Layer Security (Start TLS) extended operation to enable TLS on an LDAP connection that was originally not encrypted.
In addition, Directory Server supports the Generic Security Service API (GSSAPI) over the Simple Authentication and Security Layer (SASL). The GSSAPI allows you to use the Kerberos Version 5 security protocol on the Solaris and Linux operating systems. An identity mapping mechanism then associates the Kerberos principal with an identity in the directory.
For additional security information, see the NSS web site at http://www.mozilla.org/projects/security/pki/nss/
.
This chapter provides procedures for configuring security through SSL. For information about ACIs, see Chapter 6, "Directory Server Access Control". For information about user access and passwords, see Chapter 8, "Directory Server Password Policy".
This chapter covers the following topics:
The Secure Sockets Layer (SSL) provides encrypted communication and optional authentication between a Directory Server and its clients. SSL can be used over LDAP or with DSML-over-HTTP. SSL is enabled by default over LDAP, but if you are using DSML-over-HTTP, you can easily enable SSL. In addition, replication can be configured to use SSL for secure communications between servers.
Using SSL with simple authentication (bind DN and password) encrypts all data sent to and from the server. Encryption guarantees confidentiality and data integrity. Optionally, clients can use a certificate to authenticate to Directory Server or to a third-party security mechanism through the Simple Authentication and Security Layer (SASL). Certificate-based authentication uses public-key cryptography to prevent forgery and impersonation of either the client or the server.
Directory Server is capable of simultaneous SSL and non-SSL communications on separate ports. For security reasons, you can also restrict all communications to the LDAP secure port. Client authentication is also configurable. You can set client authentication to required or to allowed. This setting determines the level of security you enforce.
SSL enables support for the Start TLS extended operation that provides security on a regular LDAP connection. Clients can bind to the standard LDAP port and then use the Transport Layer Security protocol to secure the connection. The Start TLS operation allows more flexibility for clients, and can help simplify port allocation.
The encryption mechanisms provided by SSL are also used for attribute encryption. Enabling SSL allows you to configure attribute encryption on your suffixes, which protects data while it is stored in the directory. For more information, see Encrypting Attribute Values.
For additional security, you can set access control to directory contents through access control instructions (ACIs). ACIs require a specific authentication method and ensure that data can only be transmitted over a secure channel. Set the ACIs to complement your use of SSL and certificates. For more information, see Chapter 6, "Directory Server Access Control".
SSL is enabled by default over LDAP, and you can easily enable SSL for DSML-over-HTTP. In addition, there are some aspects of the SSL configuration that you might want to modify, as described in the following sections.
This section describes how to manage SSL certificates in Directory Server.
To run SSL on Directory Server, you must either use a self-signed certificate or a Public Key Infrastructure (PKI) solution.
The PKI solution involves an external Certificate Authority (CA). For a PKI solution, you need a CA-signed server certificate, which contains both a public key and a private key. This certificate is specific to one Directory Server. You also need a trusted CA certificate, which contains a public key. The trusted CA certificate ensures that all server certificates from your CA are trusted. This certificate is sometimes called a CA root key or root certificate.
Note:
If you are using certificates for test purposes, you probably want to use self-signed certificates. However, in production, using self-signed certificates is not very secure. In production, use trusted Certificate Authority (CA) certificates.
The procedures in this section use the dsadm
and dsconf
commands. For information about these commands, see the dsadm and dsconf man pages.
This section provides the following information about configuring certificates on Directory Server:
To Add the CA-Signed Server Certificate and the Trusted CA Certificate
Backing Up and Restoring the Certificate Database for Directory Server
When a Directory Server instance is first created, it contains a default self-signed certificate. A self-signed certificate is a public and private key pair, where the public key is signed by the private key. A self-signed certificate is valid for 24 months.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
To view the default self-signed certificate, use this command:
$ dsadm show-cert instance-path defaultCert
When you create a Directory Server instance, a default self-signed certificate is automatically provided.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
To create a self-signed certificate with non-default settings, use this command:
$ dsadm add-selfsign-cert instance-path cert-alias
Where cert-alias is a name that you provide to identify your certificate.
To see all the options for this command, see the dsadm man page or the command-line help:.
$ dsadm add-selfsign-cert --help
When your self-signed certificate expires, stop the server instance and renew the certificate.
$ dsadm stop instance-path $ dsadm renew-selfsign-cert instance-path cert-alias
Restart the server instance.
$ dsadm start instance-path
This procedure explains how to request and install a CA-signed server certificate for use with Directory Server.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Generate a CA-signed server certificate request.
$ dsadm request-cert [-i] [-W cert-pwd-file] {-S DN | --name name [--org org] \ [--org-unit org-unit] [--city city] [--state state] [--country country]} \ [--phone PHONE] [--email EMAIL] [--dns DOMAIN] [--keysize KEYSIZE] \ [--sigalg SIGALG] [-F format] [-o output-file] instance-path
For example, to request a CA-signed server certificate for the Example company, use this command:
$ dsadm request-cert --name host1 --org Example --org-unit Marketing \ -o my_cert_request_file /local/dsInst
In order to completely identify the server, Certificate Authorities might require all of the attributes that are shown in this example. For a description of each attribute, see the dsadm man page.
When you request a certificate by using dsadm request-cert
, the resulting certificate request is a binary certificate request unless you specify ASCII as output format. If you specify ASCII, the resulting certificate request is a PKCS #10 certificate request in PEM format. PEM is the Privacy Enhanced Mail format specified by RFCs 1421 through 1424 (http://www.ietf.org/rfc/rfc1421.txt
) and is used to represent a base64-encoded certificate request in US-ASCII characters. The content of the request looks similar to the following example:
-----BEGIN NEW CERTIFICATE REQUEST----- MIIBrjCCARcCAQAwbjELMAkGA1UBhMCVXMxEzARBgNVBAgTCkNBElGT1JOSUExLD AqBgVBAoTI25ldHNjYXBlIGNvb11bmljYXRpb25zIGNvcnBvcmF0aWuMRwwGgYDV QQDExNtZWxsb24umV0c2NhcGUuY29tMIGfMA0GCSqGSIb3DQEBAUAA4GNADCBiQK BgCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7u0EfgSLR0f+K41eNqqWRftGR83e mqPLDOf0ZLTLjVGJaHJn4l1gG+JDf/n/zMyahxtV7+T8GOFFigFfuxJaxMjr2j7I vELlxQ4IfZgwqCm4qQecv3G+N9YdbjveMVXW0v4XwIDAQABAAwDQYJKoZIhvcNAQ EEBQADgYEAZyZAm8UmP9PQYwNy4Pmypk79t2nvzKbwKVb97G+MT/gw1pLRsuBoKi nMfLgKp1Q38K5Py2VGW1E47/rhm3yVQrIiwV+Z8Lcc= -----END NEW CERTIFICATE REQUEST-----
You must save the request at a secure place for future reference. You may need the request for renewal.
Transmit the certificate request to your Certificate Authority, according to its procedures.
The process for obtaining your Certificate Authority certificate depends on the certificate authority that you use. Some commercial CAs provide a website that allows you to automatically download the certificate. Other CAs will send it to you in email upon request.
After you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, the CA might only take a day or two to respond to your request. If your selected CA is external to your company, the CA could take several weeks to respond to your request.
Save the certificate that you receive from the Certificate Authority.
Back up your certificates in a safe location. If you ever lose the certificates, you can reinstall them by using your backup file. You can save them in text files. The PKCS #11 certificate in PEM format looks similar to the following example:
-----BEGIN CERTIFICATE----- MIICjCCAZugAwIBAgICCEEwDQYJKoZIhKqvcNAQFBQAwfDELMAkGA1UEBhMCVVMx IzAhBgNVBAoGlBhbG9a2FWaWxsZGwSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX aWRnZXQgTW3FrZXJzICdSJyBVczEpMCcGAx1UEAxgVGVzdCBUXN0IFRlc3QgVGVz dCBUZXN0IFlc3QgQ0EswHhcNOTgwMzEyMDIzMzUWhcNOTgwMzI2MDIzMpzU3WjBP MQswCYDDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZN0b3J5VIFB1Ymxp Y2F0aW9uczEWMB4QGA1UEAxMNZHVgh49dq2tLNvbjTBaMA0GCSqGSIb3DQEBAQUA A0kAMEYkCQCksMR/aLGdfp4m0OiGgijG5KgOsyRNvwGYW7kfW+8mmijDtZaRjYNj jcgpF3VnlbxbclX9LVjjNLC5737XZdAgEDozYwpNDARBglghkgBhvhCEAQEEBAMC APAwHkwYDVR0jBBgwFAU67URjwCaGqZHUpSpdLxlzwJKiMwDQYJKoZIhQvcNAQEF BQADgYEAJ+BfVem3vBOPBveNdLGfjlb9hucgmaMcQa9FA/db8qimKT/ue9UGOJqL bwbMKBBopsDn56p2yV3PLIsBgrcuSoBCuFFnxBnqSiTS7YiYgCWqWaUA0ExJFmD6 6hBLseqkSWulk+hXHN7L/NrViO+7zNtKcaZLlFPf7d7j2MgX4Bo= -----END CERTIFICATE-----
This procedure explains how to install the CA-signed server certificate and trusted CA certificates for use with Directory Server.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Add the CA-signed server certificate.
$ dsadm add-cert instance-path cert-alias cert-file
Where cert-alias is a name that you provide to identify your certificate, and cert-file is the text file that contains the PKCS #11 certificate in PEM format.
For example, to install a CA-signed server certificate, you might use a command similar to this:
$ dsadm add-cert /local/dsInst server-cert /local/safeplace/serv-cert-file
The certificate is now installed, but is not yet trusted. To trust the CA-signed server certificate, you must install the Certificate Authority certificate.
Add the trusted Certificate Authority certificate.
$ dsadm add-cert --ca instance-path cert-alias cert-file
The --ca
option indicates that the certificate is a trusted Certificate Authority certificate.
For example, to install a trusted certificate from a Certificate Authority, you might use this command:
$ dsadm add-cert --ca /local/dsInst CA-cert /local/safeplace/ca-cert-file
Verify your installed certificates.
To list all server certificates and to display their validity dates and aliases, type:
$ dsadm list-certs instance-path
For example:
$ dsadm list-certs /local/ds1 Enter the certificate database password: Alias Valid from Expires on Self- Issued by Issued to signed? ----------- ---------- ---------- ------- ----------------- ----------------- serverCert 2000/11/10 2011/02/10 n CN=CA-Signed Cert, CN=Test Cert, 18:13 18:13 OU=CA,O=com dc=example,dc=com defaultCert 2006/05/18 2006/08/18 y CN=host1,CN=DS, Same as issuer 16:28 16:28 dc=example,dc=com 2 certificates found
By default, an instance of Directory Server contains a default server certificate called defaultCert
. The text Same as issuer
indicates that the default certificate is a self-signed server certificate.
To list trusted CA certificates, type:
$ dsadm list-certs -C instance-path
For example:
$ dsadm list-certs -C /local/ds1 Enter the certificate database password: Alias Valid from Expires on Self- Issued by Issued to signed? ------- ---------- ---------- ------- ----------------- -------------- CA-cert 2000/11/10 2011/02/10 y CN=Trusted CA Cert, Same as issuer 18:12 18:12 OU=CA,O=com 1 certificate found
To view the details of a certificate, including the certificate expiration date, type:
$ dsadm show-cert instance-path cert-alias
For example, to view a server certificate, type:
$ dsadm show-cert /local/ds1 "Server-Cert" Enter the certificate database password: Certificate: Data: Version: 3 (0x2) Serial Number: 2 (0x2) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: "CN=Server-Cert,O=Sun,C=US" Validity: Not Before: Fri Nov 10 18:12:20 2000 Not After : Thu Feb 10 18:12:20 2011 Subject: "CN=CA Server Cert,OU=ICNC,O=Sun,C=FR" Subject Public Key Info: Public Key Algorithm: PKCS #1 RSA Encryption RSA Public Key: Modulus: bd:76:fc:29:ca:06:45:df:cd:1b:f1:ce:bb:cc:3a:f7: 77:63:5a:82:69:56:5f:3d:3a:1c:02:98:72:44:36:e4: 68:8c:22:2b:f0:a2:cb:15:7a:c4:c6:44:0d:97:2d:13: b7:e3:bf:4e:be:b5:6a:df:ce:c4:c3:a4:8a:1d:fa:cf: 99:dc:4a:17:61:e0:37:2b:7f:90:cb:31:02:97:e4:30: 93:5d:91:f7:ef:b0:5a:c7:d4:de:d8:0e:b8:06:06:23: ed:5f:33:f3:f8:7e:09:c5:de:a5:32:2a:1b:6a:75:c5: 0b:e3:a5:f2:7a:df:3e:3d:93:bf:ca:1f:d9:8d:24:ed Exponent: 65537 (0x10001) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Signature: 85:92:42:1e:e3:04:4d:e5:a8:79:12:7d:72:c0:bf:45: ea:c8:f8:af:f5:95:f0:f5:83:23:15:0b:02:73:82:24: 3d:de:1e:95:04:fb:b5:08:17:04:1c:9d:9c:9b:bd:c7: e6:57:6c:64:38:8b:df:a2:67:f0:39:f9:70:e9:07:1f: 33:48:ea:2c:18:1d:f0:30:d8:ca:e1:29:ec:be:a3:43: 6f:df:03:d5:43:94:8f:ec:ea:9a:02:82:99:5a:54:c9: e4:1f:8c:ae:e2:e8:3d:50:20:46:e2:c8:44:a6:32:4e: 51:48:15:d6:44:8c:e6:d2:0d:5f:77:9b:62:80:1e:30 Fingerprint (MD5): D9:FB:74:9F:C3:EC:5A:89:8F:2C:37:47:2F:1B:D8:8F Fingerprint (SHA1): 2E:CA:B8:BE:B6:A0:8C:84:0D:62:57:85:C6:73:14:DE:67:4E:09:56 Certificate Trust Flags: SSL Flags: Valid CA Trusted CA User Trusted Client CA Email Flags: User Object Signing Flags: User
When your CA-signed server certificate (public key and private key) expires, renew it by using this procedure.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Obtain an updated CA-signed server certificate from your Certificate Authority.
When you receive the updated certificate, stop the server instance and install the certificate.
$ dsadm stop instance-path $ dsadm renew-cert instance-path cert-alias cert-file
Restart the server instance.
$ dsadm start instance-path
In some cases you might want to export the public and private keys of a certificate so that you can later import the certificate. For example, you might want the certificate to be used by another server.
The commands in this procedure can be used with certificates that contain wild cards, for example "cn=*,o=example"
.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Export the certificate.
$ dsadm export-cert [-o output-file] instance-path cert-alias
For example:
$ dsadm export-cert -o /tmp/first-certificate /local/ds1 "First Certificate" $ dsadm export-cert -o /tmp/first-ca-server-certificate /local/ds1/ defaultCert Choose the PKCS#12 file password: Confirm the PKCS#12 file password: $ ls /tmp first-ca-server-certificate
Import the certificate.
$ dsadm import-cert instance-path cert-file
For example, to import the certificate to a server instance:
$ dsadm import-cert /local/ds2 /tmp/first-ca-server-certificate Enter the PKCS#12 file password:
If you have imported the certificate to a server, configure the server to use the imported certificate.
$ dsconf set-server-prop -e -h host -p port ssl-rsa-cert-name:server-cert
By default, Directory Server manages the SSL certificate database password internally through a stored password. When managing certificates, the user does not need to type a certificate password or specify the password file. This option is not very secure because the password is only hidden, not encrypted.
However, if you want to have more control over the use of certificates, you can configure the server so that the user is prompted for a password on the command line. In this case, the user must type the certificate database password for all dsadm
subcommands except autostart
, backup
, disable-service
, enable-service
, info
, reindex
, restore
, and stop
. The certificate database is located in the directory instance-path
/alias
.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Stop the server.
$ dsadm stop instance-path
Set the password prompt flag to on
.
$ dsadm set-flags instance-path cert-pwd-prompt=on
You are asked to choose a new certificate password.
Start the server.
$ dsadm start instance-path
When you back up an instance of Directory Server, you back up the Directory Server configuration and the certificates. The backed up certificates are stored in the archive-path
/alias
directory.
For information about how to back up and restore Directory Server, see To Make a Backup for Disaster Recovery.
This section contains procedures that help you to choose encryption ciphers.
When a server instance is created, both an LDAP clear port and a secure LDAP port (LDAPS) are created by default. However, there might be situations where you want to disable non-SSL communications so that the server communicates only through SSL.
The SSL connection is enabled with a default self-signed certificate. If you want to, you can install your own certificates. For instructions on managing certificates and disabling SSL after the server has been started, see Chapter 5, "Directory Server Security". For an overview of certificates, certificate databases, and obtaining a CA-signed server certificate, see the Reference for Oracle Directory Server Enterprise Edition.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Disable the LDAP clear port.
To disable the non secure point, you must bind to the LDAP secure port. This example shows a bind to the default LDAP secure port, 1636
, on the host server host1
.
$ dsconf set-server-prop -h host1 -P 1636 ldap-port:disabled
Restart the server for the change to take effect.
$ dsadm restart /local/dsInst
You can now no longer bind on the non secure port 1389.
A cipher is the algorithm used to encrypt and decrypt data. Generally speaking, the more bits that a cipher uses during encryption, the stronger or more secure the encryption is. Ciphers for SSL are also identified by the type of message authentication used. Message authentication is another algorithm that computes a checksum
that guarantees data integrity.
When a client initiates an SSL connection with a server, the client and server must agree on a cipher to use to encrypt information. In any two-way encryption process, both parties must use the same cipher. The cipher used depends upon the current order of the cipher list kept by the server. The server chooses the first cipher presented by the client that matches a cipher in its list. The default cipher value for Directory Server is all
, which means all known secure ciphers supported by the underlying SSL library. However, you can modify this value to only accept certain ciphers.
For more information about the ciphers that are available with Directory Server, see the Reference for Oracle Directory Server Enterprise Edition.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Make sure that SSL is enabled for your server.
View the available SSL ciphers.
$ dsconf get-server-prop -h host -p port ssl-supported-ciphers ssl-supported-ciphers : TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ssl-supported-ciphers : TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ssl-supported-ciphers : TLS_DHE_RSA_WITH_AES_256_CBC_SHA ssl-supported-ciphers : TLS_DHE_DSS_WITH_AES_256_CBC_SHA ...
If you want to keep a copy of non-encrypted data, export the data before setting the SSL ciphers.
See Exporting to LDIF.
Set the SSL ciphers.
$ dsconf set-server-prop -h host -p port ssl-cipher-family:cipher
For example, to set the cipher family to SSL_RSA_WITH_RC4_128_MD5
and SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
, type:
$ dsconf set-server-prop -h host1 -P 1636 ssl-cipher-family:SSL_RSA_WITH_RC4_128_MD5 \
ssl-cipher-family:SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
Enter "cn=Directory Manager" password:
Before setting SSL configuration, export Directory Server data.
Do you want to continue [y/n] ? y
Directory Server must be restarted for changes to take effect.
Add an SSL cipher to an existing list.
If you already have a list of ciphers specified, and you want to add a cipher, use this command:
$ dsconf set-server-prop -h host -p port ssl-cipher-family+:cipher
For example, to add the SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
cipher, type:
$ dsconf set-server-prop -h host1 -P 1636 \ ssl-cipher-family+:SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
Restart the server for the changes to take effect.
$ dsadm restart /local/dsInst
The security model that is applied to clients is defined through a combination of the credential level and the authentication method.
Directory Server supports the following credential levels:
Anonymous. Allowing anonymous access for certain parts of the directory implies that anyone with access to the directory has read access.
If you use an anonymous credential level, you need to allow read access to all the LDAP naming entries and attributes.
Caution:
Do not allow anonymous write access to a directory because anyone could change information in the DIT to which they have write access, including another user's password, or their own identity.
Proxy. The client authenticates or binds to the directory using a proxy account.
This proxy account can be any entry that is allowed to bind to the directory. The proxy account needs sufficient access to perform the naming service functions on the directory. You need to configure the proxyDN
and proxyPassword
on every client using the proxy credential level. The encrypted proxyPassword
is stored locally on the client.
Proxy anonymous. A multi-valued entry in which more than one credential level is defined.
A client assigned the proxy anonymous level will first attempt to authenticate with its proxy identity. If the client is unable to authenticate as the proxy user for whatever reason (user lockout, password expired, for example), then the client will use anonymous access. This might lead to a different level of service, depending on how the directory is configured.
Client authentication is a mechanism for the server to verify the identity of the client.
Client authentication can be performed in one of the following ways:
By providing a DN and a password.
Through a certificate presented by the client.
Certificate-based authentication uses the client certificate that is obtained through the SSL protocol to find a user entry for identification. In certificate-based authentication, the client sends an SASL bind request specifying an external mechanism. The bind request relies on the SSL authentication mechanism that has already been established.
Through a SASL-based mechanism.
On all operating systems, SASL through DIGEST-MD5.
On the Solaris Operating System, SASL through the GSSAPI mechanism which allows the authentication of a client through Kerberos V5.
When using either of the two SASL mechanisms, the server must also be configured to perform identity mapping. The SASL credentials are called the Principal. Each mechanism must have specific mappings to determine the bind DN from the contents of the Principal. When the Principal is mapped to a single user entry and the SASL mechanism validates that user's identity, the user's DN is the bind DN for the connection.
Through SSL client authentication mode.
Use SSL client authentication when you want all clients to be authorized at the SSL layer. The client application authenticates by sending its SSL certificate to the server. You specify whether the server allows, requires, or does not allow SSL client authentication using the SSL-client-auth-mode
flag. By default, clients are allowed to authenticate.
This section provides the following information about configuring the two SASL mechanisms on Directory Server.
For more information about configuring security, see Configuring LDAP Clients to Use Security.
Before configuring the SASL mechanism, you must specify whether you require encryption or not. Requirements for SASL encryption are set by the maximum and minimum Strength Security Factor (SSF).
The attributes dsSaslMinSSF and dsSaslMaxSSF represent the encryption key length, and they are stored in cn=SASL, cn=security, cn=config
.
The server allows any level of encryption, including no encryption. This means that Directory Server accepts dsSaslMinSSF
and dsSaslMaxSSF
values greater than 256. However, no SASL mechanisms currently support an SSF greater than 128. Directory Server negotiates these values down to the highest SSF possible (128). Therefore, the highest actual SSF might be less than the configured maximum, depending on the underlying mechanisms available.
SASL security factor authentication depends two main items: the minimum and maximum factors requested by the server and client applications, and the available encryption mechanisms, which are provided by the underlying security components. In summary, the server and client attempt to use the highest available security factor that is less than or equal to the maximum factors set on both, but greater than or equal to the minimum factors on both.
The default minimum SASL security factor for Directory Server, dsSaslMinSSF
, is 0
, meaning no protection. The actual minimum depends on the client setting, unless you change the minimum for Directory Server. In practice, you should set the minimum to the lowest level that you actually want the server and client to use. If the server and client fail to negotiate a mechanism that meets the minimum requirements, the connection is not established.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
To require SASL encryption, set the dsSaslMinSSF
value to the minimum encryption required.
$ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: cn=SASL, cn=security, cn=config changetype: modify replace: dsSaslMinSSF dsSaslMinSSF: 128 ^D
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
To disallow SASL encryption, set both the dsSaslMinSSF
and dsSaslMaxSSF
values to zero.
$ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: cn=SASL, cn=security, cn=config changetype: modify replace: dsSaslMinSSF dsSaslMinSSF: 0 replace: dsSaslMaxSSF dsSaslMaxSSF: 0
The DIGEST-MD5 mechanism authenticates clients by comparing a hashed value sent by the client with a hash of the user's password. However, because the mechanism must read user passwords, all users that want to be authenticated through DIGEST-MD5 must have {CLEAR}
passwords in the directory. When storing {CLEAR}
passwords in the directory, you must ensure that access to password values is properly restricted through ACIs, as described in Chapter 6, "Directory Server Access Control". In addition, you need to configure attribute encryption in the suffix, as described in Encrypting Attribute Values.
The following procedure explains how to configure Directory Server to use DIGEST-MD5.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Use the ldapsearch
command to verify that DIGEST-MD5
is a value of the supportedSASLMechanisms
attribute on the root entry.
For example, the following command shows which SASL mechanisms are enabled:
$ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \ -s base -b "" "(objectclass=*)" supportedSASLMechanisms Enter bind password: dn: supportedSASLMechanisms: EXTERNAL supportedSASLMechanisms: DIGEST-MD5 supportedSASLMechanisms: GSSAPI
If DIGEST-MD5 is not enabled, enable it.
$ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: cn=SASL, cn=security, cn=config changetype: modify add: dsSaslPluginsEnable dsSaslPluginsEnable: DIGEST-MD5 - replace: dsSaslPluginsPath dsSaslPluginsPath: SASL-library
where SASL-library is the following:
install-path
/lib/private/
Use the default identity mapping for DIGEST-MD5, or create new ones.
For information, see DIGEST-MD5 Identity Mappings.
Ensure that the password is stored in {CLEAR}
for all users who will access the server through SSL using DIGEST-MD5.
See Chapter 8, "Directory Server Password Policy" for password storage schemes.
If you modified the SASL configuration entry or one of the DIGEST-MD5 identity mapping entries, restart Directory Server.
Identity mappings for SASL mechanisms try to match the credentials of the SASL identity with a user entry in the directory. Authentication fails if the mapping cannot find a DN that corresponds to the SASL identity. See the Reference for Oracle Directory Server Enterprise Edition for a complete description of this mechanism.
The SASL identity is a string called the Principal that represents a user in a format specific to each mechanism. In DIGEST-MD5, clients should create a Principal that contains either a dn:
prefix and an LDAP DN or a u:
prefix followed by any text determined by the client. During the mapping, the Principal that is sent by the client is available in the ${Principal}
placeholder.
The following entry in your server configuration is the default identity mapping for DIGEST-MD5:
dn: cn=default,cn=DIGEST-MD5,cn=identity mapping,cn=config objectClass: top objectClass: nsContainer objectClass: dsIdentityMapping objectClass: dsPatternMatching cn: default dsMatching-pattern: \${Principal} dsMatching-regexp: dn:(.*) dsMappedDN: \$1
This identity mapping assumes that the dn
field of the Principal contains the exact DN of an existing user in the directory.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Edit the default mapping entry or create new mapping entries under cn=DIGEST-MD5,cn=identity mapping,cn=config
.
The following command shows how this mapping would be defined:
$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - Enter bind password: dn: cn=unqualified-username,cn=DIGEST-MD5,cn=identity mapping cn=config objectclass: dsIdentityMapping objectclass: dsPatternMatching objectclass: nsContainer objectclass: top cn: unqualified-username dsMatching-pattern: \${Principal} dsMatching-regexp: u:(.*)@(.*)\\.com dsSearchBaseDN: dc=\$2 dsSearchFilter: (uid=\$1)
Restart Directory Server for your new mappings to take effect.
The Generic Security Service API (GSSAPI) over SASL allows you to use a third-party security system such as Kerberos V5 to authenticate clients. The GSSAPI library is available for the Solaris and Linux operating systems. Oracle recommends that you install the Kerberos V5 implementation on a Sun Enterprise Authentication Mechanism (SEAM) server.
The server uses the GSSAPI to validate the identity of the user. Then, the SASL mechanism applies the GSSAPI mapping rules to obtain a DN that is the bind DN for all operations during this connection.
Configure the Kerberos software according to the manufacturer's instructions. If you are using the Sun Enterprise Authentication Mechanism 1.0.1 server, use this procedure.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Before You Begin
On Solaris, Kerberos 5 packages are installed by default.
On Linux, be sure the following Kerberos 5 packages are installed:
krb-workstation-1.6.1-36.e15
krb5-libs-1.6.136e15
For more information, see the operating system documentation.
Edit the configuration file.
Solaris: /etc/krb5/krb5.config
Linux: /etc/krb5.config
Create the Kerberos database for storing users and services.
In the database, create the Principal for the LDAP service.
$ ldap/server-FQDN@realm
where server-FQDN is the fully qualified domain name of your Directory Server.
Start the Kerberos daemon processes.
Note:
The DNS must be configured on the host machine.
Refer to your software documentation for detailed instructions for each of these steps. Also, see Example Configuration of Kerberos Authentication Using GSSAPI With SASL.
The following procedure explains how to configure Directory Server to use GSSAPI:
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create the default identity mapping for GSSAPI and any custom mappings as described in GSSAPI Identity Mappings.
Create a keytab to store the service keys.
Your LDAP service key is stored in the keytab.
Ensure that the keytab is only readable by the Directory Server user.
Create a dedicated file for storing the keytab. Example:/var/dsee7/ds7.keytab
Change the file name to be different from the default keytab file name.
Set the environment variable KRB5_KTNAME
to ensure that the new keytab is used rather than the default keytab.
If you modified the SASL configuration entry or one of the GSSAPI identity mapping entries, restart Directory Server.
Note that the DNS must be configured on the host machine.
Identity mappings for SASL mechanisms try to match credentials of the SASL identity with a user entry in the directory. Authentication fails if the mapping cannot find a DN that corresponds to the SASL identity.
The SASL identity is a string called the Principal that represents a user in a format specific to each mechanism. In Kerberos using GSSAPI, the Principal is an identity with the format uid [/
instance][@
realm]
. The uid can contain an optional instance identifier followed by an optional realm that is often a domain name. For example, the following strings are all valid user Principals:
bjensen bjensen/Sales bjensen@EXAMPLE.COM bjensen/Sales@EXAMPLE.COM
Initially, no GSSAPI mapping is defined in the directory. Define a default mapping and any custom mappings that you need according to how your clients define the Principal that your clients use.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create new mapping entries under cn=GSSAPI,cn=identity mapping, cn=config
.
See the Reference for Oracle Directory Server Enterprise Edition for the definition of the attributes in an identity mapping entry. Examples of GSSAPI mappings are located in instance-path
/ldif/identityMapping_Examples.ldif
.
The default GSSAPI mapping in this file assumes that the Principal contains only a user ID. This mapping determines a user in a fixed branch of the directory:
dn: cn=default,cn=GSSAPI,cn=identity mapping,cn=config objectclass: dsIdentityMapping objectclass: nsContainer objectclass: top cn: default dsMappedDN: uid=\${Principal},ou=people,dc=example,dc=com
Another example in this file shows how to determine the user ID when the user ID is contained in a Principal that includes a known realm.
dn: cn=same_realm,cn=GSSAPI,cn=identity mapping,cn=config objectclass: dsIdentityMapping objectclass: dsPatternMatching objectclass: nsContainer objectclass: top cn: same_realm dsMatching-pattern: \${Principal} dsMatching-regexp: (.*)@EXAMPLE.COM dsMappedDN: uid=$1,ou=people,dc=EXAMPLE,dc=COM
Restart Directory Server for your new mappings to take effect.
The following sections explain how to configure and use SSL in LDAP clients that want to establish secure connections with Directory Server. In an SSL connection, the server sends its certificate to the client. The client must first authenticate the server by trusting its certificate. Then, the client can optionally initiate one of the client authentication mechanisms by sending its own certificate or information for one of the two SASL mechanism. The SASL mechanisms are DIGEST-MD5 and GSSAPI using Kerberos V5.
The following sections use the ldapsearch
tool as an example of an SSL-enabled LDAP client.
To configure SSL connections on other LDAP clients, refer to the documentation provided with your application.
Note:
Some client applications implement SSL but do not verify that the server has a trusted certificate. These client applications use the SSL protocol to provide data encryption but cannot guarantee confidentiality nor protect against impersonation.
The following sections explain how to configure LDAP clients to use security:
When using the DIGEST-MD5 mechanism in clients, you do not need to install a user certificate. However, if you want to use encrypted SSL connections, you must still trust the server certificate as described in Managing Certificates.
A realm defines the namespace from which the authentication identity is selected. In DIGEST-MD5 authentication, you must authenticate to a specific realm.
Directory Server uses the fully qualified host name of the machine as the default realm for DIGEST-MD5. The server uses the lowercase value of the host name that is found in the nsslapd-localhost
configuration attribute.
If you do not specify a realm, the default realm offered by the server is used.
In the UNIX environment, you must set the SASL-PATH
environment variable so that the LDAP tools can find the DIGEST-MD5 libraries. The DIGEST-MD5 library is a shared library that is dynamically loaded by the SASL plug-in. Set the SASL_PATH
environment variable as follows:
export SASL_PATH=SASL-library
This path assumes that Directory Server is installed on the same host where the LDAP tools are invoked.
ldapsearch
CommandYou can perform DIGEST-MD5 client authentication without using SSL. The following example uses the default DIGEST-MD5 identity mapping to determine the bind DN:
$ ldapsearch -h host1 -p 1389 \ -o mech=DIGEST-MD5 [ \ -o realm="example.com"] \ -o authid="dn:uid=bjensen,dc=example,dc=com" \ -w - \ -o authzid="dn:uid=bjensen,dc=example,dc=com" \ -o secProp="minssf=56,maxssf=256,noplain" \ -b "dc=example,dc=com" "(givenname=Richard)"
The preceding example shows the use of the -o
(lowercase letter o) option to specify SASL options. The realm
is optional, but if specified, it must be the fully qualified domain name of the server host machine. The authid
and authzid
must both be present and identical, although the authzid
intended for proxy operations is not used. The -w
password option applies to the authid
.
The value of authid
is the Principal used in identity mapping. The authid
should contain either the dn:
prefix followed by a valid user DN in the directory, or the u:
prefix followed by any string determined by the client. This use of authid
allows you to use the mappings that are shown in DIGEST-MD5 Identity Mappings.
The most common configuration is for an SSL connection to provide encryption over the LDAPS secure port and DIGEST-MD5 to provide the client authentication. The following example performs the same operation over SSL:
$ ldapsearch -h host1 -P 1636 \ -Z -P .mozilla/bjensen/BJE6001.slt/cert8.db \ -N "cert-example" -w - \ -o mech=DIGEST-MD5 [-o realm="example.com"] \ -o authid="dn:uid=bjensen,dc=example,dc=com" \ -o authzid="dn:uid=bjensen,dc=example,dc=com" \ -o secProp="minssf=0,maxssf=0,noplain" \ -b "dc=example,dc=com" "(givenname=Richard)"
In this example, the -N
and -w
options are required by the ldapsearch
command, as the operation is performed over SSL. However , these options are not used for client authentication. Instead, the server performs another DIGEST-MD5 identity mapping of the Principal in the authid
value.
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 and for Linux, there are some differences. The configuration file format is slightly different, commands and configuration files have different paths, 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 Kerberos client configuration file provides information that Kerberos clients require in order to communicate with the KDC:
/etc/krb5/krb5.conf
/etc/krb5.conf
Edit the Kerberos client 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 following is an example of an updated Kerveros client configuration file on Solaris:
Example 5-1 Edited Kerberos Client Configuration File /etc/krb5/krb5.conf
on Solaris
#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 th/etc/krb5/kadm5.acl
configuration file. The updated file should look like the following example.
Edit the /etc/krb5/kdc.conf
file to replace "___default_realm___"
with "EXAMPLE.COM"
. The updated file should look like the following example.
Example 5-3 Edited KDC Server Configuration File /etc/krb5/kdc.conf
on Solaris
# 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 }
$ 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.
$ 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
.
$ 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:
$ 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:
$ 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 Oracle Directory Server Enterprise Edition 11g R1 (11.1.1.6) and the latest patches. Following are example settings.
Variable Type | Example Value |
---|---|
Fully qualified computer name |
|
Installation directory |
|
Instance path |
|
Server user |
|
Server group |
|
Server port |
|
Suffix |
|
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.
Example 5-4 gssapi.ldif
File Contents
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: SASL-library
where SASL-library is the following:
install-path
/lib/private/
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:
$ kadmin -p kws/admin Enter Password: secret kadmin: ktadd -k /local/dsInst/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/dsInst/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/dsInst/config /ldap.keytab $ chmod 600 /local/dsInst/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/dsInst
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.
Example 5-5 New testuser.ldif
File
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/dsInst/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.
Pass-through authentication (PTA) is a mechanism by which bind requests are filtered by bind DN. One Directory Server (the delegator) receives the bind request and, based on the filter, can consult another Directory Server (the delegate) to authenticate bind requests. As part of this functionality, the PTA plug-in enables the delegator Directory Server to accept simple password-based bind operations for entries that are not necessarily stored in its local database.
The PTA plug-in is also used by DSCC for private communication with the server. When a server instance is registered in DSCC, the PTA plug-in is enabled and the DSCC URL is added as an argument.
$ dsconf get-plugin-prop -h host -p port "Pass Through Authentication" argument : ldap://dscc_host:3998/cn=dscc depends-on-named : depends-on-type : desc : pass through authentication plugin enabled : on feature : passthruauth init-func : passthruauth_init lib-path : install-path/lib/passthru-plugin.so type : preoperation vendor : Sun Microsystems, Inc. version : 7.0
Note:
If your server is registered in DSCC and you need to use PTA, you must preserve the following settings while modifying the PTA plug-in.
Keep the enabled
property on
.
Keep the DSCC URL in the argument, although you can add other values to the argument
property.
If the PTA plug-in is disabled or the DSCC URL is removed from the argument, the server instance will appear as inaccessible
in DSCC. If this happens, DSCC will automatically give you the option of resetting the PTA plug-in.
You can also fix this problem by unregistering and registering the Directory Server instance into DSCC. To perform these operations, you can use either DSCC or the dsccreg remove-server
and dsccreg add-server
commands. For more information about the dsccreg
command, see dsccreg.
PTA plug-in configuration information is specified in the cn=Pass Through Authentication,cn=plugins,cn=config
entry on the PTA server.
The PTA plug-in is a system plug-in, which is disabled by default. It can be enabled and setup using the dsconf
command or using DSCC.
Run the following dsconf
commands:
$ dsconf enable-plugin -h PTAhost -p port "Pass Through Authentication" $ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication" \ argument:"ldap[s]://authenticatingHost[:port]/PTAsubtree options"
The plug-in argument specifies the LDAP URL identifying the hostname of the authenticating directory server, an optional port, and the PTA subtree. If no port is specified, the default port is 389
with LDAP and 636
with LDAPS. You may also set the optional connection parameters described in the following sections. If the PTAsubtree exists in the PTAhost, the plug-in will not pass the bind request to the authenticatingHost, and the bind will be processed locally without any pass-through.
Restart the server as described in Starting, Stopping, and Restarting a Directory Server Instance.
Because the PTA plug-in must send bind credentials including the password to the authenticating directory, we recommend using a secure connection. To configure the PTA directory to communicate with the authenticating directory over SSL:
Configure and enable SSL in both the PTA and authenticating directories, as described in Chapter 5, "Directory Server Security".
Create or modify the PTA plug-in configuration to use LDAPS and the secure port in the LDAP URL, for example:
ldaps://host:secure-port/subtree
The PTA plug-in arguments accept a set of optional connection parameters after the LDAP URL:
http[s]://host:port/subtree [maxconns,maxops,timeout,ldapver,connlife]
The parameters must be given in the order shown. Although these parameters are optional, if you specify one of them, you must specify them all. If you do not want to customize all parameters, specify their default values given below. Make sure there is a space between the subtree parameter and the optional parameters.
You can configure the following optional parameters for each LDAP URL:
maxconns
- The maximum number of connections the PTA server can open simultaneously to the authenticating server. This parameter limits the number of simultaneous binds that can be passed-through to the authenticating server. The default value is 3
.
maxops
- The maximum number of bind requests the PTA directory server can send simultaneously to the authenticating directory server within a single connection. This parameter further limits the number of simultaneous pass-through authentications. The default is value is 5
.
timeout
- The maximum delay in seconds that you want the PTA server to wait for a response from the authenticating server. The default value is 300
seconds (five minutes).
ldapver
- The version of the LDAP protocol you want the PTA server to use when connecting to the authenticating server. The allowed values are 2
for LDAPv2 and 3
for LDAPv3. The default value is 3
.
connlife
- The time limit in seconds within which the PTA server will reuse a connection to the authenticating server. If a bind in the PTA subtree is requested by a client after this time has expired, the server closes the PTA connection and opens a new one. The server will not close the connection unless a bind request is initiated and the server determines the timeout has been exceeded. If you do not specify this option, or if only one authenticating server is listed in the LDAP URL, no time limit will be enforced. If two or more hosts are listed, the default is 300
seconds (five minutes).
Note:
While setting the argument
property using the dsconf
command, put the value in double quotes to protect spaces. For example:
dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\ argument:"ldaps://eastbak.example.com/ou=East,ou=People,dc=example,dc=com\ 3,5,300,3,300"
You may configure the PTA plug-in with multiple arguments to specify multiple authenticating servers, multiple PTA subtrees, or both. Each argument contains one LDAP URL and may have its own set of connection options.
When there are multiple authenticating servers for the same PTA subtree, they act as failover servers. The plug-in will establish connections to them in the order listed whenever a PTA connection reaches the timeout limit. If all connections time out, the authentication fails.
When there are multiple PTA subtrees defined, the plug-in will pass-through the authentication request to the corresponding server according to the bind DN. The following example shows four PTA plug-in arguments that define two PTA subtrees, each with a failover server for authentication and server-specific connection parameters:
$ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\ argument:"ldaps://configdir.example.com/o=example.com\ 10,10,60,3,300" $ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\ argument+:"ldaps://configbak.example.com/o=example.com\ 10,10,60,3,300" $ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\ argument+:"ldaps://east.example.com/ou=East,ou=People,dc=example,dc=com\ 10,10,60,3,300" $ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\ argument+:"ldaps://eastbak.example.com/ou=East,ou=People,dc=example,dc=com\ 10,10,60,3,300"