<?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.

</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 is able to provide identity information and

authentication for entities from trusted domains as well. Currently

only trusted domains in the same forest are recognized.

</para>

<para>

The AD provider accepts the same options used by 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 some exceptions described

below.

</para>

<para>

However, it is neither necessary nor recommended to set these

options. The AD provider can also be used as an access, chpass and

sudo provider. No configuration of the access provider is required

on the client side.

</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>

In order to retrieve users and groups using POSIX attributes from trusted

domains, the AD administrator must make sure that the POSIX attributes

are replicated to the Global Catalog.

</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>

</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_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.

This is optional if autodiscovery is enabled.

For more information on service discovery, refer

to the <quote>SERVICE DISCOVERY</quote> section.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>ad_hostname (string)</term>

<listitem>

<para>

Optional. May be set on machines where the

hostname(5) does not reflect the fully qualified

name used in the Active Directory domain to

identify this host.

</para>

<para>

This field is used to determine the host principal

in use in the keytab. 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>

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)

</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 a particular

host.

</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.

</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_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.

</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>

</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.

</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>

</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.

</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.

</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>

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.

</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>

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>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 whose IP address

should be used for dynamic DNS updates.

</para>

<para>

NOTE: This option currently supports only one interface.

</para>

<para>

Default: Use the IP address of the AD LDAP connection

</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.

</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>

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>

<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_use_enterprise_principal (boolean)</term>

<listitem>

<para>

Specifies if the user principal should be treated

as enterprise principal. See section 5 of RFC 6806

for more details about enterprise principals.

</para>

<para>

Default: true

</para>

<para>

Note that this default differs from the

traditional Kerberos provider back end.

</para>

</listitem>

</varlistentry>

<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/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>

</refsect1>

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

</refentry>

</reference>