Syncing Groups With LDAP | Installation and Configuration

Overview

As an OKD administrator, you can use groups to manage users, change their permissions, and enhance collaboration. Your organization may have already created user groups and stored them in an LDAP server. OKD can sync those LDAP records with internal OKD records, enabling you to manage your groups in one place. OKD currently supports group sync with LDAP servers using three common schemas for defining group membership: RFC 2307, Active Directory, and augmented Active Directory.

You must have cluster-admin privileges to sync groups.

Configuring LDAP Sync

Before you can run LDAP sync, you need a sync configuration file. This file contains LDAP client configuration details:

Configuration for connecting to your LDAP server.
Sync configuration options that are dependent on the schema used in your LDAP server.

A sync configuration file can also contain an administrator-defined list of name mappings that maps OKD Group names to groups in your LDAP server.

LDAP Client Configuration

Example 1. LDAP Client Configuration

url: ldap://10.0.0.0:389 (1)
bindDN: cn=admin,dc=example,dc=com (2)
bindPassword: password (3)
insecure: false (4)
ca: my-ldap-ca-bundle.crt (5)

1	The connection protocol, IP address of the LDAP server hosting your database, and the port to connect to, formatted as `scheme://host:port`.
2	Optional distinguished name (DN) to use as the Bind DN. OKD uses this if elevated privilege is required to retrieve entries for the sync operation.
3	Optional password to use to bind. OKD uses this if elevated privilege is necessary to retrieve entries for the sync operation. This value may also be provided in an environment variable, external file, or encrypted file.
4	When `true`, no TLS connection is made to the server. When `false`, secure LDAP (`ldaps://`) URLs connect using TLS, and insecure LDAP (`ldap://`) URLs are upgraded to TLS.
5	The certificate bundle to use for validating server certificates for the configured URL. If empty, OKD uses system-trusted roots. This only applies if `insecure` is set to `false`.

LDAP Query Definition

Sync configurations consist of LDAP query definitions for the entries that are required for synchronization. The specific definition of an LDAP query depends on the schema used to store membership information in the LDAP server.

Example 2. LDAP Query Definition

baseDN: ou=users,dc=example,dc=com (1)
scope: sub (2)
derefAliases: never (3)
timeout: 0 (4)
filter: (objectClass=inetOrgPerson) (5)
pageSize: 0 (6)

1	The distinguished name (DN) of the branch of the directory where all searches will start from. It is required that you specify the top of your directory tree, but you can also specify a subtree in the directory.
2	The scope of the search. Valid values are `base`, `one`, or `sub`. If this is left undefined, then a scope of `sub` is assumed. Descriptions of the scope options can be found in the table below.
3	The behavior of the search with respect to aliases in the LDAP tree. Valid values are `never`, `search`, `base`, or `always`. If this is left undefined, then the default is to `always` dereference aliases. Descriptions of the dereferencing behaviors can be found in the table below.
4	The time limit allowed for the search by the client, in seconds. A value of 0 imposes no client-side limit.
5	A valid LDAP search filter. If this is left undefined, then the default is `(objectClass=*)`.
6	The optional maximum size of response pages from the server, measured in LDAP entries. If set to 0, no size restrictions will be made on pages of responses. Setting paging sizes is necessary when queries return more entries than the client or server allow by default.

Table 1. LDAP Search Scope Options
LDAP Search Scope	Description
`base`	Only consider the object specified by the base DN given for the query.
`one`	Consider all of the objects on the same level in the tree as the base DN for the query.
`sub`	Consider the entire subtree rooted at the base DN given for the query.

Table 2. LDAP Dereferencing Behaviors
Dereferencing Behavior	Description
`never`	Never dereference any aliases found in the LDAP tree.
`search`	Only dereference aliases found while searching.
`base`	Only dereference aliases while finding the base object.
`always`	Always dereference all aliases found in the LDAP tree.

User-Defined Name Mapping

A user-defined name mapping explicitly maps the names of OKD Groups to unique identifiers that find groups on your LDAP server. The mapping uses normal YAML syntax. A user-defined mapping can contain an entry for every group in your LDAP server or only a subset of those groups. If there are groups on the LDAP server that do not have a user-defined name mapping, the default behavior during sync is to use the attribute specified as the Group’s name.

Example 3. User-Defined Name Mapping

