OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Syncing Groups With LDAP

Overview

As an OpenShift 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. OpenShift can sync those LDAP records with internal OpenShift records, enabling you to manage your groups in one place. OpenShift 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 OpenShift 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: true (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. OpenShift uses this if elevated privilege is required to retrieve entries for the sync operation.
3 Optional password to use to bind. OpenShift uses this if elevated privilege is necessary to retrieve entries for the sync operation.
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, OpenShift 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)
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=*).
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 OpenShift 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. OpenShift 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 OpenShift Group records.

To sync all groups from the LDAP server with OpenShift:

$ oadm groups sync --sync-config=config.yaml --confirm

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

$ oadm groups sync --type=openshift --sync-config=config.yaml --confirm

To sync a subset of LDAP groups with OpenShift, 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 OpenShift. Your files must contain one unique group identifier per line.

 
$ oadm groups sync --whitelist=<whitelist_file> \
                   --sync-config=config.yaml    \
                   --confirm
$ oadm groups sync --blacklist=<blacklist_file> \
                   --sync-config=config.yaml    \
                   --confirm
$ oadm groups sync <group_unique_identifier>    \
                   --sync-config=config.yaml    \
                   --confirm
$ oadm groups sync <group_unique_identifier>    \
                   --whitelist=<whitelist_file> \
                   --blacklist=<blacklist_file> \
                   --sync-config=config.yaml    \
                   --confirm
$ oadm 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 OpenShift 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 OpenShift corresponded to the deleted groups in LDAP and then remove them from OpenShift:

$ oadm 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 OpenShift will be after synchronization.

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 OpenShift records.

For clarity, the Group you create in OpenShift 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: true (2)
rfc2307:
    groupsQuery:
        baseDN: "ou=groups,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=groupOfNames)
    groupUIDAttribute: dn (3)
    groupNameAttributes: [ cn ] (4)
    groupMembershipAttributes: [ member ] (5)
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=inetOrgPerson)
    userUIDAttribute: dn (6)
    userNameAttributes: [ mail ] (7)
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.
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.
7 The attribute to use as the name of the user in the OpenShift Group record.

To run sync with the rfc2307_config.yaml file:

$ oadm groups sync --sync-config=rfc2307_config.yaml --confirm

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

Example 6. OpenShift 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
        filter: (objectclass=groupOfNames)
    groupUIDAttribute: dn (2)
    groupNameAttributes: [ cn ] (3)
    groupMembershipAttributes: [ member ]
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=inetOrgPerson)
    userUIDAttribute: dn
    userNameAttributes: [ mail ]
1 The user-defined name mapping.
2 The unique identifier attribute that is used for the keys in the user-defined name mapping.
3 The attribute to name OpenShift Groups with if their unique identifier is not in the user-defined name mapping.

To run sync with the rfc2307_config_user_defined.yaml file:

$ oadm groups sync --sync-config=rfc2307_config_user_defined.yaml --confirm

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

Example 8. OpenShift 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.

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 9. 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
testMemberOf: 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
testMemberOf: 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 testMemberOf attribute cannot be a literal attribute on the user; it can be 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 OpenShift Group records.

For clarity, the Group you create in OpenShift 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 10. LDAP Sync Configuration Using Active Directory Schema: active_directory_config.yaml
kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
insecure: true
activeDirectory:
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=inetOrgPerson)
    userNameAttributes: [ mail ] (1)
    groupMembershipAttributes: [ testMemberOf ] (2)
1 The attribute to use as the name of the user in the OpenShift Group record.
2 The attribute on the user that stores the membership information.

To run sync with the active_directory_config.yaml file:

$ oadm groups sync --sync-config=active_directory_config.yaml --confirm

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

Example 11. OpenShift 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 12. 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
testMemberOf: 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
testMemberOf: 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 OpenShift Group records.

For clarity, the Group you create in OpenShift 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 13. LDAP Sync Configuration Using Augmented Active Directory Schema: augmented_active_directory_config.yaml
kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
insecure: true
augmentedActiveDirectory:
    groupsQuery:
        baseDN: "ou=groups,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=groupOfNames)
    groupUIDAttribute: dn (1)
    groupNameAttributes: [ cn ] (2)
    usersQuery:
        baseDN: "ou=users,dc=example,dc=com"
        scope: sub
        derefAliases: never
        filter: (objectclass=inetOrgPerson)
    userNameAttributes: [ mail ] (3)
    groupMembershipAttributes: [ testMemberOf ] (4)
1 The attribute that uniquely identifies a group on the LDAP server.
2 The attribute to use as the name of the Group.
3 The attribute to use as the name of the user in the OpenShift Group record.
4 The attribute on the user that stores the membership information.

To run sync with the augmented_active_directory_config.yaml file:

$ oadm groups sync --sync-config=augmented_active_directory_config.yaml --confirm

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

Example 14. 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.