f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<refsect1 id='idmap'>

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <title>ID MAPPING</title>

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <para>

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz The ID-mapping feature allows SSSD to act as a client of Active

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz Directory without requiring administrators to extend user attributes

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz to support POSIX attributes for user and group identifiers.

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd NOTE: When ID-mapping is enabled, the uidNumber and gidNumber

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd attributes are ignored. This is to avoid the possibility of conflicts

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen between automatically-assigned and manually-assigned values. If you

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen need to use manually-assigned values, ALL values must be

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen manually-assigned.

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen </para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd Please note that changing the ID mapping related configuration

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd options will cause user and group IDs to change. At the moment,

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd SSSD does not support changing IDs, so the SSSD database must

3f08db06526d6901aa08c110b5bc7dde6bc39905nd be removed. Because cached passwords are also stored in the

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd database, removing the database should only be performed while

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd the authentication servers are reachable, otherwise users might

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd get locked out. In order to cache the password, an authentication

3f08db06526d6901aa08c110b5bc7dde6bc39905nd must be performed. It is not sufficient to use

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <citerefentry>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <refentrytitle>sss_cache</refentrytitle>

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <manvolnum>8</manvolnum>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd </citerefentry>

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd to remove the database, rather the process

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung consists of:

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <itemizedlist>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <listitem>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd Making sure the remote servers are reachable

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </listitem>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <listitem>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz Stopping the SSSD service

aa0b2780958e9b1467c9d0153a05738e399811a5nd </para>

aa0b2780958e9b1467c9d0153a05738e399811a5nd </listitem>

aa0b2780958e9b1467c9d0153a05738e399811a5nd <listitem>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd Removing the database

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </listitem>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <listitem>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd Starting the SSSD service

9335f6d807d76d60e54af4ededdebebddb3e3d13noodl </para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </listitem>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </itemizedlist>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd Moreover, as the change of IDs might necessitate the adjustment

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd of other system properties such as file and directory ownership,

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd it's advisable to plan ahead and test the ID mapping configuration

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd thoroughly.

89507e27e4d31a7e97f258994e4ba3904de47652nd </para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <refsect2 id='idmap_algorithm'>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <title>Mapping Algorithm</title>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd Active Directory provides an objectSID for every user and group

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd object in the directory. This objectSID can be broken up into

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz components that represent the Active Directory domain identity and

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz the relative identifier (RID) of the user or group object.

89507e27e4d31a7e97f258994e4ba3904de47652nd </para>

aa0b2780958e9b1467c9d0153a05738e399811a5nd <para>

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz The SSSD ID-mapping algorithm takes a range of available UIDs and

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz divides it into equally-sized component sections - called

aa0b2780958e9b1467c9d0153a05738e399811a5nd "slices"-. Each slice represents the space available to an Active

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz Directory domain.

aa0b2780958e9b1467c9d0153a05738e399811a5nd </para>

aa0b2780958e9b1467c9d0153a05738e399811a5nd <para>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf When a user or group entry for a particular domain is encountered

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz for the first time, the SSSD allocates one of the available slices

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz for that domain. In order to make this slice-assignment repeatable

aa0b2780958e9b1467c9d0153a05738e399811a5nd on different client machines, we select the slice based on the

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz following algorithm:

aa0b2780958e9b1467c9d0153a05738e399811a5nd </para>

aa0b2780958e9b1467c9d0153a05738e399811a5nd <para>

aa0b2780958e9b1467c9d0153a05738e399811a5nd The SID string is passed through the murmurhash3 algorithm to

aa0b2780958e9b1467c9d0153a05738e399811a5nd convert it to a 32-bit hashed value. We then take the modulus of

aa0b2780958e9b1467c9d0153a05738e399811a5nd this value with the total number of available slices to pick the

f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz slice.

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd </para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <para>

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd NOTE: It is possible to encounter collisions in the hash and

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd subsequent modulus. In these situations, we will select the next

a78048ccbdb6256da15e6b0e7e95355e480c2301nd available slice, but it may not be possible to reproduce the same

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd exact set of slices on other machines (since the order that they

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung are encountered will determine their slice). In this situation, it

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd is recommended to either switch to using explicit POSIX attributes

5effc8b39fae5cd169d17f342bfc265705840014rbowen in Active Directory (disabling ID-mapping) or configure a default

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen domain to guarantee that at least one is always consistent. See

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen <quote>Configuration</quote> for details.

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen </para>

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen </refsect2>

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen

bdd978e5ecd8daa2542d4d4e1988c78a622cd7f4nd <refsect2 id='idmap_config'>

<title>Configuration</title>

<para>

Minimum configuration (in the <quote>[domain/DOMAINNAME]</quote>

section):

</para>

<para>

<programlisting>

ldap_id_mapping = True

ldap_schema = ad

</programlisting>

</para>

<para>

The default configuration results in configuring 10,000 slices,

each capable of holding up to 200,000 IDs, starting from 200,000

and going up to 2,000,200,000. This should be sufficient for

most deployments.

</para>

<refsect3 id='idmap_advanced_config'>

<title>Advanced Configuration</title>

<variablelist>

<varlistentry>

<term>ldap_idmap_range_min (integer)</term>