groupUIDNameMapping:
  "cn=group1,ou=groups,dc=example,dc=com": firstgroup
  "cn=group2,ou=groups,dc=example,dc=com": secondgroup
  "cn=group3,ou=groups,dc=example,dc=com": thirdgroup

Running LDAP Sync

Once you have created a sync configuration file, then sync can begin. OKD allows administrators to perform a number of different sync types with the same server.

By default, all group synchronization or pruning operations are dry-run, so you must set the --confirm flag on the sync-groups command in order to make changes to OKD Group records.

To sync all groups from the LDAP server with OKD:

$ oc adm groups sync --sync-config=config.yaml --confirm

To sync all Groups already in OKD that correspond to groups in the LDAP server specified in the configuration file:

$ oc adm groups sync --type=openshift --sync-config=config.yaml --confirm

To sync a subset of LDAP groups with OKD, you can use whitelist files, blacklist files, or both:

Any combination of blacklist files, whitelist files, or whitelist literals will work; whitelist literals can be included directly in the command itself. This applies to groups found on LDAP servers, as well as Groups already present in OKD. Your files must contain one unique group identifier per line.

$ oc adm groups sync --whitelist=<whitelist_file> \
                   --sync-config=config.yaml    \
                   --confirm
$ oc adm groups sync --blacklist=<blacklist_file> \
                   --sync-config=config.yaml    \
                   --confirm
$ oc adm groups sync <group_unique_identifier>    \
                   --sync-config=config.yaml    \
                   --confirm
$ oc adm groups sync <group_unique_identifier>    \
                   --whitelist=<whitelist_file> \
                   --blacklist=<blacklist_file> \
                   --sync-config=config.yaml    \
                   --confirm
$ oc adm groups sync --type=openshift             \
                   --whitelist=<whitelist_file> \
                   --sync-config=config.yaml    \
                   --confirm

Running a Group Pruning Job

An administrator can also choose to remove groups from OKD records if the records on the LDAP server that created them are no longer present. The prune job will accept the same sync configuration file and white- or black-lists as used for the sync job.

For example, if groups had previously been synchronized from LDAP using some config.yaml file, and some of those groups no longer existed on the LDAP server, the following command would determine which Groups in OKD corresponded to the deleted groups in LDAP and then remove them from OKD:

$ oc adm groups prune --sync-config=config.yaml --confirm

Sync Examples

This section contains examples for the RFC 2307, Active Directory, and augmented Active Directory schemas. All of the following examples synchronize a group named admins that has two members: Jane and Jim. Each example explains:

How the group and users are added to the LDAP server.
What the LDAP sync configuration file looks like.
What the resulting Group record in OKD will be after synchronization.

These examples assume that all users are direct members of their respective groups. Specifically, no groups have other groups as members. See Nested Membership Sync Example for information on how to sync nested groups.

RFC 2307

In the RFC 2307 schema, both users (Jane and Jim) and groups exist on the LDAP server as first-class entries, and group membership is stored in attributes on the group. The following snippet of ldif defines the users and group for this schema:

Example 4. LDAP Entries Using RFC 2307 Schema: rfc2307.ldif

  dn: ou=users,dc=example,dc=com
  objectClass: organizationalUnit
  ou: users

  dn: cn=Jane,ou=users,dc=example,dc=com
  objectClass: person
  objectClass: organizationalPerson
  objectClass: inetOrgPerson
  cn: Jane
  sn: Smith
  displayName: Jane Smith
  mail: jane.smith@example.com

  dn: cn=Jim,ou=users,dc=example,dc=com
  objectClass: person
  objectClass: organizationalPerson
  objectClass: inetOrgPerson
  cn: Jim
  sn: Adams
  displayName: Jim Adams
  mail: jim.adams@example.com

  dn: ou=groups,dc=example,dc=com
  objectClass: organizationalUnit
  ou: groups

  dn: cn=admins,ou=groups,dc=example,dc=com (1)
  objectClass: groupOfNames
  cn: admins
  owner: cn=admin,dc=example,dc=com
  description: System Administrators
  member: cn=Jane,ou=users,dc=example,dc=com (2)
  member: cn=Jim,ou=users,dc=example,dc=com

1	The group is a first-class entry in the LDAP server.
2	Members of a group are listed with an identifying reference as attributes on the group.

To sync this group, you must first create the configuration file. The RFC 2307 schema requires you to provide an LDAP query definition for both user and group entries, as well as the attributes with which to represent them in the internal OKD records.

