sch-ipa.txt: add documentation about trusted domains support for FreeIPA

1 files changed, 48 insertions, 0 deletions

diff --git a/doc/ipa/sch-ipa.txt b/doc/ipa/sch-ipa.txt
index 44b4f43..b5a585b 100644
--- a/doc/ipa/sch-ipa.txt
+++ b/doc/ipa/sch-ipa.txt
@@ -39,3 +39,51 @@ membership information in a form which the client is able to process.
 As configured, an IPA server provides this information, for groups whose
 entries are beneath "cn=groups, cn=accounts, $SUFFIX", in an area
 beneath "cn=groups, cn=compat, $SUFFIX".
+
+= The Schema Compatibility Plugin support for trusted domains in IPA =
+
+When used with FreeIPA 3.3 and SSSD 1.11 or later, the Schema Compatibility
+Plugin allows to expose users and groups from trusted domains. These users
+and groups are available on the compatibility trees and can be used for
+querying their attributes and authenticating against them.
+
+Additionally, authentication against IPA users is also supported, provided
+that the Schema Compatibility Plugin is given an ordering preference in
+the Directory Server configuration. By default, all Directory server plugins
+are assigned plugin precedence of 50 (out of 1..99 scale, where 99 is the lowest
+priority). The plugin precedence is controlled with nsslapd-pluginPrecedence
+attribute in the plugin entry. More details on nsslapd-PluginPrecedence are
+available in Red Hat Directory Server Administration Guide, chapter "1.8 Using
+Directory Server Plug-ins".
+
+== Configuration of the Schema Compatibility Plugin for trusted domains ==
+
+User and groups areas should be configured separately. For each area following
+parameters can be added in the tree configuration:
+
+schema-compat-lookup-nsswitch: <user|group>
+
+specifies that the area is responsible for user or group lookups.
+
+schema-compat-nsswitch-min-id: <value>
+
+specifies that the minimal numeric id of the user or group should be not less
+than the value. Defaults to 1000.
+
+When FreeIPA 3.3 is in use, ipa-adtrust-install utility will automatically configure
+the Schema Compatibility Plugin to allow serving users and groups from trusted domains.
+No additional configuration is needed. ipa-adtrust-install, however, will not set the
+minimal numeric id for user or group.
+
+== Authentication of the trusted domains' users ==
+
+When the Schema Compatibility Plugin is configured to expose users from trusted
+domains, their authentication is handled via PAM 'system-auth' service. This
+service exists by default on Linux  systems and is provided by pam package as
+/etc/pam.d/system-auth. If your FreeIPA install does not have default HBAC rule
+'allow_all' enabled, then make sure to define in IPA a special service called
+'system-auth' and create an HBAC rule to allow access to anyone to this rule
+on  IPA masters.
+
+As 'system-auth' PAM service is not used directly by any other application, it
+is safe to use it for trusted domain users via compatibility path.