<listitem>

<para>

Specifies the lower bound of the range of POSIX IDs to

use for mapping Active Directory user and group SIDs.

</para>

<para>

NOTE: This option is different from

<quote>min_id</quote> in that <quote>min_id</quote>

acts to filter the output of requests to this domain,

whereas this option controls the range of ID

assignment. This is a subtle distinction, but the

good general advice would be to have

<quote>min_id</quote> be less-than or equal to

<quote>ldap_idmap_range_min</quote>

</para>

<para>

Default: 200000

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>ldap_idmap_range_max (integer)</term>

<listitem>

<para>

Specifies the upper bound of the range of POSIX IDs to

use for mapping Active Directory user and group SIDs.

</para>

<para>

NOTE: This option is different from

<quote>max_id</quote> in that <quote>max_id</quote>

acts to filter the output of requests to this domain,

whereas this option controls the range of ID

assignment. This is a subtle distinction, but the

good general advice would be to have

<quote>max_id</quote> be greater-than or equal to

<quote>ldap_idmap_range_max</quote>

</para>

<para>

Default: 2000200000

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>ldap_idmap_range_size (integer)</term>

<listitem>

<para>

Specifies the number of IDs available for each slice.

If the range size does not divide evenly into the min

and max values, it will create as many complete slices

as it can.

</para>

<para>

NOTE: The value of this option must be at least as large as the

highest user RID planned for use on the Active Directory server. User

lookups and login will fail for any user whose RID is greater than

this value.

</para>

<para>

For example, if your most recently-added Active Directory user has

objectSid=S-1-5-21-2153326666-2176343378-3404031434-1107,

<quote>ldap_idmap_range_size</quote> must be at least 1108 as

range size is equal to maximal SID minus minimal SID plus one

(e.g. 1108 = 1107 - 0 + 1).

</para>

<para>

It is important to plan ahead for future expansion, as changing this

value will result in changing all of the ID mappings on the system,

leading to users with different local IDs than they previously had.

</para>

<para>

Default: 200000

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>ldap_idmap_default_domain_sid (string)</term>

<listitem>

<para>

Specify the domain SID of the default domain. This

will guarantee that this domain will always be

assigned to slice zero in the ID map, bypassing

the murmurhash algorithm described above.

</para>

<para>

Default: not set

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>ldap_idmap_default_domain (string)</term>

<listitem>

<para>

Specify the name of the default domain.

</para>

<para>

Default: not set

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>ldap_idmap_autorid_compat (boolean)</term>

<listitem>

<para>

Changes the behavior of the ID-mapping algorithm

to behave more similarly to winbind's

<quote>idmap_autorid</quote> algorithm.

</para>

<para>

When this option is configured, domains will be

allocated starting with slice zero and increasing

monatomically with each additional domain.

</para>

<para>

NOTE: This algorithm is non-deterministic (it

depends on the order that users and groups are

requested). If this mode is required for

compatibility with machines running winbind, it

is recommended to also use the

<quote>ldap_idmap_default_domain_sid</quote>

option to guarantee that at least one domain is

consistently allocated to slice zero.

</para>

<para>

Default: False

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>ldap_idmap_helper_table_size (integer)</term>

<listitem>

<para>

Maximal number of secondary slices that is tried when

performing mapping from UNIX id to SID.

</para>

<para>

Note: Additional secondary slices might be generated

when SID is being mapped to UNIX id and RID part of

SID is out of range for secondary slices generated so

far. If value of ldap_idmap_helper_table_size is equal

to 0 then no additional secondary slices are

generated.

</para>

<para>

Default: 10

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect3>

</refsect2>

<refsect2 id='well_known_sids'>

<title>Well-Known SIDs</title>

<para>

SSSD supports to look up the names of Well-Known SIDs, i.e. SIDs

with a special hardcoded meaning. Since the generic users and groups

related to those Well-Known SIDs have no equivalent in a Linux/UNIX

environment no POSIX IDs are available for those objects.

</para>

<para>

The SID name space is organized in authorities which can be seen as

different domains. The authorities for the Well-Known SIDs are

<itemizedlist>

<listitem><para>Null Authority</para></listitem>

<listitem><para>World Authority</para></listitem>

<listitem><para>Local Authority</para></listitem>

<listitem><para>Creator Authority</para></listitem>

<listitem><para>NT Authority</para></listitem>

<listitem><para>Built-in</para></listitem>

</itemizedlist>

The capitalized version of these names are used as domain names when

returning the fully qualified name of a Well-Known SID.

</para>

<para>

Since some utilities allow to modify SID based access control

information with the help of a name instead of using the SID

directly SSSD supports to look up the SID by the name as well. To

avoid collisions only the fully qualified names can be used to look

up Well-Known SIDs. As a result the domain names <quote>NULL

AUTHORITY</quote>, <quote>WORLD AUTHORITY</quote>, <quote> LOCAL

AUTHORITY</quote>, <quote>CREATOR AUTHORITY</quote>, <quote>NT

AUTHORITY</quote> and <quote>BUILTIN</quote> should not be used as

domain names in <filename>sssd.conf</filename>.

</para>

</refsect2>

</refsect1>