For clarity, the Group you create in OKD should use attributes other than the distinguished name whenever possible for user- or administrator-facing fields. For example, identify the users of a Group by their e-mail, and use the name of the group as the common name. The following configuration file creates these relationships:

If using user-defined name mappings, your configuration file will differ.

Example 5. LDAP Sync Configuration Using RFC 2307 Schema: rfc2307_config.yaml

kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389 (1)
insecure: false (2)
rfc2307:
    groupsQuery:
        baseDN: "ou=groups,dc=example,dc=com"
        scope: sub
        derefAliases: never
        pageSize: 0
    groupUIDAttribute: dn (3)
    groupNameAttributes: [ cn ] (4)
    groupMembershipAttributes: [ member ] (5)
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        pageSize: 0
    userUIDAttribute: dn (6)
    userNameAttributes: [ uid ] (7)
    tolerateMemberNotFoundErrors: false
    tolerateMemberOutOfScopeErrors: false

1	The IP address and host of the LDAP server where this group’s record is stored.
2	When `true`, no TLS connection is made to the server. When `false`, secure LDAP (`ldaps://`) URLs connect using TLS, and insecure LDAP (`ldap://`) URLs are upgraded to TLS.
3	The attribute that uniquely identifies a group on the LDAP server. You cannot specify `groupsQuery` filters when using DN for groupUIDAttribute. For fine-grained filtering, use the whitelist / blacklist method.
4	The attribute to use as the name of the Group.
5	The attribute on the group that stores the membership information.
6	The attribute that uniquely identifies a user on the LDAP server. You cannot specify `usersQuery` filters when using DN for userUIDAttribute. For fine-grained filtering, use the whitelist / blacklist method.
7	The attribute to use as the name of the user in the OKD Group record.

To run sync with the rfc2307_config.yaml file:

$ oc adm groups sync --sync-config=rfc2307_config.yaml --confirm

OKD creates the following Group record as a result of the above sync operation:

Example 6. OKD Group Created Using rfc2307_config.yaml

apiVersion: v1
kind: Group
metadata:
  annotations:
    openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 (1)
    openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com (2)
    openshift.io/ldap.url: LDAP_SERVER_IP:389 (3)
  creationTimestamp:
  name: admins (4)
users: (5)
- jane.smith@example.com
- jim.adams@example.com

1	The last time this Group was synchronized with the LDAP server, in ISO 6801 format.
2	The unique identifier for the group on the LDAP server.
3	The IP address and host of the LDAP server where this Group’s record is stored.
4	The name of the Group as specified by the sync file.
5	The users that are members of the Group, named as specified by the sync file.

RFC2307 with User-Defined Name Mappings

When syncing groups with user-defined name mappings, the configuration file changes to contain these mappings as shown below.

Example 7. LDAP Sync Configuration Using RFC 2307 Schema With User-Defined Name Mappings: rfc2307_config_user_defined.yaml

kind: LDAPSyncConfig
apiVersion: v1
groupUIDNameMapping:
  "cn=admins,ou=groups,dc=example,dc=com": Administrators (1)
rfc2307:
    groupsQuery:
        baseDN: "ou=groups,dc=example,dc=com"
        scope: sub
        derefAliases: never
        pageSize: 0
    groupUIDAttribute: dn (2)
    groupNameAttributes: [ cn ] (3)
    groupMembershipAttributes: [ member ]
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        pageSize: 0
    userUIDAttribute: dn (4)
    userNameAttributes: [ uid ]
    tolerateMemberNotFoundErrors: false
    tolerateMemberOutOfScopeErrors: false

1	The user-defined name mapping.
2	The unique identifier attribute that is used for the keys in the user-defined name mapping. You cannot specify `groupsQuery` filters when using DN for groupUIDAttribute. For fine-grained filtering, use the whitelist / blacklist method.
3	The attribute to name OKD Groups with if their unique identifier is not in the user-defined name mapping.
4	The attribute that uniquely identifies a user on the LDAP server. You cannot specify `usersQuery` filters when using DN for userUIDAttribute. For fine-grained filtering, use the whitelist / blacklist method.

To run sync with the rfc2307_config_user_defined.yaml file:

$ oc adm groups sync --sync-config=rfc2307_config_user_defined.yaml --confirm

OKD creates the following Group record as a result of the above sync operation:

Example 8. OKD Group Created Using rfc2307_config_user_defined.yaml

