path: root/src/man/sssd-ad.5.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<reference>
<title>SSSD Manual pages</title>
<refentry>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />

    <refmeta>
        <refentrytitle>sssd-ad</refentrytitle>
        <manvolnum>5</manvolnum>
        <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
    </refmeta>

    <refnamediv id='name'>
        <refname>sssd-ad</refname>
        <refpurpose>SSSD Active Directory provider</refpurpose>
    </refnamediv>

    <refsect1 id='description'>
        <title>DESCRIPTION</title>
        <para>
            This manual page describes the configuration of the AD provider
            for
            <citerefentry>
                <refentrytitle>sssd</refentrytitle>
                <manvolnum>8</manvolnum>
            </citerefentry>.
            For a detailed syntax reference, refer to the <quote>FILE FORMAT</quote> section of the
            <citerefentry>
                <refentrytitle>sssd.conf</refentrytitle>
                <manvolnum>5</manvolnum>
            </citerefentry> manual page.
        </para>
        <para>
            The AD provider is a back end used to connect to an Active
            Directory server. This provider requires that the machine be
            joined to the AD domain and a keytab is available. Back end
            communication occurs over a GSSAPI-encrypted channel, SSL/TLS
            options should not be used with the AD provider and will be
            superseded by Kerberos usage.
        </para>
        <para>
            The AD provider supports connecting to Active Directory 2008 R2
            or later. Earlier versions may work, but are unsupported.
        </para>
        <para>
            The AD provider can be used to get user information
            and authenticate users from trusted domains. Currently
            only trusted domains in the same forest are recognized. In
            addition servers from trusted domains are always auto-discovered.
        </para>
        <para>
            The AD provider enables SSSD to use the
            <citerefentry>
                <refentrytitle>sssd-ldap</refentrytitle>
                <manvolnum>5</manvolnum>
            </citerefentry> identity provider and the
            <citerefentry>
                <refentrytitle>sssd-krb5</refentrytitle>
                <manvolnum>5</manvolnum>
            </citerefentry> authentication provider with optimizations for
            Active Directory environments. The AD provider accepts the same
            options used by the sssd-ldap and sssd-krb5 providers with some
            exceptions. However, it is neither necessary nor recommended to
            set these options.
        </para>
        <para>
            The AD provider primarily copies the traditional ldap and krb5
            provider default options with some exceptions, the differences
            are listed in the <quote>MODIFIED DEFAULT OPTIONS</quote> section.
        </para>
        <para>
            The AD provider can also be used as an access, chpass,
            sudo and autofs provider. No configuration of the access provider
            is required on the client side.
        </para>
        <para>
            If <quote>auth_provider=ad</quote> or
            <quote>access_provider=ad</quote> is configured
            in sssd.conf then the id_provider must also be set to
            <quote>ad</quote>.
        </para>
        <para>
            By default, the AD provider will map UID and GID values from the
            objectSID parameter in Active Directory. For details on this, see
            the <quote>ID MAPPING</quote> section below. If you want to
            disable ID mapping and instead rely on POSIX attributes defined in
            Active Directory, you should set
            <programlisting>
