#68 Add the kdcinfo improvements design page
Merged 5 years ago by jhrozek. Opened 5 years ago by jhrozek.
SSSD/ jhrozek/docs kdcinfo  into  master

file modified
+1
@@ -26,6 +26,7 @@ 

     smartcard_multiple_certificates

     enhanced_nss_api

     attestation_report

+    kdcinfo_improvements

  

  Implemented in 1.15.x

  ---------------------

@@ -0,0 +1,176 @@ 

+ .. highlight:: none

+ 

+ Kdcinfo files for trusted domains

+ =================================

+ 

+ Related ticket(s):

+ ------------------

+     https://pagure.io/SSSD/sssd/issue/3291

+     https://pagure.io/SSSD/sssd/issue/3652

+     https://pagure.io/SSSD/sssd/issue/941

+ 

+ Problem statement

+ -----------------

+ When user authenticates using Kerberos, the KDCs that will actually be

+ used are typically discovered by libkrb5 with the help of DNS SRV records,

+ unless the KDCs are configured explicitly in ``/etc/krb5.conf.``

+ 

+ Because the administrator typically expects that the servers they defined

+ in ``sssd.conf`` would be used for both authentication through SSSD and

+ for the Kerberos command line tools such as ``kinit``, SSSD provides a

+ locator plugin for libkrb5 that allows SSSD to inform libkrb5 the servers

+ SSSD had configured. However, up until now, this plugin was only functional

+ for the joined domain, not for the trusted domains. This means, that the

+ administrator had to either rely on the DNS SRC records to be correct

+ or manually configure ``krb5.conf.``. The former is not true in many

+ real-world deployments and the latter is non-obvious.and doesn't allow

+ the administrator to specify e.g.  the Active Directory site.

+ 

+ Use cases

+ ---------

+ There are three separate, but interconnected use-cases:

+ 

+  * An SSSD client joined to an Active Directory domain directly

+  * SSSD running on an IPA master with a trust established towards an AD domain

+  * SSSD running on an IPA client

+ 

+ In all three cases, the information provided by SSSD for the locator

+ plugin would allow the administrator to pin the SSSD to a specific AD KDC

+ for authentication using configuration options such as ``ad_server`` or

+ ``ad_site``. In addition, command line tools such as ``kinit`` would then

+ connect to the DCs discovered by SSSD as well.

+ 

+ Overview of the solution

+ ------------------------

+ The Kerberos locator plugin reads the address(es) from text files written

+ by SSSD located in the ``/var/lib/sss/pubconf`` directory.

+ 

+ On a high level, implementing this RFE requires several changes:

+ 

+  * The code that sets up AD connections to trusted domains when SSSD is

+    running on IPA masters must be augmented to create the kdcinfo files that

+    the Kerberos locator reads

+  * Similarly, the AD provider must be enhances to create the kdcinfo

+    files for cases where the SSSD is joined to an AD domain directly

+  * Becase the IPA provider on IPA clients is currently only able to perform

+    the full fail over for the IPA domain (at the moment the fail over is

+    bound to the back end, not the domain), the IPA provider must be extended

+    to read a configured list of servers or an AD site from the configuration,

+    resolve this input into a list of IP addresses and write the list into

+    the kdcinfo files

+  * Finally, the Kerberos locator plugin itself must be enhanced to allow

+    reading multiple addresses and call the callback function provided

+    by libkrb5 for each of the addresses

+ 

+ Implementation details

+ ----------------------

+ Writing the kdcinfo files on AD clients and IPA masters is a relatively

+ straightforward change, the ``write_kdcinfo`` flag of the ``krb5_service``

+ must be set according to the value of the ``krb5_use_kdcinfo`` configuration

+ option.

+ 

+ The scope of extending the locator plugin is changing the plugin to read

+ a list of ``(host, port)`` tuples from a newline-separated list in the

+ kdcinfo file and calling the provided callback function ``cbfunc`` in turn

+ for each for the addresses.

+ 

+ The biggest change, at least code-wise is the support for the IPA clients.

+ There, the subdomain provider must first read either the list of servers

+ from the subdomain section (using the ``ad_server`` option value) or

+ the AD site from the ``ad_site`` option. If neither of those is present,

+ the subdomain is skipped. If servers are defined using the ``ad_server``

