From 15b7e405ff7b62ab96af45999d1350455948e602 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Mon, 16 Jun 2014 13:15:33 -0400 Subject: [PATCH] Document LDAP SASL configuration Document the LDAP SASL profile tags and DB options. For consistency, also condense the kdc.conf documentation for the two bind DN variables into one entry. ticket: 7944 --- doc/admin/admin_commands/kadmin_local.rst | 29 ++++++++-- doc/admin/admin_commands/kdb5_ldap_util.rst | 14 +++-- doc/admin/conf_files/kdc_conf.rst | 60 ++++++++++++++++----- 3 files changed, 80 insertions(+), 23 deletions(-) diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst index e7e2d5a9c7..8409303ded 100644 --- a/doc/admin/admin_commands/kadmin_local.rst +++ b/doc/admin/admin_commands/kadmin_local.rst @@ -162,13 +162,32 @@ Supported options for the LDAP module are: **-x binddn=**\ *bind_dn* Specifies the DN used to bind to the LDAP server. - **-x bindpwd=**\ *bind_password* - Specifies the password for the above mentioned binddn. Using - this option may expose the password to other users on the - system via the process list; to avoid this, instead stash the - password using the **stashsrvpw** command of + **-x bindpwd=**\ *password* + Specifies the password or SASL secret used to bind to the LDAP + server. Using this option may expose the password to other + users on the system via the process list; to avoid this, + instead stash the password using the **stashsrvpw** command of :ref:`kdb5_ldap_util(8)`. + **-x sasl_mech=**\ *mechanism* + Specifies the SASL mechanism used to bind to the LDAP server. + The bind DN is ignored if a SASL mechanism is used. New in + release 1.13. + + **-x sasl_authcid=**\ *name* + Specifies the authentication name used when binding to the + LDAP server with a SASL mechanism, if the mechanism requires + one. New in release 1.13. + + **-x sasl_authzid=**\ *name* + Specifies the authorization name used when binding to the LDAP + server with a SASL mechanism. New in release 1.13. + + **-x sasl_realm=**\ *realm* + Specifies the realm used when binding to the LDAP server with + a SASL mechanism, if the mechanism uses one. New in release + 1.13. + **-x debug=**\ *level* sets the OpenLDAP client library debug level. *level* is an integer to be interpreted by the library. Debugging messages diff --git a/doc/admin/admin_commands/kdb5_ldap_util.rst b/doc/admin/admin_commands/kdb5_ldap_util.rst index 4516e048e2..cbf313f55a 100644 --- a/doc/admin/admin_commands/kdb5_ldap_util.rst +++ b/doc/admin/admin_commands/kdb5_ldap_util.rst @@ -273,7 +273,7 @@ stashsrvpw **stashsrvpw** [**-f** *filename*] - *servicedn* + *name* Allows an administrator to store the password for service object in a file so that KDC and Administration server can use it to authenticate @@ -283,9 +283,15 @@ to the LDAP server. Options: Specifies the complete path of the service password file. By default, ``/usr/local/var/service_passwd`` is used. -*servicedn* - Specifies Distinguished Name (DN) of the service object whose - password is to be stored in file. +*name* + Specifies the name of the object whose password is to be stored. + If :ref:`krb5kdc(8)` or :ref:`kadmind(8)` are configured for + simple binding, this should be the distinguished name it will + use as given by the **ldap_kdc_dn** or **ldap_kadmind_dn** + variable in :ref:`kdc.conf(5)`. If the KDC or kadmind is + configured for SASL binding, this should be the authentication + name it will use as given by the **ldap_kdc_sasl_authcid** or + **ldap_kadmind_sasl_authcid** variable. Example:: diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst index 987826642b..6a05cc4d5e 100644 --- a/doc/admin/conf_files/kdc_conf.rst +++ b/doc/admin/conf_files/kdc_conf.rst @@ -342,7 +342,15 @@ definitions of these relations. * **ldap_kerberos_container_dn** * **ldap_kdc_dn** +* **ldap_kdc_sasl_authcid** +* **ldap_kdc_sasl_authzid** +* **ldap_kdc_sasl_mech** +* **ldap_kdc_sasl_realm** * **ldap_kadmind_dn** +* **ldap_kadmind_sasl_authcid** +* **ldap_kadmind_sasl_authzid** +* **ldap_kadmind_sasl_mech** +* **ldap_kadmind_sasl_realm** * **ldap_service_password_file** * **ldap_servers** * **ldap_conns_per_server** @@ -394,18 +402,41 @@ The following tags may be specified in a [dbmodules] subsection: This LDAP-specific tag indicates the number of connections to be maintained per LDAP server. -**ldap_kadmind_dn** - This LDAP-specific tag indicates the default bind DN for the - :ref:`kadmind(8)` daemon. kadmind does a login to the directory - as this object. This object should have the rights to read and - write the Kerberos data in the LDAP database. - -**ldap_kdc_dn** - This LDAP-specific tag indicates the default bind DN for the - :ref:`krb5kdc(8)` daemon. The KDC does a login to the directory - as this object. This object should have the rights to read the - Kerberos data in the LDAP database, and to write data unless - **disable_lockout** and **disable_last_success** are true. +**ldap_kdc_dn** and **ldap_kadmind_dn** + These LDAP-specific tags indicate the default DN for binding to + the LDAP server. The :ref:`krb5kdc(8)` daemon uses + **ldap_kdc_dn**, while the :ref:`kadmind(8)` daemon and other + administrative programs use **ldap_kadmind_dn**. The kadmind DN + must have the rights to read and write the Kerberos data in the + LDAP database. The KDC DN must have the same rights, unless + **disable_lockout** and **disable_last_success** are true, in + which case it only needs to have rights to read the Kerberos data. + These tags are ignored if a SASL mechanism is set with + **ldap_kdc_sasl_mech** or **ldap_kadmind_sasl_mech**. + +**ldap_kdc_sasl_mech** and **ldap_kadmind_sasl_mech** + These LDAP-specific tags specify the SASL mechanism (such as + ``EXTERNAL``) to use when binding to the LDAP server. New in + release 1.13. + +**ldap_kdc_sasl_authcid** and **ldap_kadmind_sasl_authcid** + These LDAP-specific tags specify the SASL authentication identity + to use when binding to the LDAP server. Not all SASL mechanisms + require an authentication identity. If the SASL mechanism + requires a secret (such as the password for ``DIGEST-MD5``), these + tags also determine the name within the + **ldap_service_password_file** where the secret is stashed. New + in release 1.13. + +**ldap_kdc_sasl_authzid** and **ldap_kadmind_sasl_authzid** + These LDAP-specific tags specify the SASL authorization identity + to use when binding to the LDAP server. In most circumstances + they do not need to be specified. New in release 1.13. + +**ldap_kdc_sasl_realm** and **ldap_kadmind_sasl_realm** + These LDAP-specific tags specify the SASL realm to use when + binding to the LDAP server. In most circumstances they do not + need to be set. New in release 1.13. **ldap_kerberos_container_dn** This LDAP-specific tag indicates the DN of the container object @@ -421,8 +452,9 @@ The following tags may be specified in a [dbmodules] subsection: **ldap_service_password_file** This LDAP-specific tag indicates the file containing the stashed passwords (created by ``kdb5_ldap_util stashsrvpw``) for the - **ldap_kadmind_dn** and **ldap_kdc_dn** objects. This file must - be kept secure. + **ldap_kdc_dn** and **ldap_kadmind_dn** objects, or for the + **ldap_kdc_sasl_authcid** or **ldap_kadmind_sasl_authcid** names + for SASL authentication. This file must be kept secure. The following tag may be specified directly in the [dbmodules] section to control where database modules are loaded from: -- 2.47.2