ldap_id_mapping = False
            </programlisting>
            If POSIX attributes should be used, it is recommended for
            performance reasons that the attributes are also replicated
            to the Global Catalog. If POSIX attributes are replicated,
            SSSD will attempt to locate the domain of a requested
            numerical ID with the help of the Global Catalog and only
            search that domain. In contrast, if POSIX attributes are not
            replicated to the Global Catalog, SSSD must search all the
            domains in the forest sequentially. Please note that the
            <quote>cache_first</quote> option might be also helpful in
            speeding up domainless searches.
            Note that if only a subset of POSIX attributes is present in
            the Global Catalog, the non-replicated attributes are currently
            not read from the LDAP port.
        </para>
        <para>
            Users, groups and other entities served by SSSD are always treated as
            case-insensitive in the AD provider for compatibility with Active
            Directory's LDAP implementation.
        </para>
        <para>
            SSSD only resolves Active Directory Security Groups. For more
            information about AD group types see:
            <ulink
            url="https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/understand-security-groups">
            Active Directory security groups</ulink>
        </para>
        <para>
            SSSD filters out Domain Local groups from remote domains in the AD
            forest. By default they are filtered out e.g. when following a
            nested group hierarchy in remote domains because they are not valid
            in the local domain. This is done to be in agreement with Active
            Directory's group-membership assignment which can be seen in
            the PAC of the Kerberos ticket of a user issued by Active Directory.
        </para>
    </refsect1>

    <refsect1 id='configuration-options'>
        <title>CONFIGURATION OPTIONS</title>
        <para>Refer to the section <quote>DOMAIN SECTIONS</quote> of the
            <citerefentry>
                <refentrytitle>sssd.conf</refentrytitle>
                <manvolnum>5</manvolnum>
            </citerefentry> manual page for details on the configuration of an SSSD domain.
            <variablelist>
                <varlistentry>
                    <term>ad_domain (string)</term>
                    <listitem>
                        <para>
                            Specifies the name of the Active Directory domain.
                            This is optional. If not provided, the
                            configuration domain name is used.
                        </para>
                        <para>
                            For proper operation, this option should be
                            specified as the lower-case version of the long
                            version of the Active Directory domain.
                        </para>
                        <para>
                            The short domain name (also known as the NetBIOS
                            or the flat name) is autodetected by the SSSD.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_enabled_domains (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of enabled Active Directory
                            domains. If provided, SSSD will ignore any domains
                            not listed in this option. If left unset, all
                            discovered domains from the AD forest will be
                            available.
                        </para>
                        <para>
                            During the discovery of the domains SSSD will
                            filter out some domains where flags or attributes
                            indicate that they do not belong to the local
                            forest or are not trusted. If ad_enabled_domains is
                            set, SSSD will try to enable all listed domains.
                        </para>
                        <para>
                            For proper operation, this option must be specified in all
                            lower-case and as the fully qualified domain name of the
                            Active Directory domain. For example:
                            <programlisting>
ad_enabled_domains = sales.example.com, eng.example.com
                            </programlisting>
                        </para>
                        <para>
                            The short domain name (also known as the NetBIOS or the flat
                            name) will be autodetected by SSSD.
                        </para>
                        <para>
                            Default: Not set
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_server, ad_backup_server (string)</term>
                    <listitem>
                        <para>
                            The comma-separated list of
                            hostnames of the AD servers to which SSSD should
                            connect in order of preference. For more
                            information on failover and server redundancy, see
                            the <quote>FAILOVER</quote> section.
                        </para>
                        <para>
                            This is optional if autodiscovery is enabled.
                            For more information on service discovery, refer
                            to the <quote>SERVICE DISCOVERY</quote> section.
                        </para>
                        <para>
                            Note: Trusted domains will always auto-discover
                            servers even if the primary server is explicitly
                            defined in the ad_server option.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_hostname (string)</term>
                    <listitem>
                        <para>
                            Optional. On machines where the hostname(5) does
                            not reflect the fully qualified name, sssd will try
                            to expand the short name. If it is not possible or
                            the short name should be really used instead, set
                            this parameter explicitly.
                        </para>
                        <para>
                            This field is used to determine the host principal
                            in use in the keytab and to perform dynamic DNS
                            updates. It must match the hostname for which the
                            keytab was issued.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_enable_dns_sites (boolean)</term>
                    <listitem>
                        <para>
                            Enables DNS sites - location based
                            service discovery.
                        </para>
                        <para>
                            If true and service discovery (see Service
                            Discovery paragraph at the bottom of the man page)
                            is enabled, the SSSD will first attempt to discover
                            the Active Directory server to connect to using the
                            Active Directory Site Discovery and fall back to
                            the DNS SRV records if no AD site is found. The
                            DNS SRV configuration, including the discovery
                            domain, is used during site discovery as well.
                        </para>
                        <para>
                            Default: true
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_access_filter (string)</term>
                    <listitem>
                        <para>
                            This option specifies LDAP access control
                            filter that the user must match in order
                            to be allowed access. Please note that the
                            <quote>access_provider</quote> option must be
                            explicitly set to <quote>ad</quote> in order
                            for this option to have an effect.
                        </para>
                        <para>
                            The option also supports specifying different
                            filters per domain or forest. This
                            extended filter would consist of:
                            <quote>KEYWORD:NAME:FILTER</quote>.
                            The keyword can be either <quote>DOM</quote>,
                            <quote>FOREST</quote> or missing.
                        </para>
                        <para>
                            If the keyword equals to <quote>DOM</quote>
                            or is missing, then <quote>NAME</quote> specifies
                            the domain or subdomain the filter applies to.
                            If the keyword equals to <quote>FOREST</quote>,
                            then the filter equals to all domains from the
                            forest specified by <quote>NAME</quote>.
                        </para>
                        <para>
                            Multiple filters can be separated with the
                            <quote>?</quote> character, similarly to how
                            search bases work.
                        </para>
                        <para>
                            Nested group membership must be searched for using
                            a special OID <quote>:1.2.840.113556.1.4.1941:</quote>
                            in addition to the full DOM:domain.example.org: syntax
                            to ensure the parser does not attempt to interpret the
                            colon characters associated with the OID. If you do not
                            use this OID then nested group membership will not be
                            resolved. See usage example below and refer here
                            for further information about the OID:
                            <ulink
                            url="https://msdn.microsoft.com/en-us/library/cc223367.aspx">
                            [MS-ADTS] section LDAP extensions</ulink>
                        </para>
                        <para>
                            The most specific match is always used. For
                            example, if the option specified filter
                            for a domain the user is a member of and a
                            global filter, the per-domain filter would
                            be applied.  If there are more matches with
                            the same specification, the first one is used.
                        </para>
                        <para>
                            Examples:
                        </para>
                        <programlisting>
# apply filter on domain called dom1 only:
dom1:(memberOf=cn=admins,ou=groups,dc=dom1,dc=com)

# apply filter on domain called dom2 only:
DOM:dom2:(memberOf=cn=admins,ou=groups,dc=dom2,dc=com)

# apply filter on forest called EXAMPLE.COM only:
FOREST:EXAMPLE.COM:(memberOf=cn=admins,ou=groups,dc=example,dc=com)

# apply filter for a member of a nested group in dom1:
DOM:dom1:(memberOf:1.2.840.113556.1.4.1941:=cn=nestedgroup,ou=groups,dc=example,dc=com)
                        </programlisting>
                        <para>
                            Default: Not set
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_site (string)</term>
                    <listitem>
                        <para>
                          Specify AD site to which client should try to connect.
                          If this option is not provided, the AD site will be
                          auto-discovered.
                        </para>
                        <para>
                            Default: Not set
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_enable_gc (boolean)</term>
                    <listitem>
                        <para>
                            By default, the SSSD connects to the Global
                            Catalog first to retrieve users from trusted
                            domains and uses the LDAP port to retrieve
                            group memberships or as a fallback. Disabling
                            this option makes the SSSD only connect to
                            the LDAP port of the current AD server.
                        </para>
                        <para>
                            Please note that disabling Global Catalog support
                            does not disable retrieving users from trusted
                            domains. The SSSD would connect to the LDAP port
                            of trusted domains instead. However, Global
                            Catalog must be used in order to resolve
                            cross-domain group memberships.
                        </para>
                        <para>
                            Default: true
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_access_control (string)</term>
                    <listitem>
                        <para>
                            This option specifies the operation mode for
                            GPO-based access control functionality:
                            whether it operates in disabled mode, enforcing
                            mode, or permissive mode. Please note that the
                            <quote>access_provider</quote> option must be
                            explicitly set to <quote>ad</quote> in order for
                            this option to have an effect.
                        </para>
                        <para>
                            GPO-based access control functionality uses GPO
                            policy settings to determine whether or not a
                            particular user is allowed to logon to the host.
                            For more information on the supported policy
                            settings please refer to the
                            <quote>ad_gpo_map</quote> options.
                        </para>
                        <para>
                            Please note that current version of SSSD does
                            not support Active Directory's built-in groups.
                            Built-in groups (such as Administrators with
                            SID S-1-5-32-544) in GPO access control rules
                            will be ignored by SSSD.
                            See upstream issue tracker
                            https://github.com/SSSD/sssd/issues/5063 .
                        </para>
                        <para>
                            Before performing access control SSSD applies group
                            policy security filtering on the GPOs. For every
                            single user login, the applicability of the GPOs
                            that are linked to the host is checked. In order for
                            a GPO to apply to a user, the user or at least one
                            of the groups to which it belongs must have
                            following permissions on the GPO:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        Read: The user or one of its groups must
                                        have read access to the properties of the
                                        GPO (RIGHT_DS_READ_PROPERTY)
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        Apply Group Policy: The user or at least
                                        one of its groups must be allowed to
                                        apply the GPO (RIGHT_DS_CONTROL_ACCESS).
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                        <para>
                            By default, the Authenticated Users group is present
                            on a GPO and this group has both Read and Apply Group
                            Policy access rights. Since authentication of a user
                            must have been completed successfully before GPO
                            security filtering and access control are started,
                            the Authenticated Users group permissions on the GPO
                            always apply also to the user.
                        </para>
                        <para>
                            NOTE: If the operation mode is set to enforcing, it
                            is possible that users that were previously allowed
                            logon access will now be denied logon access (as
                            dictated by the GPO policy settings). In order to
                            facilitate a smooth transition for administrators,
                            a permissive mode is available that will not enforce
                            the access control rules, but will evaluate them and
                            will output a syslog message if access would have
                            been denied. By examining the logs, administrators
                            can then make the necessary changes before setting
                            the mode to enforcing. For logging GPO-based access
                            control debug level 'trace functions' is required (see
                            <citerefentry>
                                <refentrytitle>sssctl</refentrytitle>
                                <manvolnum>8</manvolnum>
                            </citerefentry>
                            manual page).
                        </para>
                        <para>
                            There are three supported values for this option:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        disabled: GPO-based access control rules
                                        are neither evaluated nor enforced.
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        enforcing: GPO-based access control
                                        rules are evaluated and enforced.
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        permissive: GPO-based access control
                                        rules are evaluated, but not enforced.
                                        Instead, a syslog message will be
                                        emitted indicating that the user would
                                        have been denied access if this option's
                                        value were set to enforcing.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                        <para condition="gpo_default_permissive">
                            Default: permissive
                        </para>
                        <para condition="gpo_default_enforcing">
                            Default: enforcing
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_implicit_deny (boolean)</term>
                    <listitem>
                        <para>
                            Normally when no applicable GPOs are found the
                            users are allowed access. When this option is set
                            to True users will be allowed access only when
                            explicitly allowed by a GPO rule. Otherwise users
                            will be denied access. This can be used to harden
                            security but be careful when using this option
                            because it can deny access even to users in the
                            built-in Administrators group if no GPO rules
                            apply to them.
                        </para>

                        <para>
                            Default: False
                        </para>

                        <para>
                            The following 2 tables should illustrate when a user
                            is allowed or rejected based on the allow and deny
                            login rights defined on the server-side and the
                            setting of ad_gpo_implicit_deny.
                        </para>
                        <informaltable frame='all'>
                        <tgroup cols='3'>
                        <colspec colname='c1' align='center'/>
                        <colspec colname='c2' align='center'/>
                        <colspec colname='c3' align='center'/>
                        <thead>
                        <row><entry namest='c1' nameend='c3' align='center'>
                            ad_gpo_implicit_deny = False (default)</entry></row>
                        <row><entry>allow-rules</entry><entry>deny-rules</entry>
                            <entry>results</entry></row>
                        </thead>
                        <tbody>
                        <row><entry>missing</entry><entry>missing</entry>
                            <entry><para>all users are allowed</para>
                            </entry></row>
                        <row><entry>missing</entry><entry>present</entry>
                            <entry><para>only users not in deny-rules are
                            allowed</para></entry></row>
                        <row><entry>present</entry><entry>missing</entry>
                            <entry><para>only users in allow-rules are
                            allowed</para></entry></row>
                        <row><entry>present</entry><entry>present</entry>
                            <entry><para>only users in allow-rules and not in
                            deny-rules are allowed</para></entry></row>
                        </tbody></tgroup></informaltable>

                        <informaltable frame='all'>
                        <tgroup cols='3'>
                        <colspec colname='c1' align='center'/>
                        <colspec colname='c2' align='center'/>
                        <colspec colname='c3' align='center'/>
                        <thead>
                        <row><entry namest='c1' nameend='c3' align='center'>
                            ad_gpo_implicit_deny = True</entry></row>
                        <row><entry>allow-rules</entry><entry>deny-rules</entry>
                            <entry>results</entry></row>
                        </thead>
                        <tbody>
                        <row><entry>missing</entry><entry>missing</entry>
                            <entry><para>no users are allowed</para>
                            </entry></row>
                        <row><entry>missing</entry><entry>present</entry>
                            <entry><para>no users are allowed</para>
                            </entry></row>
                        <row><entry>present</entry><entry>missing</entry>
                            <entry><para>only users in allow-rules are
                            allowed</para></entry></row>
                        <row><entry>present</entry><entry>present</entry>
                            <entry><para>only users in allow-rules and not in
                            deny-rules are allowed</para></entry></row>
                        </tbody></tgroup></informaltable>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_ignore_unreadable (boolean)</term>
                    <listitem>
                        <para>
                            Normally when some group policy containers (AD
                            object) of applicable group policy objects are
                            not readable by SSSD then users are denied access.
                            This option allows to ignore group policy
                            containers and with them associated policies
                            if their attributes in group policy containers
                            are not readable for SSSD.
                        </para>
                        <para>
                            Default: False
                        </para>
                    </listitem>
                </varlistentry>



                <varlistentry>
                    <term>ad_gpo_cache_timeout (integer)</term>
                    <listitem>
                        <para>
                            The amount of time between lookups of GPO policy
                            files against the AD server. This will reduce the
                            latency and load on the AD server if there are
                            many access-control requests made in a short
                            period.
                        </para>
                        <para>
                            Default: 5 (seconds)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_map_interactive (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of PAM service names for
                            which GPO-based access control is evaluated based on
                            the InteractiveLogonRight and
                            DenyInteractiveLogonRight policy settings.
                            Only those GPOs are evaluated for which the user has
                            Read and Apply Group Policy permission (see option
                            <quote>ad_gpo_access_control</quote>).
                            If an evaluated GPO contains the deny interactive
                            logon setting for the user or one of its groups, the
                            user is denied local access.
                            If none of the evaluated GPOs has an interactive
                            logon right defined, the user is granted local
                            access. If at least one evaluated GPO contains
                            interactive logon right settings, the user is
                            granted local access only, if it or at least one of
                            its groups is part of the policy settings.
                        </para>
                        <para>
                            Note: Using the Group Policy Management Editor
                            this value is called "Allow log on locally"
                            and "Deny log on locally".
                        </para>
                        <para>
                            It is possible to add another PAM service name
                            to the default set by using <quote>+service_name</quote>
                            or to explicitly remove a PAM service name from
                            the default set by using <quote>-service_name</quote>.
                            For example, in order to replace a default PAM service
                            name for this logon right (e.g. <quote>login</quote>)
                            with a custom pam service name (e.g. <quote>my_pam_service</quote>),
                            you would use the following configuration:
                            <programlisting>
ad_gpo_map_interactive = +my_pam_service, -login
                            </programlisting>
                        </para>
                        <para>
                            Default: the default set of PAM service names includes:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        login
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        su
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        su-l
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        gdm-fingerprint
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        gdm-password
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        gdm-smartcard
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        kdm
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        lightdm
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        lxdm
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        sddm
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        unity
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        xdm
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_map_remote_interactive (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of PAM service names for
                            which GPO-based access control is evaluated based on
                            the RemoteInteractiveLogonRight and
                            DenyRemoteInteractiveLogonRight policy settings.
                            Only those GPOs are evaluated for which the user has
                            Read and Apply Group Policy permission (see option
                            <quote>ad_gpo_access_control</quote>).
                            If an evaluated GPO contains the deny remote
                            logon setting for the user or one of its groups, the
                            user is denied remote interactive access.
                            If none of the evaluated GPOs has a remote
                            interactive logon right defined, the user is granted
                            remote access. If at least one evaluated GPO
                            contains remote interactive logon right settings,
                            the user is granted remote access only, if it or at
                            least one of its groups is part of the policy
                            settings.
                        </para>
                        <para>
                            Note: Using the Group Policy Management Editor this
                            value is called "Allow log on through Remote Desktop
                            Services" and "Deny log on through Remote Desktop
                            Services".
                        </para>
                        <para>
                            It is possible to add another PAM service name
                            to the default set by using <quote>+service_name</quote>
                            or to explicitly remove a PAM service name from
                            the default set by using <quote>-service_name</quote>.
                            For example, in order to replace a default PAM service
                            name for this logon right (e.g. <quote>sshd</quote>)
                            with a custom pam service name (e.g. <quote>my_pam_service</quote>),
                            you would use the following configuration:
                            <programlisting>
ad_gpo_map_remote_interactive = +my_pam_service, -sshd
                            </programlisting>
                        </para>
                        <para>
                            Default: the default set of PAM service names includes:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        sshd
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        cockpit
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_map_network (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of PAM service names for
                            which GPO-based access control is evaluated based on
                            the NetworkLogonRight and DenyNetworkLogonRight
                            policy settings.
                            Only those GPOs are evaluated for which the user has
                            Read and Apply Group Policy permission (see option
                            <quote>ad_gpo_access_control</quote>).
                            If an evaluated GPO contains the deny network
                            logon setting for the user or one of its groups, the
                            user is denied network logon access.
                            If none of the evaluated GPOs has a network
                            logon right defined, the user is granted logon
                            access. If at least one evaluated GPO contains
                            network logon right settings, the user is
                            granted logon access only, if it or at least one of
                            its groups is part of the policy settings.
                        </para>
                        <para>
                            Note: Using the Group Policy Management Editor
                            this value is called "Access this computer
                            from the network" and "Deny access to this
                            computer from the network".
                        </para>
                        <para>
                            It is possible to add another PAM service name
                            to the default set by using <quote>+service_name</quote>
                            or to explicitly remove a PAM service name from
                            the default set by using <quote>-service_name</quote>.
                            For example, in order to replace a default PAM service
                            name for this logon right (e.g. <quote>ftp</quote>)
                            with a custom pam service name (e.g. <quote>my_pam_service</quote>),
                            you would use the following configuration:
                            <programlisting>
ad_gpo_map_network = +my_pam_service, -ftp
                            </programlisting>
                        </para>
                        <para>
                            Default: the default set of PAM service names includes:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        ftp
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        samba
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_map_batch (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of PAM service names for
                            which GPO-based access control is evaluated based on
                            the BatchLogonRight and DenyBatchLogonRight
                            policy settings.
                            Only those GPOs are evaluated for which the user has
                            Read and Apply Group Policy permission (see option
                            <quote>ad_gpo_access_control</quote>).
                            If an evaluated GPO contains the deny batch
                            logon setting for the user or one of its groups, the
                            user is denied batch logon access.
                            If none of the evaluated GPOs has a batch
                            logon right defined, the user is granted logon
                            access. If at least one evaluated GPO contains
                            batch logon right settings, the user is
                            granted logon access only, if it or at least one of
                            its groups is part of the policy settings.
                        </para>
                        <para>
                            Note: Using the Group Policy Management Editor
                            this value is called "Allow log on as a batch
                            job" and "Deny log on as a batch job".
                        </para>
                        <para>
                            It is possible to add another PAM service name
                            to the default set by using <quote>+service_name</quote>
                            or to explicitly remove a PAM service name from
                            the default set by using <quote>-service_name</quote>.
                            For example, in order to replace a default PAM service
                            name for this logon right (e.g. <quote>crond</quote>)
                            with a custom pam service name (e.g. <quote>my_pam_service</quote>),
                            you would use the following configuration:
                            <programlisting>
ad_gpo_map_batch = +my_pam_service, -crond
                            </programlisting>
                        </para>
                        <para>Note: Cron service name may differ depending on Linux distribution used.</para>
                        <para>
                            Default: the default set of PAM service names includes:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        crond
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_map_service (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of PAM service names for
                            which GPO-based access control is evaluated based on
                            the ServiceLogonRight and DenyServiceLogonRight
                            policy settings.
                            Only those GPOs are evaluated for which the user has
                            Read and Apply Group Policy permission (see option
                            <quote>ad_gpo_access_control</quote>).
                            If an evaluated GPO contains the deny service
                            logon setting for the user or one of its groups, the
                            user is denied service logon access.
                            If none of the evaluated GPOs has a service
                            logon right defined, the user is granted logon
                            access. If at least one evaluated GPO contains
                            service logon right settings, the user is
                            granted logon access only, if it or at least one of
                            its groups is part of the policy settings.
                        </para>
                        <para>
                            Note: Using the Group Policy Management Editor
                            this value is called "Allow log on as a service"
                            and "Deny log on as a service".
                        </para>
                        <para>
                            It is possible to add a PAM service name to the
                            default set by using <quote>+service_name</quote>.
                            Since the default set is empty, it is not possible
                            to remove a PAM service name from the default set.
                            For example, in order to add a custom pam service
                            name (e.g. <quote>my_pam_service</quote>), you
                            would use the following configuration:
                            <programlisting>
ad_gpo_map_service = +my_pam_service
                            </programlisting>
                        </para>
                        <para>
                          Default: not set
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_map_permit (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of PAM service names for
                            which GPO-based access is always granted, regardless
                            of any GPO Logon Rights.
                        </para>
                        <para>
                            It is possible to add another PAM service name
                            to the default set by using <quote>+service_name</quote>
                            or to explicitly remove a PAM service name from
                            the default set by using <quote>-service_name</quote>.
                            For example, in order to replace a default PAM service
                            name for unconditionally permitted access (e.g. <quote>sudo</quote>)
                            with a custom pam service name (e.g. <quote>my_pam_service</quote>),
                            you would use the following configuration:
                            <programlisting>
ad_gpo_map_permit = +my_pam_service, -sudo
                            </programlisting>
                        </para>
                        <para>
                            Default: the default set of PAM service names includes:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        polkit-1
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        sudo
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        sudo-i
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        systemd-user
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_map_deny (string)</term>
                    <listitem>
                        <para>
                            A comma-separated list of PAM service names for
                            which GPO-based access is always denied, regardless
                            of any GPO Logon Rights.
                        </para>
                        <para>
                            It is possible to add a PAM service name to the
                            default set by using <quote>+service_name</quote>.
                            Since the default set is empty, it is not possible
                            to remove a PAM service name from the default set.
                            For example, in order to add a custom pam service
                            name (e.g. <quote>my_pam_service</quote>), you
                            would use the following configuration:
                            <programlisting>
ad_gpo_map_deny = +my_pam_service
                            </programlisting>
                        </para>
                        <para>
                          Default: not set
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_gpo_default_right (string)</term>
                    <listitem>
                        <para>
                            This option defines how access control is evaluated
                            for PAM service names that are not explicitly listed
                            in one of the ad_gpo_map_* options. This option can be
                            set in two different manners. First, this option can
                            be set to use a default logon right. For example, if
                            this option is set to 'interactive', it means that
                            unmapped PAM service names will be processed based on
                            the InteractiveLogonRight and DenyInteractiveLogonRight
                            policy settings. Alternatively, this option can be set
                            to either always permit or always deny access for
                            unmapped PAM service names.
                        </para>
                        <para>
                            Supported values for this option include:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        interactive
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        remote_interactive
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        network
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        batch
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        service
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        permit
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        deny
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                        <para>
                            Default: deny
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_maximum_machine_account_password_age (integer)</term>
                    <listitem>
                        <para>
                            SSSD will check once a day if the machine account
                            password is older than the given age in days and try
                            to renew it. A value of 0 will disable the renewal
                            attempt.
                        </para>
                        <para>
                            Default: 30 days
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_machine_account_password_renewal_opts (string)</term>
                    <listitem>
                        <para>
                            This option should only be used to test the machine
                            account renewal task. The option expects 2 integers
                            separated by a colon (':'). The first integer
                            defines the interval in seconds how often the task
                            is run. The second specifies the initial timeout in
                            seconds before the task is run for the first time
                            after startup.
                        </para>
                        <para>
                            Default: 86400:750 (24h and 15m)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_update_samba_machine_account_password (boolean)</term>
                    <listitem>
                        <para>
                            If enabled, when SSSD renews the machine account
                            password, it will also be updated in Samba's
                            database. This prevents Samba's copy of the machine
                            account password from getting out of date when it is
                            set up to use AD for authentication.
                        </para>
                        <para>
                            Default: false
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_use_ldaps (bool)</term>
                    <listitem>
                        <para>
                            By default SSSD uses the plain LDAP port 389 and the
                            Global Catalog port 3628. If this option is set to
                            True SSSD will use the LDAPS port 636 and Global
                            Catalog port 3629 with LDAPS protection. Since AD
                            does not allow to have multiple encryption layers on
                            a single connection and we still want to use
                            SASL/GSSAPI or SASL/GSS-SPNEGO for authentication
                            the SASL security property maxssf is set to 0 (zero)
                            for those connections.
                        </para>
                        <para>
                            Default: False
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>ad_allow_remote_domain_local_groups (boolean)</term>
                    <listitem>
                        <para>
                            If this option is set to <quote>true</quote> SSSD
                            will not filter out Domain Local groups from remote
                            domains in the AD forest. By default they are
                            filtered out e.g. when following a nested group
                            hierarchy in remote domains because they are not
                            valid in the local domain. To be compatible with
                            other solutions which make AD users and groups
                            available on Linux client this option was added.
                        </para>
                        <para>
                            Please note that setting this option to
                            <quote>true</quote> will be against the intention of
                            Domain Local group in Active Directory and
                            <emphasis>SHOULD ONLY BE USED TO FACILITATE
                            MIGRATION FROM OTHER SOLUTIONS</emphasis>. Although
                            the group exists and user can be member of the group
                            the intention is that the group should be only used
                            in the domain it is defined and in no others. Since
                            there is only one type of POSIX groups the only way
                            to achieve this on the Linux side is to ignore those
                            groups. This is also done by Active Directory as can
                            be seen in the PAC of the Kerberos ticket for a
                            local service or in tokenGroups requests where
                            remote Domain Local groups are missing as well.
                        </para>
                        <para>
                            Given the comments above, if this option is set to
                            <quote>true</quote> the tokenGroups request must be
                            disabled by setting
                            <quote>ldap_use_tokengroups</quote> to
                            <quote>false</quote> to get consistent
                            group-memberships of a users. Additionally the
                            Global Catalog lookup should be skipped as well by
                            setting <quote>ad_enable_gc</quote> to
                            <quote>false</quote>. Finally it might be necessary
                            to modify <quote>ldap_group_nesting_level</quote> if
                            the remote Domain Local groups can only be found
                            with a deeper nesting level.
                        </para>
                        <para>
                            Default: False
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_update (boolean)</term>
                    <listitem>
                        <para>
                            Optional. This option tells SSSD to automatically
                            update the Active Directory DNS server with
                            the IP address of this client. The update is
                            secured using GSS-TSIG. As a consequence, the
                            Active Directory administrator only needs to
                            allow secure updates for the DNS zone. The IP
                            address of the AD LDAP connection is used for
                            the updates, if it is not otherwise specified
                            by using the <quote>dyndns_iface</quote> option.
                        </para>
                        <para>
                            NOTE: On older systems (such as RHEL 5), for this
                            behavior to work reliably, the default Kerberos
                            realm must be set properly in /etc/krb5.conf
                        </para>
                        <para>
                            Default: true
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_ttl (integer)</term>
                    <listitem>
                        <para>
                            The TTL to apply to the client DNS record when updating it.
                            If dyndns_update is false this has no effect. This will
                            override the TTL serverside if set by an administrator.
                        </para>
                        <para>
                            Default: 3600 (seconds)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_iface (string)</term>
                    <listitem>
                        <para>
                            Optional. Applicable only when dyndns_update
                            is true. Choose the interface or a list of interfaces
                            whose IP addresses should be used for dynamic DNS
                            updates. Special value <quote>*</quote> implies that
                            IPs from all interfaces should be used.
                        </para>
                        <para>
                            Default: Use the IP addresses of the interface which
                            is used for AD LDAP connection
                        </para>
                        <para>
                            Example: dyndns_iface = em1, vnet1, vnet2
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_refresh_interval (integer)</term>
                    <listitem>
                        <para>
                            How often should the back end perform periodic DNS update in
                            addition to the automatic update performed when the back end
                            goes online.
                            This option is optional and applicable only when dyndns_update
                            is true. Note that the lowest possible value is 60 seconds in-case
                            if value is provided less than 60, parameter will assume lowest
                            value only.
                        </para>
                        <para>
                            Default: 86400 (24 hours)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_update_ptr (bool)</term>
                    <listitem>
                        <para>
                            Whether the PTR record should also be explicitly
                            updated when updating the client's DNS records.
                            Applicable only when dyndns_update is true.
                        </para>
                        <para>
                            Note that <emphasis>dyndns_update_per_family</emphasis>
                            parameter does not apply for PTR record updates.
                            Those updates are always sent separately.
                        </para>
                        <para>
                            Default: True
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_force_tcp (bool)</term>
                    <listitem>
                        <para>
                            Whether the nsupdate utility should default to using
                            TCP for communicating with the DNS server.
                        </para>
                        <para>
                            Default: False (let nsupdate choose the protocol)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_auth (string)</term>
                    <listitem>
                        <para>
                            Whether the nsupdate utility should use GSS-TSIG
                            authentication for secure updates with the DNS
                            server, insecure updates can be sent by setting
                            this option to 'none'.
                        </para>
                        <para>
                            Default: GSS-TSIG
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_auth_ptr (string)</term>
                    <listitem>
                        <para>
                            Whether the nsupdate utility should use GSS-TSIG
                            authentication for secure PTR updates with the DNS
                            server, insecure updates can be sent by setting
                            this option to 'none'.
                        </para>
                        <para>
                            Default: Same as dyndns_auth
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_server (string)</term>
                    <listitem>
                        <para>
                            The DNS server to use when performing a DNS
                            update. In most setups, it's recommended to leave
                            this option unset.
                        </para>
                        <para>
                            Setting this option makes sense for environments
                            where the DNS server is different from the identity
                            server.
                        </para>
                        <para>
                            Please note that this option will be only used in
                            fallback attempt when previous attempt using
                            autodetected settings failed.
                        </para>
                        <para>
                            Default: None (let nsupdate choose the server)
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>dyndns_update_per_family (boolean)</term>
                    <listitem>
                        <para>
                            DNS update is by default performed in two steps -
                            IPv4 update and then IPv6 update. In some cases
                            it might be desirable to perform IPv4 and IPv6
                            update in single step.
                        </para>
                        <para>
                            Default: true
                        </para>
                    </listitem>
                </varlistentry>

                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/override_homedir.xml" />
                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/homedir_substring.xml" />

                <varlistentry>
                    <term>krb5_confd_path (string)</term>
                    <listitem>
                        <para>
                            Absolute path of a directory where SSSD should place
                            Kerberos configuration snippets.
                        </para>
                        <para>
                            To disable the creation of the configuration
                            snippets set the parameter to 'none'.
                        </para>
                        <para>
                            Default: not set (krb5.include.d subdirectory of
                            SSSD's pubconf directory)
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/ad_modified_defaults.xml" />

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/failover.xml" />

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/service_discovery.xml" />

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/ldap_id_mapping.xml" />

    <refsect1 id='example'>
        <title>EXAMPLE</title>
        <para>
            The following example assumes that SSSD is correctly
            configured and example.com is one of the domains in the
            <replaceable>[sssd]</replaceable> section. This example shows only
            the AD provider-specific options.
        </para>
        <para>
<programlisting>
[domain/EXAMPLE]
id_provider = ad
auth_provider = ad
access_provider = ad
chpass_provider = ad

ad_server = dc1.example.com
ad_hostname = client.example.com
ad_domain = example.com
</programlisting>
        </para>
    </refsect1>

    <refsect1 id='notes'>
        <title>NOTES</title>
        <para>
            The AD access control provider checks if the account is expired.
            It has the same effect as the following configuration of the LDAP
            provider:
<programlisting>
access_provider = ldap
ldap_access_order = expire
ldap_account_expire_policy = ad
</programlisting>
        </para>
        <para>
            However, unless the <quote>ad</quote> access control provider
            is explicitly configured, the default access provider is
            <quote>permit</quote>. Please note that if you configure an
            access provider other than <quote>ad</quote>, you need to set
            all the connection parameters (such as LDAP URIs and encryption
            details) manually.
        </para>
        <para>
            When the autofs provider is set to <quote>ad</quote>, the RFC2307
            schema attribute mapping (nisMap, nisObject, ...) is used,
            because these attributes are included in the default Active
            Directory schema.
        </para>
        <para>
        </para>
    </refsect1>

	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />

</refentry>
</reference>