apiVersion: v1
kind: Group
metadata:
  annotations:
    openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400
    openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com
    openshift.io/ldap.url: LDAP_SERVER_IP:389
  creationTimestamp:
  name: Administrators (1)
users:
- jane.smith@example.com
- jim.adams@example.com

1	The name of the Group as specified by the user-defined name mapping.

RFC 2307 with User-Defined Error Tolerances

By default, if the groups being synced contain members whose entries are outside of the scope defined in the member query, the group sync fails with an error:

Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in group "<group>" failed because of "search for entry with dn="<user-dn>" would search outside of the base dn specified (dn="<base-dn>")".

This often indicates a mis-configured baseDN in the usersQuery field. However, in cases where the baseDN intentionally does not contain some of the members of the group, setting tolerateMemberOutOfScopeErrors: true allows the group sync to continue. Out of scope members will be ignored.

Similarly, when the group sync process fails to locate a member for a group, it fails outright with errors:

Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in group "<group>" failed because of "search for entry with base dn="<user-dn>" refers to a non-existent entry".

Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in group "<group>" failed because of "search for entry with base dn="<user-dn>" and filter "<filter>" did not return any results".

This often indicates a mis-configured usersQuery field. However, in cases where the group contains member entries that are known to be missing, setting tolerateMemberNotFoundErrors: true allows the group sync to continue. Problematic members will be ignored.

Enabling error tolerances for the LDAP group sync causes the sync process to ignore problematic member entries. If the LDAP group sync is not configured correctly, this could result in synced OKD groups missing members.

Example 9. LDAP Entries Using RFC 2307 Schema With Problematic Group Membership: rfc2307_problematic_users.ldif

  dn: ou=users,dc=example,dc=com
  objectClass: organizationalUnit
  ou: users

  dn: cn=Jane,ou=users,dc=example,dc=com
  objectClass: person
  objectClass: organizationalPerson
  objectClass: inetOrgPerson
  cn: Jane
  sn: Smith
  displayName: Jane Smith
  mail: jane.smith@example.com

  dn: cn=Jim,ou=users,dc=example,dc=com
  objectClass: person
  objectClass: organizationalPerson
  objectClass: inetOrgPerson
  cn: Jim
  sn: Adams
  displayName: Jim Adams
  mail: jim.adams@example.com

  dn: ou=groups,dc=example,dc=com
  objectClass: organizationalUnit
  ou: groups

  dn: cn=admins,ou=groups,dc=example,dc=com
  objectClass: groupOfNames
  cn: admins
  owner: cn=admin,dc=example,dc=com
  description: System Administrators
  member: cn=Jane,ou=users,dc=example,dc=com
  member: cn=Jim,ou=users,dc=example,dc=com
  member: cn=INVALID,ou=users,dc=example,dc=com (1)
  member: cn=Jim,ou=OUTOFSCOPE,dc=example,dc=com (2)

1	A member that does not exist on the LDAP server.
2	A member that may exist, but is not under the `baseDN` in the user query for the sync job.

In order to tolerate the errors in the above example, the following additions to your sync configuration file must be made:

Example 10. LDAP Sync Configuration Using RFC 2307 Schema Tolerating Errors: rfc2307_config_tolerating.yaml

kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
rfc2307:
    groupsQuery:
        baseDN: "ou=groups,dc=example,dc=com"
        scope: sub
        derefAliases: never
    groupUIDAttribute: dn
    groupNameAttributes: [ cn ]
    groupMembershipAttributes: [ member ]
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
    userUIDAttribute: dn (3)
    userNameAttributes: [ uid ]
    tolerateMemberNotFoundErrors: true (1)
    tolerateMemberOutOfScopeErrors: true (2)

1	When `true`, the sync job tolerates groups for which some members were not found, and members whose LDAP entries are not found are ignored. The default behavior for the sync job is to fail if a member of a group is not found.
2	When `true`, the sync job tolerates groups for which some members are outside the user scope given in the `usersQuery` base DN, and members outside the member query scope are ignored. The default behavior for the sync job is to fail if a member of a group is out of scope.
3	The attribute that uniquely identifies a user on the LDAP server. You cannot specify `usersQuery` filters when using DN for userUIDAttribute. For fine-grained filtering, use the whitelist / blacklist method.

To run sync with the rfc2307_config_tolerating.yaml file:

$ oc adm groups sync --sync-config=rfc2307_config_tolerating.yaml --confirm

