Skip to content

[enterprise-4.22] OSDOCS-16959-ldap-identity-sync CQA #117892

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mburke5678 merged 1 commit into from
Aug 13, 2026
Merged

[enterprise-4.22] OSDOCS-16959-ldap-identity-sync CQA #117892

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 20 additions & 4 deletions authentication/ldap-syncing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ include::_attributes/common-attributes.adoc[]

toc::[]

[role="_abstract"]
Sync LDAP groups with {product-title} so you can manage user membership and permissions using groups stored in your LDAP directory.

ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
As an administrator,
endif::[]
Expand All @@ -21,13 +24,11 @@ LDAP servers using three common schemas for defining group membership: RFC 2307,
Active Directory, and augmented Active Directory.

ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
For more information on configuring LDAP, see
xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[Configuring an LDAP identity provider].
For more information on configuring LDAP, see "Configuring an LDAP identity provider".
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]

ifdef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
For more information on configuring LDAP, see
xref:../authentication/sd-configuring-identity-providers.adoc#config-ldap-idp_sd-configuring-identity-providers[Configuring an LDAP identity provider].
For more information on configuring LDAP, see "Configuring an LDAP identity provider".
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]

ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
Expand Down Expand Up @@ -85,6 +86,21 @@ include::modules/ldap-syncing-activedir.adoc[leveloffset=+2]

include::modules/ldap-syncing-augmented-activedir.adoc[leveloffset=+2]

include::modules/ldap-syncing-nesting-about.adoc[leveloffset=+2]

include::modules/ldap-syncing-nesting.adoc[leveloffset=+2]

include::modules/ldap-syncing-spec.adoc[leveloffset=+1]

[role="_additional-resources"]
.Additional resources

* xref:ldap-syncing-nesting-about_{context}[LDAP nested membership sync]

ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
* xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[Configuring an LDAP identity provider]
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]

ifdef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
* xref:../authentication/sd-configuring-identity-providers.adoc#config-ldap-idp_sd-configuring-identity-providers[Configuring an LDAP identity provider]
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
95 changes: 50 additions & 45 deletions modules/ldap-auto-syncing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,32 +6,32 @@
[id="ldap-auto-syncing_{context}"]
= Automatically syncing LDAP groups

You can automatically sync LDAP groups on a periodic basis by configuring a cron job.
[role="_abstract"]
Configure a cron job to automatically sync LDAP groups with {product-title} so you can keep group membership up to date without running manual sync commands.

.Prerequisites

* You have access to the cluster as a user with the `cluster-admin` role.
* You have configured an LDAP identity provider (IDP).
+
This procedure assumes that you created an LDAP secret named `ldap-secret` and a config map named `ca-config-map`.
* You configured an LDAP identity provider (IDP).
* You created an LDAP secret named `ldap-secret` and a config map named `ca-config-map`.

.Procedure

. Create a project where the cron job will run:
. Create a project where the cron job runs by running the following command:
+
[source,terminal]
----
$ oc new-project ldap-sync <1>
$ oc new-project ldap-sync
----
<1> This procedure uses a project called `ldap-sync`.
+
This procedure uses a project called `ldap-sync`.

. Locate the secret and config map that you created when configuring the LDAP identity provider and copy them to this new project.
+
The secret and config map exist in the `openshift-config` project and must be copied to the new `ldap-sync` project.

. Define a service account:
+
.Example `ldap-sync-service-account.yaml`
[source,yaml]
----
kind: ServiceAccount
Expand All @@ -41,7 +41,7 @@ metadata:
namespace: ldap-sync
----

. Create the service account:
. Create the service account by running the following command:
+
[source,terminal]
----
Expand All @@ -50,7 +50,6 @@ $ oc create -f ldap-sync-service-account.yaml

. Define a cluster role:
+
.Example `ldap-sync-cluster-role.yaml`
[source,yaml]
----
apiVersion: rbac.authorization.k8s.io/v1
Expand All @@ -69,7 +68,7 @@ rules:
- update
----

. Create the cluster role:
. Create the cluster role by running the following command:
+
[source,terminal]
----
Expand All @@ -78,7 +77,6 @@ $ oc create -f ldap-sync-cluster-role.yaml

. Define a cluster role binding to bind the cluster role to the service account:
+
.Example `ldap-sync-cluster-role-binding.yaml`
[source,yaml]
----
kind: ClusterRoleBinding
Expand All @@ -87,17 +85,20 @@ metadata:
name: ldap-group-syncer
subjects:
- kind: ServiceAccount
name: ldap-group-syncer <1>
name: ldap-group-syncer
namespace: ldap-sync
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: ldap-group-syncer <2>
name: ldap-group-syncer
----
<1> Reference to the service account created earlier in this procedure.
<2> Reference to the cluster role created earlier in this procedure.
+
where:

`subjects.name`:: Specifies the service account created earlier in this procedure.
`roleRef.name`:: Specifies the cluster role created earlier in this procedure.

. Create the cluster role binding:
. Create the cluster role binding by running the following command:
+
[source,terminal]
----
Expand All @@ -106,7 +107,6 @@ $ oc create -f ldap-sync-cluster-role-binding.yaml