+ option, a new resolver request would resolve the host names from this

+ list into a list of IP addresses and write those into the kdcinfo file.

+ Care must be taken so that any unresolvable address is just skipped.

+ If a site is configured, then the IPA subdomains provider would first

+ resolve the servers in this site using a DNS SRV query and then call the

+ same request to resolve the host names into addresses as in the case where

+ the host names were configured. Finally, the addresses are also written

+ to the kdcinfo files.

+ 

+ In the case where host names are specified using the ``ad_server`` option,

+ all of the host names will be resolved and written into the kdcinfo file.

+ In the case where the site is configured, the first 5 host names resolved

+ from the DNS SRV query will be resolved. Using more host names wouldn't

+ make sense anyway, because either the SSSD authentication time out would

+ abort the ``krb5_child`` helper or ``kinit`` itself would time out.

+ 

+ Configuration changes

+ ---------------------

+ No new configuration options are added. However, on IPA clients

+ the following configuration::

+ 

+     [domain/ipa.domain/ad.domain]

+     ad_server = dc1.ad.domain, dc2.ad.doma

+ 

+ Or this configuration::

+ 

+     [domain/ipa.domain/ad.domain]

+     ad_site = localsite

+ 

+ Would now trigger the DNS resolution of either the host names

+ or the site and then the host names in the site and populate

+ the kdcinfo files.

+ 

+ How To Test

+ -----------

+ On an AD client or an IPA master, the kdcinfo files are populated in

+ response to a request towards the trusted domain. Therefore a valid test

+ is to make sure that after resolving a user from a trusted domain::

+ 

+     getent passwd user@child.domain

+ 

+ a valid kdcinfo file with an address of the DC that SSSD contacted in

+ order to resolve the user is present. Given the example above, the

+ file would be located at::

+ 

+     /var/lib/sss/pubconf/kdcinfo.CHILD.DOMAIN

+ 

+ In case of the IPA client, the kdcinfo files are generated after startup

+ and then subsequently during each periodic invocation of the subdomains

+ provider

+ 

+ In all cases, either shutting down SSSD or bringing SSSD into the offline

+ mode (e.g with the ``SIGUSR1`` signal) should remove all the kdcinfo files.

+ 

+ In all cases, calling a command line Kerberos tool such as ``kinit``

+ should read the kdcinfo file and contact the AD DC specified in the

+ kdcinfo file. This can be verified using e.g. ``strace.`` or by using

+ the ``KRB5_TRACE`` variable.

+ 

+ In all cases, disabling the ``krb5_use_kdcinfo`` option must prevent

+ the kdcinfo files from being generated.

+ 

+ How To Debug

+ ------------

+ Information on which servers were discovered and written to the kdcinfo

+ files are present in the SSSD debug logs.

+ 

+ The kdcinfo files are textual and can be inspected using e.g. ``cat``.

+ 

+ Finally, whether the kdcinfo files are being used and which DCs are being

+ contacted can be seen either in the ``krb5_child.log`` with a very high

+ debug level (one that enables the KRB5_TRACE messages). Whether the kdcinfo

+ files are being used from other command line utilities can be inspected

+ by using the ``KRB5_TRACE`` environment variable, e.g.::

+ 

+     KRB5_TRACE=/dev/stderr kinit user@DOMAIN

+ 

+ Future development

+ ------------------

+ At the moment, setting the AD DCs or site must be done on each and every

+ IPA client by either modifying the sssd.conf file, or (better) dropping

+ a configuration snippet into the ``/etc/sssd/conf.d`` directory. We would

+ also like to, in one of the future releases, provide means of mapping an

+ IPA host or a host group to an AD site so that this configuration can be

+ done centrally.

+ 

+ Additionally, we would like to extend the kdcinfo file generation on AD

+ clients as well so that the client can optionally write multiple addresses

+ into the kdcinfo files in order to provide a way of failing over between

+ multiple DCs from outside SSSD, for example from ``kinit.``

+ 

+ Authors

+ -------

+  * Sumit Bose <sbose@redhat.com>

+  * Jakub Hrozek <jhrozek@redhat.com>

A design page for the recent kdcinfo enhancements

rebased onto 7cbf6da

5 years ago

Since the code was pushed, I'm going to push the design page as well..

Pull-Request has been merged by jhrozek

5 years ago