OKD creates the following group record as a result of the above sync operation:

Example 11. OKD Group Created Using rfc2307_config.yaml

apiVersion: v1
kind: Group
metadata:
  annotations:
    openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400
    openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com
    openshift.io/ldap.url: LDAP_SERVER_IP:389
  creationTimestamp:
  name: admins
users: (1)
- jane.smith@example.com
- jim.adams@example.com

1	The users that are members of the group, as specified by the sync file. Members for which lookup encountered tolerated errors are absent.

Active Directory

In the Active Directory schema, both users (Jane and Jim) exist in the LDAP server as first-class entries, and group membership is stored in attributes on the user. The following snippet of ldif defines the users and group for this schema:

Example 12. LDAP Entries Using Active Directory Schema: active_directory.ldif

dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users

dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: jane.smith@example.com
memberOf: admins (1)

dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jim
sn: Adams
displayName: Jim Adams
mail: jim.adams@example.com
memberOf: admins

1 The user’s group memberships are listed as attributes on the user, and the group does not exist as an entry on the server. The memberOf attribute does not have to be a literal attribute on the user; in some LDAP servers, it is created during search and returned to the client, but not committed to the database.

To sync this group, you must first create the configuration file. The Active Directory schema requires you to provide an LDAP query definition for user entries, as well as the attributes to represent them with in the internal OKD Group records.

For clarity, the Group you create in OKD should use attributes other than the distinguished name whenever possible for user- or administrator-facing fields. For example, identify the users of a Group by their e-mail, but define the name of the Group by the name of the group on the LDAP server. The following configuration file creates these relationships:

Example 13. LDAP Sync Configuration Using Active Directory Schema: active_directory_config.yaml

kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
activeDirectory:
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=inetOrgPerson)
        pageSize: 0
    userNameAttributes: [ uid ] (1)
    groupMembershipAttributes: [ memberOf ] (2)

1	The attribute to use as the name of the user in the OKD Group record.
2	The attribute on the user that stores the membership information.

To run sync with the active_directory_config.yaml file:

$ oc adm groups sync --sync-config=active_directory_config.yaml --confirm

OKD creates the following Group record as a result of the above sync operation:

Example 14. OKD Group Created Using active_directory_config.yaml

apiVersion: v1
kind: Group
metadata:
  annotations:
    openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 (1)
    openshift.io/ldap.uid: admins (2)
    openshift.io/ldap.url: LDAP_SERVER_IP:389 (3)
  creationTimestamp:
  name: admins (4)
users: (5)
- jane.smith@example.com
- jim.adams@example.com

1	The last time this Group was synchronized with the LDAP server, in ISO 6801 format.
2	The unique identifier for the group on the LDAP server.
3	The IP address and host of the LDAP server where this Group’s record is stored.
4	The name of the group as listed in the LDAP server.
5	The users that are members of the Group, named as specified by the sync file.

Augmented Active Directory

In the augmented Active Directory schema, both users (Jane and Jim) and groups exist in the LDAP server as first-class entries, and group membership is stored in attributes on the user. The following snippet of ldif defines the users and group for this schema:

Example 15. LDAP Entries Using Augmented Active Directory Schema: augmented_active_directory.ldif

dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users

dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: jane.smith@example.com
memberOf: cn=admins,ou=groups,dc=example,dc=com (1)

dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jim
sn: Adams
displayName: Jim Adams
mail: jim.adams@example.com
memberOf: cn=admins,ou=groups,dc=example,dc=com

dn: ou=groups,dc=example,dc=com
objectClass: organizationalUnit
ou: groups

dn: cn=admins,ou=groups,dc=example,dc=com (2)
objectClass: groupOfNames
cn: admins
owner: cn=admin,dc=example,dc=com
description: System Administrators
member: cn=Jane,ou=users,dc=example,dc=com
member: cn=Jim,ou=users,dc=example,dc=com

1	The user’s group memberships are listed as attributes on the user.
2	The group is a first-class entry on the LDAP server.

To sync this group, you must first create the configuration file. The augmented Active Directory schema requires you to provide an LDAP query definition for both user entries and group entries, as well as the attributes with which to represent them in the internal OKD Group records.

For clarity, the Group you create in OKD should use attributes other than the distinguished name whenever possible for user- or administrator-facing fields. For example, identify the users of a Group by their e-mail, and use the name of the Group as the common name. The following configuration file creates these relationships.

