From 7cbf6daa4e74c87d3936311e8ea55c6f2c4c2938 Mon Sep 17 00:00:00 2001 From: Jakub Hrozek Date: Jun 30 2018 10:09:41 +0000 Subject: Add the kdcinfo improvements design page --- diff --git a/design_pages/index.rst b/design_pages/index.rst index 9df12af..b35c898 100644 --- a/design_pages/index.rst +++ b/design_pages/index.rst @@ -26,6 +26,7 @@ Implemented in 1.16.x smartcard_multiple_certificates enhanced_nss_api attestation_report + kdcinfo_improvements Implemented in 1.15.x --------------------- diff --git a/design_pages/kdcinfo_improvements.rst b/design_pages/kdcinfo_improvements.rst new file mode 100644 index 0000000..b4629cd --- /dev/null +++ b/design_pages/kdcinfo_improvements.rst @@ -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 + * Jakub Hrozek