openshift-docs/modules/ldap-syncing-spec.adoc

// Module included in the following assemblies:
//
// * authentication/ldap-syncing.adoc

[id="ldap-syncing-spec_{context}"]
= LDAP sync configuration specification

The object specification for the configuration file is below.  Note that the different schema
objects have different fields.  For example, v1.ActiveDirectoryConfig has no `groupsQuery`
field whereas v1.RFC2307Config and v1.AugmentedActiveDirectoryConfig both do.

[IMPORTANT]
====
There is no support for binary attributes. All attribute data coming from the
LDAP server must be in the format of a UTF-8 encoded string. For example, never
use a binary attribute, such as `objectGUID`, as an ID attribute. You must use
string attributes, such as `sAMAccountName` or `userPrincipalName`, instead.
====

[[sync-ldap-v1-ldapsyncconfig]]
== v1.LDAPSyncConfig

`LDAPSyncConfig` holds the necessary configuration options to define an LDAP
group sync.

[options="header"]
|===
|Name |Description |Schema

|`kind`
|String value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds[]
|string

|`apiVersion`
|Defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources[]
|string

|`url`
|Host is the scheme, host and port of the LDAP server to connect to: `scheme://host:port`
|string

|`bindDN`
|Optional DN to bind to the LDAP server with.
|string

|`bindPassword`
|Optional password to bind with during the search phase. |v1.StringSource

|`insecure`
|If `true`, indicates the connection should not use TLS. If `false`, `ldaps://` URLs connect using TLS, and `ldap://` URLs are upgraded to a TLS connection using StartTLS as specified in link:https://tools.ietf.org/html/rfc2830[]. If you set `insecure` to `true`, you cannot use `ldaps://` URL schemes.
|boolean

|`ca`
|Optional trusted certificate authority bundle to use when making requests to the server. If empty, the default system roots are used.
|string

|`groupUIDNameMapping`
|Optional direct mapping of LDAP group UIDs to {product-title} group names.
|object

|`rfc2307`
|Holds the configuration for extracting data from an LDAP server set up in a fashion similar to RFC2307: first-class group and user entries, with group membership determined by a multi-valued attribute on the group entry listing its members.
|v1.RFC2307Config

|`activeDirectory`
|Holds the configuration for extracting data from an LDAP server set up in a fashion similar to that used in Active Directory: first-class user entries, with group membership determined by a multi-valued attribute on members listing groups they are a member of.
|v1.ActiveDirectoryConfig

|`augmentedActiveDirectory`
|Holds the configuration for extracting data from an LDAP server set up in a fashion similar to that used in Active Directory as described above, with one addition: first-class group entries exist and are used to hold metadata but not group membership.
|v1.AugmentedActiveDirectoryConfig
|===

[[sync-ldap-v1-stringsource]]
== v1.StringSource

`StringSource` allows specifying a string inline, or externally via environment
variable or file. When it contains only a string value, it marshals to a simple
JSON string.

[options="header"]
|===
|Name |Description |Schema

|`value`
|Specifies the cleartext value, or an encrypted value if `keyFile` is specified.
|string

|`env`
|Specifies an environment variable containing the cleartext value, or an
encrypted value if the `keyFile` is specified.
|string

|`file`
|References a file containing the cleartext value, or an encrypted value if a `keyFile` is specified.
|string

|`keyFile`
|References a file containing the key to use to decrypt the value.
|string
|===

[[sync-ldap-v1-ldapquery]]
== v1.LDAPQuery

`LDAPQuery` holds the options necessary to build an LDAP query.

[options="header"]
|===
|Name |Description |Schema

|`baseDN`
|DN of the branch of the directory where all searches should start from.
|string

|`scope`
|The optional scope of the search. Can be `base`: only the base object, `one`:
all objects on the base level, `sub`: the entire subtree. Defaults to `sub`
if not set.
|string

|`derefAliases`
|The optional behavior of the search with regards to aliases. Can be `never`:
never dereference aliases, `search`: only dereference in searching, `base`:
only dereference in finding the base object, `always`: always dereference.
Defaults to `always` if not set.
|string

|`timeout`
|Holds the limit of time in seconds that any request to the server can remain outstanding before the wait for a response is given up. If this is `0`, no client-side limit is imposed.
|integer

|`filter`
|A valid LDAP search filter that retrieves all relevant entries from the LDAP server with the base DN.
|string

|`pageSize`
|Maximum preferred page size, measured in LDAP entries. A page size of `0` means no paging will be done.
|integer
|===