Example 16. LDAP Sync Configuration Using Augmented Active Directory Schema: augmented_active_directory_config.yaml

kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
augmentedActiveDirectory:
    groupsQuery:
        baseDN: "ou=groups,dc=example,dc=com"
        scope: sub
        derefAliases: never
        pageSize: 0
    groupUIDAttribute: dn (1)
    groupNameAttributes: [ cn ] (2)
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=inetOrgPerson)
        pageSize: 0
    userNameAttributes: [ uid ] (3)
    groupMembershipAttributes: [ memberOf ] (4)

1	The attribute that uniquely identifies a group on the LDAP server. You cannot specify `groupsQuery` filters when using DN for groupUIDAttribute. For fine-grained filtering, use the whitelist / blacklist method.
2	The attribute to use as the name of the Group.
3	The attribute to use as the name of the user in the OKD Group record.
4	The attribute on the user that stores the membership information.

To run sync with the augmented_active_directory_config.yaml file:

$ oc adm groups sync --sync-config=augmented_active_directory_config.yaml --confirm

OKD creates the following Group record as a result of the above sync operation:

Example 17. OpenShift Group Created Using augmented_active_directory_config.yaml

apiVersion: v1
kind: Group
metadata:
  annotations:
    openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 (1)
    openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com (2)
    openshift.io/ldap.url: LDAP_SERVER_IP:389 (3)
  creationTimestamp:
  name: admins (4)
users: (5)
- jane.smith@example.com
- jim.adams@example.com

1	The last time this Group was synchronized with the LDAP server, in ISO 6801 format.
2	The unique identifier for the group on the LDAP server.
3	The IP address and host of the LDAP server where this Group’s record is stored.
4	The name of the Group as specified by the sync file.
5	The users that are members of the Group, named as specified by the sync file.

Nested Membership Sync Example

Groups in OKD do not nest. The LDAP server must flatten group membership before the data can be consumed. Microsoft’s Active Directory Server supports this feature via the LDAP_MATCHING_RULE_IN_CHAIN rule, which has the OID 1.2.840.113556.1.4.1941. Furthermore, only explicitly whitelisted groups can be synced when using this matching rule.

This section has an example for the augmented Active Directory schema, which synchronizes a group named admins that has one user Jane and one group otheradmins as members. The otheradmins group has one user member: Jim. This example explains:

How the group and users are added to the LDAP server.
What the LDAP sync configuration file looks like.
What the resulting Group record in OKD will be after synchronization.

In the augmented Active Directory schema, both users (Jane and Jim) and groups exist in the LDAP server as first-class entries, and group membership is stored in attributes on the user or the group. The following snippet of ldif defines the users and groups for this schema:

LDAP Entries Using Augmented Active Directory Schema With Nested Members: augmented_active_directory_nested.ldif

dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users

dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: jane.smith@example.com
memberOf: cn=admins,ou=groups,dc=example,dc=com (1)

dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jim
sn: Adams
displayName: Jim Adams
mail: jim.adams@example.com
memberOf: cn=otheradmins,ou=groups,dc=example,dc=com (1)

dn: ou=groups,dc=example,dc=com
objectClass: organizationalUnit
ou: groups

dn: cn=admins,ou=groups,dc=example,dc=com (2)
objectClass: group
cn: admins
owner: cn=admin,dc=example,dc=com
description: System Administrators
member: cn=Jane,ou=users,dc=example,dc=com
member: cn=otheradmins,ou=groups,dc=example,dc=com

dn: cn=otheradmins,ou=groups,dc=example,dc=com (2)
objectClass: group
cn: otheradmins
owner: cn=admin,dc=example,dc=com
description: Other System Administrators
memberOf: cn=admins,ou=groups,dc=example,dc=com  (1) (3)
member: cn=Jim,ou=users,dc=example,dc=com

1	The user’s and group’s memberships are listed as attributes on the object.
2	The groups are first-class entries on the LDAP server.
3	The `otheradmins` group is a member of the `admins` group.

To sync nested groups with Active Directory, you must provide an LDAP query definition for both user entries and group entries, as well as the attributes with which to represent them in the internal OKD Group records. Furthermore, certain changes are required in this configuration:

