diff options
author | Greg Hudson <ghudson@mit.edu> | 2019-09-10 01:12:43 -0400 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2019-09-19 16:52:00 -0400 |
commit | ca1057fe6a03b6679b7907ee41b8abd444acc70d (patch) | |
tree | 03bf8d03e10095aa355142d6bd8b139bee679b56 /doc | |
parent | 2977b8e88002fc928a0ff3757098b34ca83645ef (diff) | |
download | krb5-ca1057fe6a03b6679b7907ee41b8abd444acc70d.zip krb5-ca1057fe6a03b6679b7907ee41b8abd444acc70d.tar.gz krb5-ca1057fe6a03b6679b7907ee41b8abd444acc70d.tar.bz2 |
Update LDAP KDB module documentation
Remove ldapbackend.rst, as it is largely redundant with conf_ldap.rst.
Simplify conf_ldap.rst, using kerberos.openldap.ldif (added by ticket
8529) and removing unnecessary command arguments. Mention the
possibility of using SASL authentication (added by ticket 7944) as an
alternative to binding with DN and password. Remove unnecessary
access rights.
In kdc_conf.rst, remove ldap_servers from the list of relations read
from [dbdefaults], as it is only read from the realm's database
configuration section.
In kdb5_ldap_util.rst, document "-r" as a global parameter, as it
applies in some fashion to all commands. Make the same changes to the
kdb5_ldap_util usage message, and make it fit within 80 columns.
Reported by Dilyan Palauzov.
ticket: 8831 (new)
tags: pullup
target_version: 1.17-next
Diffstat (limited to 'doc')
-rw-r--r-- | doc/admin/admin_commands/kdb5_ldap_util.rst | 84 | ||||
-rw-r--r-- | doc/admin/advanced/index.rst | 1 | ||||
-rw-r--r-- | doc/admin/advanced/ldapbackend.rst | 143 | ||||
-rw-r--r-- | doc/admin/conf_files/kdc_conf.rst | 1 | ||||
-rw-r--r-- | doc/admin/conf_ldap.rst | 134 |
5 files changed, 84 insertions, 279 deletions
diff --git a/doc/admin/admin_commands/kdb5_ldap_util.rst b/doc/admin/admin_commands/kdb5_ldap_util.rst index 343df4d..73a920f 100644 --- a/doc/admin/admin_commands/kdb5_ldap_util.rst +++ b/doc/admin/admin_commands/kdb5_ldap_util.rst @@ -29,6 +29,9 @@ COMMAND-LINE OPTIONS .. _kdb5_ldap_util_options: +**-r** *realm* + Specifies the realm to be operated on. + **-D** *user_dn* Specifies the Distinguished Name (DN) of the user who has sufficient rights to perform the operation on the LDAP server. @@ -38,8 +41,12 @@ COMMAND-LINE OPTIONS recommended. **-H** *ldapuri* - Specifies the URI of the LDAP server. It is recommended to use - ``ldapi://`` or ``ldaps://`` to connect to the LDAP server. + Specifies the URI of the LDAP server. + +By default, kdb5_ldap_util operates on the default realm (as specified +in :ref:`krb5.conf(5)`) and connects and authenticates to the LDAP +server in the same manner as :ref:kadmind(8)` would given the +parameters in :ref:`dbdefaults` in :ref:`kdc.conf(5)`. .. _kdb5_ldap_util_options_end: @@ -58,9 +65,9 @@ create [**-containerref** *container_reference_dn*] [**-k** *mkeytype*] [**-kv** *mkeyVNO*] + [**-M** *mkeyname*] [**-m|-P** *password*\|\ **-sf** *stashfilename*] [**-s**] - [**-r** *realm*] [**-maxtktlife** *max_ticket_life*] [**-maxrenewlife** *max_renewable_ticket_life*] [*ticket_flags*] @@ -92,6 +99,11 @@ Creates realm in directory. Options: Specifies the version number of the master key in the database; the default is 1. Note that 0 is not allowed. +**-M** *mkeyname* + Specifies the principal name for the master key in the database. + If not specified, the name is determined by the + **master_key_name** variable in :ref:`kdc.conf(5)`. + **-m** Specifies that the master database password should be read from the TTY rather than fetched from a file on the disk. @@ -100,9 +112,6 @@ Creates realm in directory. Options: Specifies the master database password. This option is not recommended. -**-r** *realm* - Specifies the Kerberos realm of the database. - **-sf** *stashfilename* Specifies the stash file of the master database password. @@ -125,7 +134,7 @@ Creates realm in directory. Options: Example:: kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - create -subtrees o=org -sscope SUB -r ATHENA.MIT.EDU + -r ATHENA.MIT.EDU create -subtrees o=org -sscope SUB Password for "cn=admin,o=org": Initializing database for realm 'ATHENA.MIT.EDU' You will be prompted for the database Master Password. @@ -144,7 +153,6 @@ modify [**-subtrees** *subtree_dn_list*] [**-sscope** *search_scope*] [**-containerref** *container_reference_dn*] - [**-r** *realm*] [**-maxtktlife** *max_ticket_life*] [**-maxrenewlife** *max_renewable_ticket_life*] [*ticket_flags*] @@ -165,9 +173,6 @@ Modifies the attributes of a realm. Options: container object in which the principals of a realm will be created. -**-r** *realm* - Specifies the Kerberos realm of the database. - **-maxtktlife** *max_ticket_life* (:ref:`getdate` string) Specifies maximum ticket life for principals in this realm. @@ -183,9 +188,8 @@ Modifies the attributes of a realm. Options: Example:: - shell% kdb5_ldap_util -D cn=admin,o=org -H - ldaps://ldap-server1.mit.edu modify +requires_preauth -r - ATHENA.MIT.EDU + shell% kdb5_ldap_util -r ATHENA.MIT.EDU -D cn=admin,o=org -H + ldaps://ldap-server1.mit.edu modify +requires_preauth Password for "cn=admin,o=org": shell% @@ -196,17 +200,14 @@ view .. _kdb5_ldap_util_view: - **view** [**-r** *realm*] + **view** -Displays the attributes of a realm. Options: - -**-r** *realm* - Specifies the Kerberos realm of the database. +Displays the attributes of a realm. Example:: kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - view -r ATHENA.MIT.EDU + -r ATHENA.MIT.EDU view Password for "cn=admin,o=org": Realm Name: ATHENA.MIT.EDU Subtree: ou=users,o=org @@ -223,20 +224,17 @@ destroy .. _kdb5_ldap_util_destroy: - **destroy** [**-f**] [**-r** *realm*] + **destroy** [**-f**] Destroys an existing realm. Options: **-f** If specified, will not prompt the user for confirmation. -**-r** *realm* - Specifies the Kerberos realm of the database. - Example:: - shell% kdb5_ldap_util -D cn=admin,o=org -H - ldaps://ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU + shell% kdb5_ldap_util -r ATHENA.MIT.EDU -D cn=admin,o=org -H + ldaps://ldap-server1.mit.edu destroy Password for "cn=admin,o=org": Deleting KDC database of 'ATHENA.MIT.EDU', are you sure? (type 'yes' to confirm)? yes @@ -252,7 +250,7 @@ list **list** -Lists the name of realms. +Lists the names of realms under the container. Example:: @@ -308,7 +306,6 @@ create_policy .. _kdb5_ldap_util_create_policy: **create_policy** - [**-r** *realm*] [**-maxtktlife** *max_ticket_life*] [**-maxrenewlife** *max_renewable_ticket_life*] [*ticket_flags*] @@ -316,9 +313,6 @@ create_policy Creates a ticket policy in the directory. Options: -**-r** *realm* - Specifies the Kerberos realm of the database. - **-maxtktlife** *max_ticket_life* (:ref:`getdate` string) Specifies maximum ticket life for principals. @@ -339,7 +333,7 @@ Creates a ticket policy in the directory. Options: Example:: kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - create_policy -r ATHENA.MIT.EDU -maxtktlife "1 day" + -r ATHENA.MIT.EDU create_policy -maxtktlife "1 day" -maxrenewlife "1 week" -allow_postdated +needchange -allow_forwardable tktpolicy Password for "cn=admin,o=org": @@ -352,7 +346,6 @@ modify_policy .. _kdb5_ldap_util_modify_policy: **modify_policy** - [**-r** *realm*] [**-maxtktlife** *max_ticket_life*] [**-maxrenewlife** *max_renewable_ticket_life*] [*ticket_flags*] @@ -364,7 +357,7 @@ Modifies the attributes of a ticket policy. Options are same as for Example:: kdb5_ldap_util -D cn=admin,o=org -H - ldaps://ldap-server1.mit.edu modify_policy -r ATHENA.MIT.EDU + ldaps://ldap-server1.mit.edu -r ATHENA.MIT.EDU modify_policy -maxtktlife "60 minutes" -maxrenewlife "10 hours" +allow_postdated -requires_preauth tktpolicy Password for "cn=admin,o=org": @@ -377,18 +370,14 @@ view_policy .. _kdb5_ldap_util_view_policy: **view_policy** - [**-r** *realm*] *policy_name* -Displays the attributes of a ticket policy. Options: - -*policy_name* - Specifies the name of the ticket policy. +Displays the attributes of the named ticket policy. Example:: kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - view_policy -r ATHENA.MIT.EDU tktpolicy + -r ATHENA.MIT.EDU view_policy tktpolicy Password for "cn=admin,o=org": Ticket policy: tktpolicy Maximum ticket life: 0 days 01:00:00 @@ -403,15 +392,11 @@ destroy_policy .. _kdb5_ldap_util_destroy_policy: **destroy_policy** - [**-r** *realm*] [**-force**] *policy_name* Destroys an existing ticket policy. Options: -**-r** *realm* - Specifies the Kerberos realm of the database. - **-force** Forces the deletion of the policy object. If not specified, the user will be prompted for confirmation before deleting the policy. @@ -422,7 +407,7 @@ Destroys an existing ticket policy. Options: Example:: kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - destroy_policy -r ATHENA.MIT.EDU tktpolicy + -r ATHENA.MIT.EDU destroy_policy tktpolicy Password for "cn=admin,o=org": This will delete the policy object 'tktpolicy', are you sure? (type 'yes' to confirm)? yes @@ -436,18 +421,13 @@ list_policy .. _kdb5_ldap_util_list_policy: **list_policy** - [**-r** *realm*] -Lists the ticket policies in realm if specified or in the default -realm. Options: - -**-r** *realm* - Specifies the Kerberos realm of the database. +Lists ticket policies. Example:: kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - list_policy -r ATHENA.MIT.EDU + -r ATHENA.MIT.EDU list_policy Password for "cn=admin,o=org": tktpolicy tmppolicy diff --git a/doc/admin/advanced/index.rst b/doc/admin/advanced/index.rst index 54add53..834f453 100644 --- a/doc/admin/advanced/index.rst +++ b/doc/admin/advanced/index.rst @@ -5,5 +5,4 @@ Advanced topics .. toctree:: :maxdepth: 1 - ldapbackend.rst retiring-des.rst diff --git a/doc/admin/advanced/ldapbackend.rst b/doc/admin/advanced/ldapbackend.rst deleted file mode 100644 index ede93d7..0000000 --- a/doc/admin/advanced/ldapbackend.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. _ldap_be_ubuntu: - -LDAP backend on Ubuntu 10.4 (lucid) -=================================== - -Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (Lucid Lynx) - - -Prerequisites -------------- - -Install the following packages: *slapd, ldap-utils* and *libldap2-dev* - -You can install the necessary packages with these commands:: - - sudo apt-get install slapd - sudo apt-get install ldap-utils - sudo apt-get install libldap2-dev - -Extend the user schema using schemas from standart OpenLDAP -distribution: *cosine, mics, nis, inetcomperson* :: - - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/cosine.ldif - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/mics.ldif - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/inetcomperson.ldif - - -Building Kerberos from source ------------------------------ - -:: - - ./configure --with-ldap - make - sudo make install - - -Setting up Kerberos -------------------- - -Configuration -~~~~~~~~~~~~~ - -Update kdc.conf with the LDAP back-end information:: - - [realms] - EXAMPLE.COM = { - database_module = LDAP - } - - [dbmodules] - LDAP = { - db_library = kldap - ldap_kerberos_container_dn = cn=krbContainer,dc=example,dc=com - ldap_kdc_dn = cn=admin,dc=example,dc=com - ldap_kadmind_dn = cn=admin,dc=example,dc=com - ldap_service_password_file = /usr/local/var/krb5kdc/admin.stash - ldap_servers = ldapi:/// - } - - -Schema -~~~~~~ - -From the source tree copy -``src/plugins/kdb/ldap/libkdb_ldap/kerberos.schema`` into -``/etc/ldap/schema`` - -Warning: this step should be done after slapd is installed to avoid -problems with slapd installation. - -To convert kerberos.schema to run-time configuration (``cn=config``) -do the following: - -#. Create a temporary file ``/tmp/schema_convert.conf`` with the - following content:: - - include /etc/ldap/schema/kerberos.schema - -#. Create a temporary directory ``/tmp/krb5_ldif``. - -#. Run:: - - slaptest -f /tmp/schema_convert.conf -F /tmp/krb5_ldif - - This should in a new file named - ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif``. - -#. Edit ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif`` by - replacing the lines:: - - dn: cn={0}kerberos - cn: {0}kerberos - - with - - dn: cn=kerberos,cn=schema,cn=config - cn: kerberos - - Also, remove following attribute-value pairs:: - - structuralObjectClass: olcSchemaConfig - entryUUID: ... - creatorsName: cn=config - createTimestamp: ... - entryCSN: ... - modifiersName: cn=config - modifyTimestamp: ... - -#. Load the new schema with ldapadd (with the proper authentication):: - - ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif - - which should result the message ``adding new entry - "cn=kerberos,cn=schema,cn=config"``. - - -Create Kerberos database ------------------------- - -Using LDAP administrator credentials, create Kerberos database and -master key stash:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create -s - -Stash the LDAP administrative passwords:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com - -Start :ref:`krb5kdc(8)`:: - - krb5kdc - -To destroy database run:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// destroy -f - - -Useful references ------------------ - -* `Kerberos and LDAP <https://help.ubuntu.com/lts/serverguide/kerberos-ldap.html>`_ diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst index e5d8962..9759756 100644 --- a/doc/admin/conf_files/kdc_conf.rst +++ b/doc/admin/conf_files/kdc_conf.rst @@ -446,7 +446,6 @@ definitions of these relations. * **ldap_kadmind_sasl_mech** * **ldap_kadmind_sasl_realm** * **ldap_service_password_file** -* **ldap_servers** * **ldap_conns_per_server** diff --git a/doc/admin/conf_ldap.rst b/doc/admin/conf_ldap.rst index a49b578..13d3769 100644 --- a/doc/admin/conf_ldap.rst +++ b/doc/admin/conf_ldap.rst @@ -4,51 +4,47 @@ Configuring Kerberos with OpenLDAP back-end =========================================== - 1. Set up SSL on the OpenLDAP server and client to ensure secure - communication when the KDC service and LDAP server are on different - machines. ``ldapi://`` can be used if the LDAP server and KDC - service are running on the same machine. + 1. Make sure the LDAP server is using local authentication + (``ldapi://``) or TLS (``ldaps``). See + https://www.openldap.org/doc/admin24/tls.html for instructions on + configuring TLS support in OpenLDAP. - A. Setting up SSL on the OpenLDAP server: + 2. Add the Kerberos schema file to the LDAP Server using the OpenLDAP + LDIF file from the krb5 source directory + (``src/plugins/kdb/ldap/libkdb_ldap/kerberos.openldap.ldif``). + The following example uses local authentication:: - i) Get a CA certificate using OpenSSL tools - ii) Configure OpenLDAP server for using SSL/TLS + ldapadd -Y EXTERNAL -H ldapi:/// -f /path/to/kerberos.openldap.ldif - For the latter, you need to specify the location of CA - certificate location in *slapd.conf* file. - - Refer to the following link for more information: - https://www.openldap.org/doc/admin23/tls.html - - B. Setting up SSL on OpenLDAP client: + 3. Choose DNs for the :ref:`krb5kdc(8)` and :ref:`kadmind(8)` servers + to bind to the LDAP server, and create them if necessary. Specify + these DNs with the **ldap_kdc_dn** and **ldap_kadmind_dn** + directives in :ref:`kdc.conf(5)`. The kadmind DN will also be + used for administrative commands such as :ref:`kdb5_util(8)`. - i) For the KDC and Admin Server, you need to do the client-side - configuration in ldap.conf. For example:: + Alternatively, you may configure krb5kdc and kadmind to use SASL + authentication to access the LDAP server; see the :ref:`dbmodules` + relations **ldap_kdc_sasl_mech** and similar. - TLS_CACERT /etc/openldap/certs/cacert.pem + 4. Specify a location for the LDAP service password file by setting + **ldap_service_password_file**. Use ``kdb5_ldap_util stashsrvpw`` + to stash passwords for the KDC and kadmind DNs chosen above. For + example:: - 2. Include the Kerberos schema file (kerberos.schema) in the - configuration file (slapd.conf) on the LDAP Server, by providing - the location where it is stored:: + kdb5_ldap_util stashsrvpw -f /path/to/service.keyfile cn=krbadmin,dc=example,dc=com - include /etc/openldap/schema/kerberos.schema + Skip this step if you are using SASL authentication and the + mechanism does not require a password. - 3. Choose DNs for the :ref:`krb5kdc(8)` and :ref:`kadmind(8)` servers - to bind to the LDAP server, and create them if necessary. These DNs - will be specified with the **ldap_kdc_dn** and **ldap_kadmind_dn** - directives in :ref:`kdc.conf(5)`; their passwords can be stashed - with "``kdb5_ldap_util stashsrvpw``" and the resulting file - specified with the **ldap_service_password_file** directive. - - 4. Choose a DN for the global Kerberos container entry (but do not - create the entry at this time). This DN will be specified with the + 5. Choose a DN for the global Kerberos container entry (but do not + create the entry at this time). Specify this DN with the **ldap_kerberos_container_dn** directive in :ref:`kdc.conf(5)`. Realm container entries will be created underneath this DN. Principal entries may exist either underneath the realm container (the default) or in separate trees referenced from the realm container. - 5. Configure the LDAP server ACLs to enable the KDC and kadmin server + 6. Configure the LDAP server ACLs to enable the KDC and kadmin server DNs to read and write the Kerberos data. If **disable_last_success** and **disable_lockout** are both set to true in the :ref:`dbmodules` subsection for the realm, then the @@ -62,21 +58,13 @@ Configuring Kerberos with OpenLDAP back-end access to dn.base="cn=Subschema" by * read - access to attrs=userPassword,userPKCS12 - by self write - by * auth - - access to attrs=shadowLastChange - by self write - by * read - - # Providing access to realm container + # Provide access to the realm container. access to dn.subtree= "cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com" by dn.exact="cn=kdc-service,dc=example,dc=com" write by dn.exact="cn=adm-service,dc=example,dc=com" write by * none - # Providing access to principals, if not underneath realm container + # Provide access to principals, if not underneath the realm container. access to dn.subtree= "ou=users,dc=example,dc=com" by dn.exact="cn=kdc-service,dc=example,dc=com" write by dn.exact="cn=adm-service,dc=example,dc=com" write @@ -85,33 +73,24 @@ Configuring Kerberos with OpenLDAP back-end access to * by * read - If the locations of the container and principals or the DNs of - the service objects for a realm are changed then this - information should be updated. + If the locations of the container and principals or the DNs of the + service objects for a realm are changed then this information + should be updated. - 6. Start the LDAP server as follows:: + 7. In :ref:`kdc.conf(5)`, make sure the following relations are set + in the :ref:`dbmodules` subsection for the realm:: - slapd -h "ldapi:/// ldaps:///" - - 7. Modify the :ref:`kdc.conf(5)` file to include LDAP specific items - listed below:: - - realms - database_module - - dbmodules - db_library - db_module_dir - ldap_kdc_dn - ldap_kadmind_dn - ldap_service_password_file - ldap_servers - ldap_conns_per_server + db_library (set to ``kldap``) + ldap_kerberos_container_dn + ldap_kdc_dn + ldap_kadmind_dn + ldap_service_password_file + ldap_servers 8. Create the realm using :ref:`kdb5_ldap_util(8)` (see :ref:`ldap_create_realm`):: - kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees ou=users,dc=example,dc=com -r EXAMPLE.COM -s + kdb5_ldap_util create -subtrees ou=users,dc=example,dc=com -s Use the **-subtrees** option if the principals are to exist in a separate subtree from the realm container. Before executing the @@ -123,27 +102,20 @@ Configuring Kerberos with OpenLDAP back-end For more information, refer to the section :ref:`ops_on_ldap`. The realm object is created under the - **ldap_kerberos_container_dn** specified in the configuration file. - This operation will also create the Kerberos container, if not - present already. This will be used to store information related to - all realms. + **ldap_kerberos_container_dn** specified in the configuration + file. This operation will also create the Kerberos container, if + not present already. This container can be used to store + information related to multiple realms. - 9. Stash the password of the service object used by the KDC and - Administration service to bind to the LDAP server using the - :ref:`kdb5_ldap_util(8)` **stashsrvpw** command (see - :ref:`stash_ldap`). The object DN should be the same as - **ldap_kdc_dn** and **ldap_kadmind_dn** values specified in the - :ref:`kdc.conf(5)` file:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com - - 10. Add ``krbPrincipalName`` to the indexes in slapd.conf to speed up - the access. + 9. Add an ``eq`` index for ``krbPrincipalName`` to speed up principal + lookup operations. See + https://www.openldap.org/doc/admin24/tuning.html#Indexes for + details. With the LDAP back end it is possible to provide aliases for principal -entries. Currently we provide no mechanism provided for creating -aliases, so it must be done by direct manipulation of the LDAP -entries. +entries. Currently we provide no administrative utilities for +creating aliases, so it must be done by direct manipulation of the +LDAP entries. An entry with aliases contains multiple values of the *krbPrincipalName* attribute. Since LDAP attribute values are not @@ -159,5 +131,3 @@ requests canonicalization. Canonicalization is normally requested for service principals; for client principals, an explicit flag is often required (e.g., ``kinit -C``) and canonicalization is only performed for initial ticket requests. - -.. seealso:: :ref:`ldap_be_ubuntu` |