[[sync-ldap-v1-rfc2307config]]
== v1.RFC2307Config

`RFC2307Config` holds the necessary configuration options to define how an LDAP
group sync interacts with an LDAP server using the RFC2307 schema.

[options="header"]
|===
|Name |Description |Schema

|`groupsQuery`
|Holds the template for an LDAP query that returns group entries.
|v1.LDAPQuery

|`groupUIDAttribute`
|Defines which attribute on an LDAP group entry will be interpreted as its unique identifier. (`ldapGroupUID`)
|string

|`groupNameAttributes`
|Defines which attributes on an LDAP group entry will be interpreted as its name to use for an {product-title} group.
|string array

|`groupMembershipAttributes`
|Defines which attributes on an LDAP group entry will be interpreted as its members. The values contained in those attributes must be queryable by your `UserUIDAttribute`.
|string array

|`usersQuery`
|Holds the template for an LDAP query that returns user entries.
|v1.LDAPQuery

|`userUIDAttribute`
|Defines which attribute on an LDAP user entry will be interpreted as its unique identifier. It must correspond to values that will be found from the `GroupMembershipAttributes`.
|string

|`userNameAttributes`
|Defines which attributes on an LDAP user entry will be used, in order, as its {product-title} user name. The first attribute with a non-empty value is used. This should match your `PreferredUsername` setting for your `LDAPPasswordIdentityProvider`. The attribute to use as the name of the user in the {product-title} group
record. `mail` or `sAMAccountName` are preferred choices in most installations.
|string array

|`tolerateMemberNotFoundErrors`
|Determines the behavior of the LDAP sync job when missing user entries are encountered. If `true`, an LDAP query for users that does not find any will be tolerated and an only and error will be logged. If `false`, the LDAP sync job will fail if a query for users does not find any. The default value is `false`. Misconfigured LDAP sync jobs with this flag set to `true` can cause group membership to be removed, so it is recommended to use this flag with caution.
|boolean

|`tolerateMemberOutOfScopeErrors`
|Determines the behavior of the LDAP sync job when out-of-scope user entries are encountered. If `true`, an LDAP query for a user that falls outside of the base DN given for the all user query will be tolerated and only an error will be logged. If `false`, the LDAP sync job will fail if a user query would search outside of the base DN specified by the all user query. Misconfigured LDAP sync jobs with this flag set to `true` can result in groups missing users, so it is recommended to use this flag with caution.
|boolean
|===

[[sync-ldap-v1-activedirectoryconfig]]
== v1.ActiveDirectoryConfig

`ActiveDirectoryConfig` holds the necessary configuration options to define how
an LDAP group sync interacts with an LDAP server using the Active Directory
schema.

[options="header"]
|===
|Name |Description |Schema

|`usersQuery`
|Holds the template for an LDAP query that returns user entries.
|v1.LDAPQuery

|`userNameAttributes`
|Defines which attributes on an LDAP user entry will be interpreted as its {product-title} user name. The attribute to use as the name of the user in the {product-title} group
record. `mail` or `sAMAccountName` are preferred choices in most installations.
|string array

|`groupMembershipAttributes`
|Defines which attributes on an LDAP user entry will be interpreted as the groups it is a member of.
|string array
|===

[[sync-ldap-v1-augmentedactivedirectoryconfig]]
== v1.AugmentedActiveDirectoryConfig

`AugmentedActiveDirectoryConfig` holds the necessary configuration options to
define how an LDAP group sync interacts with an LDAP server using the augmented
Active Directory schema.

[options="header"]
|===
|Name |Description |Schema

|`usersQuery`
|Holds the template for an LDAP query that returns user entries.
|v1.LDAPQuery

|`userNameAttributes`
|Defines which attributes on an LDAP user entry will be interpreted as its {product-title} user name. The attribute to use as the name of the user in the {product-title} group
record. `mail` or `sAMAccountName` are preferred choices in most installations.
|string array

|`groupMembershipAttributes`
|Defines which attributes on an LDAP user entry will be interpreted as the groups it is a member of.
|string array

|`groupsQuery`
|Holds the template for an LDAP query that returns group entries.
|v1.LDAPQuery

|`groupUIDAttribute`
|Defines which attribute on an LDAP group entry will be interpreted as its unique identifier. (`ldapGroupUID`)
|string

|`groupNameAttributes`
|Defines which attributes on an LDAP group entry will be interpreted as its name to use for an {product-title} group.
|string array
|===