. Define a config map that specifies the sync configuration file:
+
.Example `ldap-sync-config-map.yaml`
[source,yaml]
----
kind: ConfigMap
Expand All @@ -115,18 +115,18 @@ metadata:
name: ldap-group-syncer
namespace: ldap-sync
data:
sync.yaml: | <1>
sync.yaml:
kind: LDAPSyncConfig
apiVersion: v1
url: ldaps://10.0.0.0:636 <2>
url: ldaps://10.0.0.0:636
insecure: false
bindDN: cn=admin,dc=example,dc=com <3>
bindDN: cn=admin,dc=example,dc=com
bindPassword:
file: "/etc/secrets/bindPassword"
ca: /etc/ldap-ca/ca.crt
rfc2307: <4>
rfc2307:
groupsQuery:
baseDN: "ou=groups,dc=example,dc=com" <5>
baseDN: "ou=groups,dc=example,dc=com"
scope: sub
filter: "(objectClass=groupOfMembers)"
derefAliases: never
Expand All @@ -135,7 +135,7 @@ data:
groupNameAttributes: [ cn ]
groupMembershipAttributes: [ member ]
usersQuery:
baseDN: "ou=users,dc=example,dc=com" <6>
baseDN: "ou=users,dc=example,dc=com"
scope: sub
derefAliases: never
pageSize: 0
Expand All @@ -144,14 +144,17 @@ data:
tolerateMemberNotFoundErrors: false
tolerateMemberOutOfScopeErrors: false
----
<1> Define the sync configuration file.
<2> Specify the URL.
<3> Specify the `bindDN`.
<4> This example uses the RFC2307 schema; adjust values as necessary. You can also use a different schema.
<5> Specify the `baseDN` for `groupsQuery`.
<6> Specify the `baseDN` for `usersQuery`.
+
where:

`data.sync.yaml`:: Specifies the sync configuration file.
`data.sync.yaml.url`:: Specifies the URL.
`data.sync.yaml.bindDN`:: Specifies the `bindDN`.
`data.sync.yaml.rfc2307`:: Specifies the RFC 2307 schema. Adjust the values as necessary. You can also use a different schema.
`data.sync.yaml.rfc2307.groupsQuery.baseDN`:: Specifies the `baseDN` for `groupsQuery`.
`data.sync.yaml.rfc2307.usersQuery.baseDN`:: Specifies the `baseDN` for `usersQuery`.

. Create the config map:
. Create the config map by running the following command:
+
[source,terminal]
----
Expand All @@ -160,21 +163,20 @@ $ oc create -f ldap-sync-config-map.yaml

. Define a cron job:
+
.Example `ldap-sync-cron-job.yaml`
[source,yaml]
----
kind: CronJob
apiVersion: batch/v1
metadata:
name: ldap-group-syncer
namespace: ldap-sync
spec: <1>
schedule: "*/30 * * * *" <2>
spec:
schedule: "*/30 * * * *"
concurrencyPolicy: Forbid
jobTemplate:
spec:
backoffLimit: 0
ttlSecondsAfterFinished: 1800 <3>
ttlSecondsAfterFinished: 1800
template:
spec:
containers:
Expand All @@ -183,7 +185,7 @@ spec:
command:
- "/bin/bash"
- "-c"
- "oc adm groups sync --sync-config=/etc/config/sync.yaml --confirm" <4>
- "oc adm groups sync --sync-config=/etc/config/sync.yaml --confirm"
volumeMounts:
- mountPath: "/etc/config"
name: "ldap-sync-volume"
Expand All @@ -197,24 +199,27 @@ spec:
name: "ldap-group-syncer"
- name: "ldap-bind-password"
secret:
secretName: "ldap-secret" <5>
secretName: "ldap-secret"
- name: "ldap-ca"
configMap:
name: "ca-config-map" <6>
name: "ca-config-map"
restartPolicy: "Never"
terminationGracePeriodSeconds: 30
activeDeadlineSeconds: 500
dnsPolicy: "ClusterFirst"
serviceAccountName: "ldap-group-syncer"
----
<1> Configure the settings for the cron job. See "Creating cron jobs" for more information on cron job settings.
<2> The schedule for the job specified in link:https://en.wikipedia.org/wiki/Cron[cron format]. This example cron job runs every 30 minutes. Adjust the frequency as necessary, making sure to take into account how long the sync takes to run.
<3> How long, in seconds, to keep finished jobs. This should match the period of the job schedule in order to clean old failed jobs and prevent unnecessary alerts. For more information, see link:https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished[TTL-after-finished Controller] in the Kubernetes documentation.
<4> The LDAP sync command for the cron job to run. Passes in the sync configuration file that was defined in the config map.
<5> This secret was created when the LDAP IDP was configured.
<6> This config map was created when the LDAP IDP was configured.
+
where:

`spec`:: Specifies the configuration settings for the cron job. See "Creating cron jobs" for more information on cron job settings.
`spec.schedule`:: Specifies the schedule for the job specified in link:https://en.wikipedia.org/wiki/Cron[cron format]. This example cron job runs every 30 minutes. Adjust the frequency as necessary, making sure to take into account how long the sync takes to run.
`spec.jobTemplate.spec.ttlSecondsAfterFinished`:: Specifies how long, in seconds, to keep finished jobs. This should match the period of the job schedule in order to clean old failed jobs and prevent unnecessary alerts. For more information, see link:https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished[Automatic Cleanup for Finished Jobs (Kubernetes documentation)].
`spec.jobTemplate.spec.template.spec.containers.command`:: Specifies the LDAP sync command for the cron job to run. Passes in the sync configuration file that was defined in the config map.
`spec.jobTemplate.spec.template.spec.volumes.secret.secretName`:: Specifies the name of the secret that you created when the LDAP IDP was configured.
`spec.jobTemplate.spec.template.spec.volumes.configMap.name`:: Specifies the name of the config map that you created when the LDAP IDP was configured.

. Create the cron job:
. Create the cron job by running the following command:
+
[source,terminal]
----
Expand Down
Loading