From 9e0ef662d0f497777336aa6d8b3e4acc5fb05ca3 Mon Sep 17 00:00:00 2001
From: Justin Stephenson <jstephen@redhat.com>
Date: Mon, 8 Jan 2024 09:57:47 -0500
Subject: [PATCH] docs: add files provider removal document

Include steps on how to switch to equivalent proxy provider
configuration.
---
 src/contents.rst                        |  1 +
 src/docs/files-provider-deprecation.rst | 60 +++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 src/docs/files-provider-deprecation.rst

diff --git a/src/contents.rst b/src/contents.rst
index be77cdf..fc8b68c 100644
--- a/src/contents.rst
+++ b/src/contents.rst
@@ -55,6 +55,7 @@ Table of Contents
    docs/introduction
    Architecture <docs/architecture>
    docs/reporting-bugs
+   docs/files-provider-deprecation
 
 .. toctree::
    :caption: Active Directory
diff --git a/src/docs/files-provider-deprecation.rst b/src/docs/files-provider-deprecation.rst
new file mode 100644
index 0000000..c519e11
--- /dev/null
+++ b/src/docs/files-provider-deprecation.rst
@@ -0,0 +1,60 @@
+Files Provider Removal
+######################
+
+The SSSD team has announced the `removal of the files provider <https://pagure.io/fesco/issue/3107>`_ feature in recent versions of SSSD in Fedora/CentOS Stream/RHEL. This document describes how to switch to using the SSSD 'proxy' provider to replace files provider functionality.
+
+Practically, there are only two use cases that currently justify usage of the files provider feature:
+
+* smart card authentication of local users
+* session recording for local users
+
+For both cases the proxy provider is a viable substitute. Otherwise, there is no benefit in SSSD handling local users.
+
+Proxy Provider Configuration
+****************************
+
+The SSSD proxy provider is just a relay, an intermediary configuration. SSSD connects to its proxy service, and then that proxy loads the specified libraries. This allows SSSD to use some resources that it otherwise would not be able to use.
+
+First, make sure to install the ``sssd-proxy`` package.
+
+.. code-block:: console
+
+    $ dnf install sssd-proxy
+
+A sample proxy provider configuration to load the nss `files` module is below:
+
+.. code-block:: console
+
+    [sssd]
+    services=nss, pam
+    domains=nssfiles
+
+    [domain/nssfiles]
+    id_provider=proxy
+    proxy_lib_name=files
+    proxy_pam_target=sssd-shadowutils
+
+The ``proxy_lib_name`` option specifies which existing NSS library to proxy identity requests through.
+
+The ``proxy_pam_target`` specifies the target to which PAM must proxy as an authentication provider. This PAM target is a file containing PAM stack information in the default PAM directory, ``/etc/pam.d/``. The file `sssd-shadowutils <https://github.com/SSSD/sssd/blob/master/src/examples/sssd-shadowutils>`_ is packaged with upstream SSSD and shipped in Fedora.
+
+.. note:: Ensure that the proxy PAM target stack does not recursively include pam_sss.so.
+
+.. code-block:: console
+
+    ~# cat /etc/pam.d/sssd-shadowutils
+    #%PAM-1.0
+    auth        [success=done ignore=ignore default=die] pam_unix.so nullok try_first_pass
+    auth        required      pam_deny.so
+
+    account     required      pam_unix.so
+    account     required      pam_permit.so
+
+nsswitch changes
+****************
+
+In the `session recording for local users` case it is required to set the `sss` module as the first module in the list for the `passwd` and `group` databases of ``/etc/nsswitch.conf``. On systems managed by authselect, the following command should be run:
+
+.. code-block:: bash
+
+    authselect select sssd with-tlog
\ No newline at end of file