The oc adm groups sync command must explicitly whitelist groups.
The user’s groupMembershipAttributes must include "memberOf:1.2.840.113556.1.4.1941:" to comply with the LDAP_MATCHING_RULE_IN_CHAIN rule.
The groupUIDAttribute must be set to dn.
The groupsQuery:
- Must not set filter.
- Must set a valid derefAliases.
- Should not set baseDN as that value is ignored.
- Should not set scope as that value is ignored.

For clarity, the Group you create in OKD should use attributes other than the distinguished name whenever possible for user- or administrator-facing fields. For example, identify the users of a Group by their e-mail, and use the name of the Group as the common name. The following configuration file creates these relationships:

LDAP Sync Configuration Using Augmented Active Directory Schema With Nested Members: augmented_active_directory_config_nested.yaml

kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
augmentedActiveDirectory:
    groupsQuery: (1)
        derefAliases: never
        pageSize: 0
    groupUIDAttribute: dn (2)
    groupNameAttributes: [ cn ] (3)
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=inetOrgPerson)
        pageSize: 0
    userNameAttributes: [ uid ] (4)
    groupMembershipAttributes: [ "memberOf:1.2.840.113556.1.4.1941:" ] (5)

1	`groupsQuery` filters cannot be specified. The `groupsQuery` base DN and scope values are ignored. `groupsQuery` must set a valid `derefAliases`.
2	The attribute that uniquely identifies a group on the LDAP server. It must be set to `dn`.
3	The attribute to use as the name of the Group.
4	The attribute to use as the name of the user in the OKD group record. `uid` or `sAMAccountName` are preferred choices in most installations.
5	The attribute on the user that stores the membership information. Note the use of `LDAP_MATCHING_RULE_IN_CHAIN`.

To run sync with the augmented_active_directory_config_nested.yaml file:

$ oc adm groups sync \
    'cn=admins,ou=groups,dc=example,dc=com' \
    --sync-config=augmented_active_directory_config_nested.yaml \
    --confirm

You must explicitly whitelist the cn=admins,ou=groups,dc=example,dc=com group.

OKD creates the following Group record as a result of the above sync operation:

OpenShift Group Created Using augmented_active_directory_config_nested.yaml

apiVersion: v1
kind: Group
metadata:
  annotations:
    openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 (1)
    openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com (2)
    openshift.io/ldap.url: LDAP_SERVER_IP:389 (3)
  creationTimestamp:
  name: admins (4)
users: (5)
- jane.smith@example.com
- jim.adams@example.com

1	The last time this Group was synchronized with the LDAP server, in ISO 6801 format.
2	The unique identifier for the group on the LDAP server.
3	The IP address and host of the LDAP server where this Group’s record is stored.
4	The name of the Group as specified by the sync file.
5	The users that are members of the Group, named as specified by the sync file. Note that members of nested groups are included since the group membership was flattened by the Microsoft Active Directory Server.

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.

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.

v1.LDAPSyncConfig

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

Name Description Schema

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: https://github.com/kubernetes/community/blob/master/contributors/devel/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: https://github.com/kubernetes/community/blob/master/contributors/devel/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. Cannot be set to true with a URL scheme of `ldaps://` If `false`, `ldaps://` URLs connect using TLS, and `ldap://` URLs are upgraded to a TLS connection using StartTLS as specified in https://tools.ietf.org/html/rfc2830.	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 OKD 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

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: https://github.com/kubernetes/community/blob/master/contributors/devel/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: https://github.com/kubernetes/community/blob/master/contributors/devel/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. Cannot be set to true with a URL scheme of ldaps:// If false, ldaps:// URLs connect using TLS, and ldap:// URLs are upgraded to a TLS connection using StartTLS as specified in https://tools.ietf.org/html/rfc2830.

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

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.

Name Description Schema

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

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

v1.LDAPQuery

LDAPQuery holds the options necessary to build an LDAP query.

Name Description Schema

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

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

v1.RFC2307Config

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

Name Description Schema

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 OKD 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 OKD 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 OKD 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 doesn’t 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

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 OKD 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 OKD 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 OKD 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 doesn’t 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

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.

Name Description Schema

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 OKD user name. The attribute to use as the name of the user in the OKD 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

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 OKD user name. The attribute to use as the name of the user in the OKD 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

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.

Name Description Schema

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 OKD user name. The attribute to use as the name of the user in the OKD 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 OKD group.	string array

usersQuery

Holds the template for an LDAP query that returns user entries.

v1.LDAPQuery

userNameAttributes

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 OKD group.

string array