diff --git a/authentication/ldap-syncing.adoc b/authentication/ldap-syncing.adoc index 8c30a2813f8..ce1ae49acc0 100644 --- a/authentication/ldap-syncing.adoc +++ b/authentication/ldap-syncing.adoc @@ -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::[] @@ -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[] @@ -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[] diff --git a/modules/ldap-auto-syncing.adoc b/modules/ldap-auto-syncing.adoc index 3f4f951f206..b717687e5db 100644 --- a/modules/ldap-auto-syncing.adoc +++ b/modules/ldap-auto-syncing.adoc @@ -6,24 +6,25 @@ [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. + @@ -31,7 +32,6 @@ The secret and config map exist in the `openshift-config` project and must be co . Define a service account: + -.Example `ldap-sync-service-account.yaml` [source,yaml] ---- kind: ServiceAccount @@ -41,7 +41,7 @@ metadata: namespace: ldap-sync ---- -. Create the service account: +. Create the service account by running the following command: + [source,terminal] ---- @@ -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 @@ -69,7 +68,7 @@ rules: - update ---- -. Create the cluster role: +. Create the cluster role by running the following command: + [source,terminal] ---- @@ -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 @@ -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] ---- @@ -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 @@ -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 @@ -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 @@ -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] ---- @@ -160,7 +163,6 @@ $ oc create -f ldap-sync-config-map.yaml . Define a cron job: + -.Example `ldap-sync-cron-job.yaml` [source,yaml] ---- kind: CronJob @@ -168,13 +170,13 @@ 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: @@ -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" @@ -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] ---- diff --git a/modules/ldap-syncing-about.adoc b/modules/ldap-syncing-about.adoc index 58432701c0d..26ce0f8b379 100644 --- a/modules/ldap-syncing-about.adoc +++ b/modules/ldap-syncing-about.adoc @@ -6,84 +6,65 @@ [id="ldap-syncing-about_{context}"] = About configuring LDAP sync -Before you can run LDAP sync, you need a sync -configuration file. This file contains the following LDAP client configuration details: +[role="_abstract"] +Review how LDAP group sync works and what the sync configuration file contains so you can configure group sync for your LDAP schema. + +Before you can run LDAP sync, you need a sync configuration file. This file contains the following 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. +* Sync configuration options that are dependent on the schema used in your LDAP server. * An administrator-defined list of name mappings that maps {product-title} group names to groups in your LDAP server. -The format of the configuration file depends upon the schema you are using: RFC 2307, Active Directory, or augmented Active Directory. +The format of the configuration file depends upon the schema you are using: -[[ldap-client-configuration]] -LDAP client configuration:: +* RFC 2307 +* Active Directory +* augmented Active Directory. -The LDAP client configuration section of the configuration defines the connections to your LDAP server. +[id="ldap-client-configuration_{context}"] +== LDAP client configuration -The LDAP client configuration section of the configuration defines the connections to your LDAP server. +The LDAP client configuration section of the configuration defines the connections to your LDAP server. The following example shows the LDAP client configuration fields: -.LDAP client configuration [source,yaml] ---- -url: ldap://10.0.0.0:389 <1> -bindDN: cn=admin,dc=example,dc=com <2> -bindPassword: <3> -insecure: false <4> -ca: my-ldap-ca-bundle.crt <5> +url: ldap://10.0.0.0:389 +bindDN: cn=admin,dc=example,dc=com +bindPassword: +insecure: false +ca: my-ldap-ca-bundle.crt ---- -<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. -{product-title} uses this if elevated privilege is required to retrieve entries for -the sync operation. -<3> Optional password to use to bind. {product-title} 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 `false`, secure -LDAP (`ldaps://`) URLs connect using TLS, and insecure LDAP (`ldap://`) URLs are -upgraded to TLS. When `true`, no TLS connection is made to the server and you cannot use `ldaps://` URL schemes. -<5> The certificate bundle to use for validating server certificates for the -configured URL. If empty, {product-title} uses system-trusted roots. This only applies -if `insecure` is set to `false`. - -[[ldap-query-definition]] -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. - -.LDAP query definition + +* The `url` field shows the connection protocol, IP address of the LDAP server hosting your database, and the port to connect to, formatted as `scheme://host:port`. +* The `bindDN` field shows an optional distinguished name (DN) to use as the Bind DN. {product-title} uses this if elevated privilege is required to retrieve entries for the sync operation. +* The `bindPassword` field shows an optional password to use to bind. {product-title} 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. +* The `insecure` field controls whether the LDAP connection uses TLS. When set to `false`, `ldaps://` URLs connect to the server using TLS, and `ldap://` URLs are upgraded to TLS. When set to `true`, no TLS connection is made to the server, and you cannot use `ldaps://` URL schemes. +* The `ca` field shows the certificate bundle to use for validating server certificates for the configured URL. If empty, {product-title} uses system-trusted roots. This only applies if `insecure` is set to `false`. + +[id="ldap-query-definition_{context}"] +== 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. The following example shows the LDAP query definition fields: + [source,yaml] ---- -baseDN: ou=users,dc=example,dc=com <1> -scope: sub <2> -derefAliases: never <3> -timeout: 0 <4> -filter: (objectClass=person) <5> -pageSize: 0 <6> +baseDN: ou=users,dc=example,dc=com +scope: sub +derefAliases: never +timeout: 0 +filter: (objectClass=person) +pageSize: 0 ---- -<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. - -[[ldap-search]] -.LDAP search scope options + +* The `baseDN` field contains the distinguished name (DN) of the branch of the directory where all searches start from. It is required that you specify the top of your directory tree, but you can also specify a subtree in the directory. +* The `scope` field shows the search scope. Valid values are `base`, `one`, and `sub`. If you omit this field, the default is `sub`. For descriptions of each value, see Table 1, _LDAP search scope options_. +* The `derefAliases` field shows 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 are in Table 2, _LDAP dereferencing behaviors_. +* The `timeout` field shows the time limit allowed for the search by the client, in seconds. A value of `0` imposes no client-side limit. +* The `filter` field contains a valid LDAP search filter. If this is left undefined, then the default is `(objectClass=*)`. +* The `pageSize` field shows the maximum number of LDAP entries the server returns per page. If set to `0`, no page size limit applies. Set this field when a query returns more entries than the client or server allow by default. + +[caption="Table 1. LDAP search scope options"] [cols="2a,8a",options="header"] |=== |LDAP search scope | Description @@ -93,8 +74,7 @@ the query. .^|`sub` | Consider the entire subtree rooted at the base DN given for the query. |=== -[[deref-aliases]] -.LDAP dereferencing behaviors +[caption="Table 2. LDAP dereferencing behaviors"] [cols="2a,8a",options="header"] |=== |Dereferencing behavior | Description @@ -104,16 +84,13 @@ the query. .^|`always` | Always dereference all aliases found in the LDAP tree. |=== -[[user-defined-name-mapping]] -User-defined name mapping:: -A user-defined name mapping explicitly maps the names of {product-title} 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 {product-title} group's name. +[id="user-defined-name-mapping_{context}"] +== User-defined name mapping + +A user-defined name mapping explicitly maps the names of {product-title} 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 name of the {product-title} group. + +The following example shows a user-defined name mapping: -.User-defined name mapping [source,yaml] ---- groupUIDNameMapping: diff --git a/modules/ldap-syncing-activedir.adoc b/modules/ldap-syncing-activedir.adoc index 1cd791cd7e1..539545ccabc 100644 --- a/modules/ldap-syncing-activedir.adoc +++ b/modules/ldap-syncing-activedir.adoc @@ -6,12 +6,12 @@ [id="ldap-syncing-activedir_{context}"] = Syncing groups using the Active Directory schema -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 +[role="_abstract"] +You can sync LDAP groups for your {product-title} cluster using the Active Directory schema by running `oc adm groups sync` with an LDAP sync configuration file. In this schema, group membership is stored in attributes on user entries, such as `memberOf`. + +In the Active Directory schema, users exist on 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: -.LDAP entries that use Active Directory schema: `active_directory.ldif` [source,ldif] ---- dn: ou=users,dc=example,dc=com @@ -40,14 +40,14 @@ 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. + +where: + +`memberOf`:: Specifies that the group memberships of the user 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, the attribute is created during search and returned to the client, but not committed to the database. .Prerequisites -* Create the configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `active_directory_config.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -57,37 +57,35 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* Run the sync with the `active_directory_config.yaml` file: +* Sync with the `active_directory_config.yaml` file by running the following command: + [source,terminal] ---- $ oc adm groups sync --sync-config=active_directory_config.yaml --confirm ---- + -{product-title} creates the following group record as a result of the above sync -operation: +{product-title} creates the following group record as a result of the previous sync operation: + -.{product-title} group created by using the `active_directory_config.yaml` file [source,yaml] ---- apiVersion: user.openshift.io/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> + openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 + openshift.io/ldap.uid: admins + openshift.io/ldap.url: LDAP_SERVER_IP:389 creationTimestamp: - name: admins <4> -users: <5> + name: admins +users: - jane.smith@example.com - jim.adams@example.com ---- -<1> The last time this {product-title} 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. ++ +where: + +`metadata.annotations.openshift.io/ldap.sync-time`:: Specifies the last time this {product-title} group was synchronized with the LDAP server, in ISO 8601 format. +`metadata.annotations.openshift.io/ldap.uid`:: Specifies the unique identifier for the group on the LDAP server. +`metadata.annotations.openshift.io/ldap.url`:: Specifies the IP address and host of the LDAP server where the record of the group is stored. +`metadata.name`:: Specifies the name of the group as listed in the LDAP server. +`users`:: Specifies the users that are members of the group, named as specified by the sync file. diff --git a/modules/ldap-syncing-augmented-activedir.adoc b/modules/ldap-syncing-augmented-activedir.adoc index 0aeea936154..3840507fd7b 100644 --- a/modules/ldap-syncing-augmented-activedir.adoc +++ b/modules/ldap-syncing-augmented-activedir.adoc @@ -6,12 +6,14 @@ [id="ldap-syncing-augmented-activedir_{context}"] = Syncing groups using the augmented Active Directory schema -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 +[role="_abstract"] +You can sync LDAP groups for your {product-title} cluster using the augmented Active Directory schema by running `oc adm groups sync` with an LDAP sync configuration file. + +In this schema, users and groups are first-class LDAP entries, and group membership is stored in attributes on user entries, such as `memberOf`. + +In the augmented Active Directory schema, both users 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: -.LDAP entries that use augmented Active Directory schema: `augmented_active_directory.ldif` [source,ldif] ---- dn: ou=users,dc=example,dc=com @@ -27,7 +29,7 @@ cn: Jane sn: Smith displayName: Jane Smith mail: jane.smith@example.com -memberOf: cn=admins,ou=groups,dc=example,dc=com <1> +memberOf: cn=admins,ou=groups,dc=example,dc=com dn: cn=Jim,ou=users,dc=example,dc=com objectClass: person @@ -44,7 +46,7 @@ dn: ou=groups,dc=example,dc=com objectClass: organizationalUnit ou: groups -dn: cn=admins,ou=groups,dc=example,dc=com <2> +dn: cn=admins,ou=groups,dc=example,dc=com objectClass: groupOfNames cn: admins owner: cn=admin,dc=example,dc=com @@ -52,12 +54,15 @@ 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. + +where: + +`memberOf`:: Specifies that the group memberships of the user are listed as attributes on the user. +`dn: cn=admins,ou=groups,dc=example,dc=com`:: Specifies that the group is a first-class entry on the LDAP server. .Prerequisites -* Create the configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `augmented_active_directory_config.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -67,35 +72,35 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* Run the sync with the `augmented_active_directory_config.yaml` file: +* Sync with the `augmented_active_directory_config.yaml` file by running the following command: + [source,terminal] ---- $ oc adm groups sync --sync-config=augmented_active_directory_config.yaml --confirm ---- + -{product-title} creates the following group record as a result of the above sync -operation: +{product-title} creates the following group record as a result of the previous sync operation: + -.{product-title} group created by using the `augmented_active_directory_config.yaml` file - [source,yaml] ---- apiVersion: user.openshift.io/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> + 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 <4> -users: <5> + name: admins +users: - jane.smith@example.com - jim.adams@example.com ---- -<1> The last time this {product-title} 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. ++ +where: + +`metadata.annotations.openshift.io/ldap.sync-time`:: Specifies the last time this {product-title} group was synchronized with the LDAP server, in ISO 8601 format. +`metadata.annotations.openshift.io/ldap.uid`:: Specifies the unique identifier for the group on the LDAP server. +`metadata.annotations.openshift.io/ldap.url`:: Specifies the IP address and host of the LDAP server where the record of the group is stored. +`metadata.name`:: Specifies the name of the group as specified by the sync file. +`users`:: Specifies the users that are members of the group, named as specified by the sync file. diff --git a/modules/ldap-syncing-config-activedir.adoc b/modules/ldap-syncing-config-activedir.adoc index 3290c64f896..5c08ff0bed9 100644 --- a/modules/ldap-syncing-config-activedir.adoc +++ b/modules/ldap-syncing-config-activedir.adoc @@ -6,17 +6,13 @@ [id="ldap-syncing-config-activedir_{context}"] = About the Active Directory 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 -{product-title} group records. +[role="_abstract"] +Review the Active Directory LDAP sync configuration file so you can define user queries and the attributes used in {product-title} group records. -For clarity, the group you create in {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} 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: +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 {product-title} group records. + +For clarity, the group you create in {product-title} should use attributes other than the distinguished name whenever possible for user-facing or administrator-facing fields. For example, identify the users of an {product-title} 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: -.LDAP sync configuration that uses Active Directory schema: `active_directory_config.yaml` [source,yaml] ---- kind: LDAPSyncConfig @@ -29,8 +25,11 @@ activeDirectory: derefAliases: never filter: (objectclass=person) pageSize: 0 - userNameAttributes: [ mail ] <1> - groupMembershipAttributes: [ memberOf ] <2> + userNameAttributes: [ mail ] + groupMembershipAttributes: [ memberOf ] ---- -<1> The attribute to use as the name of the user in the {product-title} group record. -<2> The attribute on the user that stores the membership information. + +where: + +`activeDirectory.userNameAttributes`:: Specifies the attribute to use as the name of the user in the {product-title} group record. +`activeDirectory.groupMembershiptAttributes`:: Specifies the attribute on the user that stores the membership information. diff --git a/modules/ldap-syncing-config-augmented-activedir.adoc b/modules/ldap-syncing-config-augmented-activedir.adoc index b497d649145..f897cbe95dd 100644 --- a/modules/ldap-syncing-config-augmented-activedir.adoc +++ b/modules/ldap-syncing-config-augmented-activedir.adoc @@ -4,19 +4,15 @@ :_mod-docs-content-type: CONCEPT [id="ldap-syncing-config-augmented-activedir_{context}"] -= About the augmented Active Directory configuration file += About the augmented Active Directory 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 {product-title} group records. +[role="_abstract"] +Review the augmented Active Directory LDAP sync configuration file so you can define user and group queries and the attributes used in {product-title} group records. -For clarity, the group you create in {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} group by their e-mail, -and use the name of the group as the common name. The following configuration -file creates these relationships. +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 {product-title} group records. + +For clarity, the group you create in {product-title} should use attributes other than the distinguished name whenever possible for user-facing or administrator-facing fields. For example, identify the users of an {product-title} 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 that uses augmented Active Directory schema: `augmented_active_directory_config.yaml` [source,yaml] ---- kind: LDAPSyncConfig @@ -28,20 +24,21 @@ augmentedActiveDirectory: scope: sub derefAliases: never pageSize: 0 - groupUIDAttribute: dn <1> - groupNameAttributes: [ cn ] <2> + groupUIDAttribute: dn + groupNameAttributes: [ cn ] usersQuery: baseDN: "ou=users,dc=example,dc=com" scope: sub derefAliases: never filter: (objectclass=person) pageSize: 0 - userNameAttributes: [ mail ] <3> - groupMembershipAttributes: [ memberOf ] <4> + userNameAttributes: [ mail ] + groupMembershipAttributes: [ memberOf ] ---- -<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 {product-title} group record. -<4> The attribute on the user that stores the membership information. + +where: + +`augmentedActiveDirectory.groupUIDAttribute`:: Specifies 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 an allowlist file, a denylist file, or both. +`augmentedActiveDirectory.groupNameAttributes`:: Specifies the attribute to use as the name of the group. +`augmentedActiveDirectory.userNameAttributes`:: Specifies the attribute to use as the name of the user in the {product-title} group record. +`augmentedActiveDirectory.groupMembershipAttributes`:: Specifies the attribute on the user that stores the membership information. diff --git a/modules/ldap-syncing-config-rfc2307.adoc b/modules/ldap-syncing-config-rfc2307.adoc index 93110c3c715..5a65c777e98 100644 --- a/modules/ldap-syncing-config-rfc2307.adoc +++ b/modules/ldap-syncing-config-rfc2307.adoc @@ -6,28 +6,24 @@ [id="ldap-syncing-config-rfc2307_{context}"] = About the RFC 2307 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 {product-title} records. +[role="_abstract"] +Review the RFC 2307 LDAP sync configuration file so you can define user and group queries and the attributes used in {product-title} group records. -For clarity, the group you create in {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} group by their e-mail, and use the -name of the group as the common name. The following configuration file creates -these relationships: +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 {product-title} records. + +For clarity, the group you create in {product-title} should use attributes other than the distinguished name whenever possible for user-facing or administrator-facing fields. For example, identify the users of an {product-title} group by their e-mail, and use the name of the group as the common name. The following configuration file creates these relationships: [NOTE] ==== -If using user-defined name mappings, your configuration file will differ. +If using user-defined name mappings, your configuration file differs. ==== -.LDAP sync configuration that uses RFC 2307 schema: `rfc2307_config.yaml` [source,yaml] ---- kind: LDAPSyncConfig apiVersion: v1 -url: ldap://LDAP_SERVICE_IP:389 <1> -insecure: false <2> +url: ldap://LDAP_SERVICE_IP:389 +insecure: false bindDN: cn=admin,dc=example,dc=com bindPassword: file: "/etc/secrets/bindPassword" @@ -37,30 +33,27 @@ rfc2307: scope: sub derefAliases: never pageSize: 0 - groupUIDAttribute: dn <3> - groupNameAttributes: [ cn ] <4> - groupMembershipAttributes: [ member ] <5> + groupUIDAttribute: dn + groupNameAttributes: [ cn ] + groupMembershipAttributes: [ member ] usersQuery: baseDN: "ou=users,dc=example,dc=com" scope: sub derefAliases: never pageSize: 0 - userUIDAttribute: dn <6> - userNameAttributes: [ mail ] <7> + userUIDAttribute: dn + userNameAttributes: [ mail ] tolerateMemberNotFoundErrors: false tolerateMemberOutOfScopeErrors: false ---- -<1> The IP address and host of the LDAP server where this group's record is -stored. -<2> When `false`, secure -LDAP (`ldaps://`) URLs connect using TLS, and insecure LDAP (`ldap://`) URLs are -upgraded to TLS. When `true`, no TLS connection is made to the server and you cannot use `ldaps://` URL schemes. -<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 {product-title} group record. + +where: + +`url`:: Specifies the IP address and host of the LDAP server where the record of the group is stored. +`insecure`:: Specifies whether the LDAP connection uses TLS. When set to `false`, `ldaps://` URLs connect to the server using TLS, and `ldap://` URLs are upgraded to TLS. When set to `true`, no TLS connection is made to the server, and you cannot use `ldaps://` URL schemes. +`rfc2307.groupUIDAttribute`:: Specifies 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 an allowlist file, a denylist file, or both. +`rfc2307.groupNameAttributes`:: Specifies the attribute to use as the name of the group. +`rfc2307.groupMembershipAttributes`:: Specifies the attribute on the group that stores the membership information. +`rfc2307.userUIDAttribute`:: Specifies 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 an allowlist file, a denylist file, or both. +`rfc2307.userNameAttributes`:: Specifies the attribute to use as the name of the user in the {product-title} group record. diff --git a/modules/ldap-syncing-examples.adoc b/modules/ldap-syncing-examples.adoc index 62b85702480..d8e780aff2b 100644 --- a/modules/ldap-syncing-examples.adoc +++ b/modules/ldap-syncing-examples.adoc @@ -6,10 +6,11 @@ [id="ldap-syncing-examples_{context}"] = LDAP group sync examples -This section contains examples for the RFC 2307, Active Directory, and augmented Active Directory schemas. +[role="_abstract"] +Review LDAP group sync examples so you can configure synchronization for RFC 2307, Active Directory, or augmented Active Directory schemas. [NOTE] ==== -These examples assume that all users are direct members of their respective groups. Specifically, no groups have other groups as members. See the Nested Membership Sync Example for information on how to sync nested groups. +These examples cover only direct group membership. Each user is a direct member of a group, and groups do not contain other groups as members. For information, see "LDAP nested membership sync". ==== diff --git a/modules/ldap-syncing-nesting-about.adoc b/modules/ldap-syncing-nesting-about.adoc new file mode 100644 index 00000000000..81d2047f330 --- /dev/null +++ b/modules/ldap-syncing-nesting-about.adoc @@ -0,0 +1,136 @@ +// Module included in the following assemblies: +// +// * authentication/ldap-syncing.adoc + +:_mod-docs-content-type: CONCEPT +[id="ldap-syncing-nesting-about_{context}"] += LDAP nested membership sync + +[role="_abstract"] +Understand how nested LDAP group membership is flattened during sync so you can configure allowlisted sync jobs that include members of nested Active Directory groups. + +Groups in {product-title} do not nest. The LDAP server must flatten group membership before the data can be consumed. The Microsoft 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 allowlisted groups can be synced when using this matching rule. + +The following example synchronizes a group named `admins` that has one user member, `Jane`, and one nested group member, `otheradmins`, which contains `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 {product-title} is after synchronization. + +[id="example-ldap-entries_{context}"] +== Example LDAP entries + +In the augmented Active Directory schema, both users 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 `ldif` snippet defines the users and groups for this schema: + +[source,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 + +dn: ou=groups,dc=example,dc=com +objectClass: organizationalUnit +ou: groups + +dn: cn=admins,ou=groups,dc=example,dc=com +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 +objectClass: group +cn: otheradmins +owner: cn=admin,dc=example,dc=com +description: Other System Administrators +memberOf: cn=admins,ou=groups,dc=example,dc=com +member: cn=Jim,ou=users,dc=example,dc=com +---- + +where: + +`memberOf`:: Specifies that the memberships of the user and group are listed as attributes on the object. +`dn: cn=admins,ou=groups,dc=example,dc=com`:: Specifies that groups are first-class entries on the LDAP server. +`member: cn=otheradmins,ou=groups,dc=example,dc=com`:: Specifies that the `otheradmins` group is a member of the `admins` group. + +[id="configuration-requirements_{context}"] +== Configuration requirements + +When syncing 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 {product-title} group records. +Furthermore, certain changes are required in this configuration: + +* The `oc adm groups sync` command requires you to explicitly allowlist groups. +* The `groupMembershipAttributes` field 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 {product-title} should use attributes other than the distinguished name whenever possible for user-facing or administrator-facing fields. For example, identify the users of an {product-title} group by their e-mail, and use the name of the group as the common name. + +[id="example-sync-configuration_{context}"] +== Example sync configuration + +The following configuration file creates these relationships. Save it as `augmented_active_directory_config_nested.yaml`: + +[source,yaml] +---- +kind: LDAPSyncConfig +apiVersion: v1 +url: ldap://LDAP_SERVICE_IP:389 +augmentedActiveDirectory: + groupsQuery: + derefAliases: never + pageSize: 0 + groupUIDAttribute: dn + groupNameAttributes: [ cn ] + usersQuery: + baseDN: "ou=users,dc=example,dc=com" + scope: sub + derefAliases: never + filter: (objectclass=person) + pageSize: 0 + userNameAttributes: [ mail ] + groupMembershipAttributes: [ "memberOf:1.2.840.113556.1.4.1941:" ] +---- + +where: + +`augmentedActiveDirectory.groupsQuery`:: Specifies that the `groupsQuery` filters cannot be specified. The `groupsQuery` base DN and scope values are ignored. `groupsQuery` must set a valid `derefAliases`. +`augmentedActiveDirectory.groupUIDAttribute`:: Specifies the attribute that uniquely identifies a group on the LDAP server. It must be set to `dn`. +`augmentedActiveDirectory.groupNameAttributes`:: Specifies the attribute to use as the name of the group. +`augmentedActiveDirectory.userNameAttributes`:: Specifies the attribute to use as the username of the user in the {product-title} group record. +`augmentedActiveDirectory.groupMembershipAttributes`:: Specifies the attribute on the user that stores the membership information. Note the use of `LDAP_MATCHING_RULE_IN_CHAIN`. ++ +[NOTE] +==== +`mail` or `sAMAccountName` are preferred choices in most installations. +==== diff --git a/modules/ldap-syncing-nesting.adoc b/modules/ldap-syncing-nesting.adoc index 6795ebdb517..e174c241193 100644 --- a/modules/ldap-syncing-nesting.adoc +++ b/modules/ldap-syncing-nesting.adoc @@ -4,136 +4,14 @@ :_mod-docs-content-type: PROCEDURE [id="ldap-syncing-nesting_{context}"] -== LDAP nested membership sync example += LDAP nested membership sync example -Groups in {product-title} 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 {product-title} 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 that use augmented Active Directory schema with nested members: `augmented_active_directory_nested.ldif` -[source,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. - -When syncing 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 {product-title} 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 {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} 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 that uses augmented Active Directory schema with nested members: `augmented_active_directory_config_nested.yaml` -[source,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=person) - pageSize: 0 - userNameAttributes: [ mail ] <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 {product-title} group -record. -+ -[NOTE] -==== -`mail` 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`. +[role="_abstract"] +Run the nested group LDAP sync example with an allowlisted group so you can verify that members of nested Active Directory groups appear in the resulting {product-title} group. .Prerequisites -* Create the configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `augmented_active_directory_config_nested.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -143,7 +21,7 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* Run the sync with the `augmented_active_directory_config_nested.yaml` file: +* Sync with the `augmented_active_directory_config_nested.yaml` file by running the following command: + [source,terminal] ---- @@ -155,32 +33,36 @@ $ oc adm groups sync \ + [NOTE] ==== -You must explicitly whitelist the `cn=admins,ou=groups,dc=example,dc=com` group. +You must explicitly allowlist the `cn=admins,ou=groups,dc=example,dc=com` group. ==== + -{product-title} creates the following group record as a result of the above sync -operation: +{product-title} creates the following group record as a result of the previous sync operation: + -.{product-title} group created by using the `augmented_active_directory_config_nested.yaml` file [source,yaml] ---- apiVersion: user.openshift.io/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> + 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 <4> -users: <5> + name: admins +users: - jane.smith@example.com - jim.adams@example.com ---- -<1> The last time this {product-title} 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. ++ +where: + +`metadata.annotations.openshift.io/ldap.sync-time`:: Specifies the last time this {product-title} group was synchronized with the LDAP server, in ISO 8601 format. +`metadata.annotations.openshift.io/ldap.uid`:: Specifies the unique identifier for the group on the LDAP server. +`metadata.annotations.openshift.io/ldap.url`:: Specifies the IP address and host of the LDAP server where the record of the group is stored. +`metadata.name`:: Specifies the name of the group as specified by the sync file. +`users`:: Specifies the users that are members of the group, named as specified by the sync file. ++ +[NOTE] +==== +Members of nested groups are included because the group membership is flattened by the Microsoft Active Directory Server. +==== diff --git a/modules/ldap-syncing-pruning.adoc b/modules/ldap-syncing-pruning.adoc index e3937b805ef..4d97309242b 100644 --- a/modules/ldap-syncing-pruning.adoc +++ b/modules/ldap-syncing-pruning.adoc @@ -2,24 +2,31 @@ // // * authentication/ldap-syncing.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: PROCEDURE [id="ldap-syncing-pruning_{context}"] = Running a group pruning job -An administrator can also choose to remove groups from {product-title} 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 whitelists or blacklists as used for the sync job. +[role="_abstract"] +Run a group pruning job to remove LDAP-synced groups from {product-title} when they no longer exist on your LDAP server so you can keep cluster group records aligned with your directory. -For example: +.Procedure +* Prune groups using a sync configuration file by running the following command: ++ [source,terminal] ---- $ oc adm prune groups --sync-config=/path/to/ldap-sync-config.yaml --confirm ---- +* Prune groups using an allowlist file by running the following command: ++ [source,terminal] ---- $ oc adm prune groups --whitelist=/path/to/whitelist.txt --sync-config=/path/to/ldap-sync-config.yaml --confirm ---- +* Prune groups using a denylist file by running the following command: ++ [source,terminal] ---- $ oc adm prune groups --blacklist=/path/to/blacklist.txt --sync-config=/path/to/ldap-sync-config.yaml --confirm diff --git a/modules/ldap-syncing-rfc2307-user-defined-error.adoc b/modules/ldap-syncing-rfc2307-user-defined-error.adoc index 40b2f920766..ec5fbe1f267 100644 --- a/modules/ldap-syncing-rfc2307-user-defined-error.adoc +++ b/modules/ldap-syncing-rfc2307-user-defined-error.adoc @@ -4,41 +4,36 @@ :_mod-docs-content-type: PROCEDURE [id="ldap-syncing-rfc2307-user-defined-error_{context}"] -= Syncing groups using RFC 2307 with user-defined error tolerances += Syncing groups by using 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: +[role="_abstract"] +Sync LDAP groups using the RFC 2307 schema with error tolerances so you can complete group synchronization when some members are missing or out of scope. + +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 "": membership lookup for user "" in group "" failed because of "search for entry with dn="" would search outside of the base dn specified (dn="")". ---- -This often indicates a misconfigured `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. +This often indicates a misconfigured `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 are ignored. -Similarly, when the group sync process fails to locate a member for a group, it -fails outright with errors: +Similarly, when the group sync process fails to locate a member for a group, it fails with errors: ---- Error determining LDAP group membership for "": membership lookup for user "" in group "" failed because of "search for entry with base dn="" refers to a non-existent entry". Error determining LDAP group membership for "": membership lookup for user "" in group "" failed because of "search for entry with base dn="" and filter "" did not return any results". ---- -This often indicates a misconfigured `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. +This often indicates a misconfigured `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. Missing members are ignored. [WARNING] ==== -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 {product-title} groups missing members. +Enabling error tolerances for the LDAP group sync causes the sync process to ignore member entries that cause errors. If the LDAP group sync is not configured correctly, this could result in synced {product-title} groups missing members. ==== -.LDAP entries that use RFC 2307 schema with problematic group membership: `rfc2307_problematic_users.ldif` +The following example shows LDAP entries that use RFC 2307 schema with invalid group membership: `rfc2307_problematic_users.ldif` + [source,ldif] ---- dn: ou=users,dc=example,dc=com @@ -70,17 +65,17 @@ correctly, this could result in synced {product-title} groups missing members. 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> + member: cn=INVALID,ou=users,dc=example,dc=com + member: cn=Jim,ou=OUTOFSCOPE,dc=example,dc=com ---- -<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. -To tolerate the errors in the above example, the following additions to -your sync configuration file must be made: +where: + +`member: cn=INVALID,ou=users,dc=example,dc=com`:: Specifies a member that does not exist on the LDAP server. +`member: cn=Jim,ou=OUTOFSCOPE,dc=example,dc=com`:: Specifies a member that may exist, but is not under the `baseDN` in the user query for the sync job. + +To tolerate the errors in the above example, the following additions to your sync configuration file must be made: -.LDAP sync configuration that uses RFC 2307 schema tolerating errors: `rfc2307_config_tolerating.yaml` [source,yaml] ---- kind: LDAPSyncConfig @@ -98,26 +93,21 @@ rfc2307: baseDN: "ou=users,dc=example,dc=com" scope: sub derefAliases: never - userUIDAttribute: dn <1> + userUIDAttribute: dn userNameAttributes: [ mail ] - tolerateMemberNotFoundErrors: true <2> - tolerateMemberOutOfScopeErrors: true <3> + tolerateMemberNotFoundErrors: true + tolerateMemberOutOfScopeErrors: true ---- -<1> 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. -<2> 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. -<3> 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. + +where: + +`rfc2307.userUIDAttribute`:: Specifies 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 an allowlist file, a denylist file, or both. +`rfc2307.tolerateMemberNotFoundErrors`:: Specifies whether the sync job tolerates groups for which some members were not found. When set to `true`, 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. +`rfc2307.tolerateMemberOutOfScopeErrors`:: Specifies whether the sync job tolerates groups for which some members are outside the user scope given in the `usersQuery` `baseDN`. When set to `true`, 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. .Prerequisites -* Create the configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `rfc2307_config_tolerating.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -127,17 +117,15 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* Run the sync with the `rfc2307_config_tolerating.yaml` file: +* Sync with the `rfc2307_config_tolerating.yaml` file by running the following command: + [source,terminal] ---- $ oc adm groups sync --sync-config=rfc2307_config_tolerating.yaml --confirm ---- + -{product-title} creates the following group record as a result of the above sync -operation: +{product-title} creates the following group record as a result of the previous sync operation: + -.{product-title} group created by using the `rfc2307_config.yaml` file [source,yaml] ---- apiVersion: user.openshift.io/v1 @@ -149,9 +137,11 @@ metadata: openshift.io/ldap.url: LDAP_SERVER_IP:389 creationTimestamp: name: admins -users: <1> +users: - 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. ++ +where: + +`users`:: Specifies the users that are members of the group, as specified by the sync file. Members for which lookup encountered tolerated errors are absent. diff --git a/modules/ldap-syncing-rfc2307-user-defined.adoc b/modules/ldap-syncing-rfc2307-user-defined.adoc index c9fbfc878d2..790c691148e 100644 --- a/modules/ldap-syncing-rfc2307-user-defined.adoc +++ b/modules/ldap-syncing-rfc2307-user-defined.adoc @@ -4,50 +4,50 @@ :_mod-docs-content-type: PROCEDURE [id="ldap-syncing-rfc2307-user-defined_{context}"] -= Syncing groups using the RFC2307 schema with user-defined name mappings += Syncing groups by using the RFC 2307 schema with user-defined name mappings -When syncing groups with user-defined name mappings, the configuration file -changes to contain these mappings as shown below. +[role="_abstract"] +Sync LDAP groups using the RFC 2307 schema with user-defined name mappings so you can map LDAP group identifiers to {product-title} group names. + +When you sync groups with user-defined name mappings, include the mappings in the configuration file, as shown in the following `rfc2307_config_user_defined.yaml` example: -.LDAP sync configuration that uses RFC 2307 schema with user-defined name mappings: `rfc2307_config_user_defined.yaml` [source,yaml] ---- kind: LDAPSyncConfig apiVersion: v1 groupUIDNameMapping: - "cn=admins,ou=groups,dc=example,dc=com": Administrators <1> + "cn=admins,ou=groups,dc=example,dc=com": Administrators rfc2307: groupsQuery: baseDN: "ou=groups,dc=example,dc=com" scope: sub derefAliases: never pageSize: 0 - groupUIDAttribute: dn <2> - groupNameAttributes: [ cn ] <3> + groupUIDAttribute: dn + groupNameAttributes: [ cn ] groupMembershipAttributes: [ member ] usersQuery: baseDN: "ou=users,dc=example,dc=com" scope: sub derefAliases: never pageSize: 0 - userUIDAttribute: dn <4> + userUIDAttribute: dn userNameAttributes: [ mail ] 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 {product-title} groups with if their unique identifier is + +where: + +`groupUIDNameMapping`:: Specifies the user-defined name mapping. +`rfc2307.groupUIDAttribute`:: Specifies 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 an allowlist file, a denylist file, or both. +`rfc2307.groupNameAttributes`:: Specifies the attribute to name {product-title} 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. +`rfc2307.userUIDAttribute`:: Specifies the attribute that uniquely identifies a user on the LDAP server. You cannot specify `usersQuery` filters when using DN for the `userUIDAttribute` parameter. For fine-grained filtering, use an allowlist file, a denylist file, or both. .Prerequisites -* Create the configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `rfc2307_config_user_defined.yaml`. ifndef::openshift-dedicated,openshift-rosa[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa[] @@ -57,17 +57,15 @@ endif::openshift-dedicated,openshift-rosa[] .Procedure -* Run the sync with the `rfc2307_config_user_defined.yaml` file: +* Sync groups using the `rfc2307_config_user_defined.yaml` file by running the following command: + [source,terminal] ---- $ oc adm groups sync --sync-config=rfc2307_config_user_defined.yaml --confirm ---- + -{product-title} creates the following group record as a result of the above sync -operation: +After you run the sync command, the following group record is created in {product-title}: + -.{product-title} group created by using the `rfc2307_config_user_defined.yaml` file [source,yaml] ---- apiVersion: user.openshift.io/v1 @@ -78,9 +76,12 @@ metadata: openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com openshift.io/ldap.url: LDAP_SERVER_IP:389 creationTimestamp: - name: Administrators <1> + name: Administrators users: - jane.smith@example.com - jim.adams@example.com ---- -<1> The name of the group as specified by the user-defined name mapping. ++ +where: + +`metadata.name`:: Specifies the name of the group as specified by the user-defined name mapping. diff --git a/modules/ldap-syncing-rfc2307.adoc b/modules/ldap-syncing-rfc2307.adoc index 9154e526e69..d2ea78929c8 100644 --- a/modules/ldap-syncing-rfc2307.adoc +++ b/modules/ldap-syncing-rfc2307.adoc @@ -6,26 +6,22 @@ [id="ldap-syncing-rfc2307_{context}"] = Syncing groups using the RFC 2307 schema -For the RFC 2307 schema, the following examples synchronize a group named `admins` that has two -members: `Jane` and `Jim`. The examples explain: +[role="_abstract"] +Sync LDAP groups by using the RFC 2307 schema so you can mirror direct group membership from your LDAP server in {product-title}. + +For the RFC 2307 schema, the following examples synchronize a group named `admins` that has two members: `Jane` and `Jim`. The examples explain: * How the group and users are added to the LDAP server. -* What the resulting group record in {product-title} will be after synchronization. +* What the resulting group record in {product-title} is after synchronization. [NOTE] ==== -These examples assume that all users are direct members of their respective -groups. Specifically, no groups have other groups as members. See -the Nested Membership Sync Example for information on -how to sync nested groups. +These examples assume that all users are direct members of their respective groups. Specifically, no groups have other groups as members. For information on how to sync nested groups, see "LDAP nested membership sync". ==== -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 +In the RFC 2307 schema, users 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: -.LDAP entries that use RFC 2307 schema: `rfc2307.ldif` [source,ldif] ---- dn: ou=users,dc=example,dc=com @@ -50,21 +46,23 @@ schema: dn: ou=groups,dc=example,dc=com objectClass: organizationalUnit ou: groups - dn: cn=admins,ou=groups,dc=example,dc=com <1> + 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 <2> + member: cn=Jane,ou=users,dc=example,dc=com 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. + +where: + +`dn: cn=admins,ou=groups,dc=example,dc=com`:: Specifies that this group is a first-class entry in the LDAP server. +`member: cn=Jane,ou=users,dc=example,dc=com`:: Specifies that the members of a group are listed with an identifying reference as attributes on the group. .Prerequisites -* Create the configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `rfc2307_config.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -74,36 +72,36 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* Run the sync with the `rfc2307_config.yaml` file: +* Sync with the `rfc2307_config.yaml` file by running the following command: + [source,terminal] ---- $ oc adm groups sync --sync-config=rfc2307_config.yaml --confirm ---- + -{product-title} creates the following group record as a result of the above sync -operation: +After you run the sync command, the following group record is created in {product-title}: + -.{product-title} group created by using the `rfc2307_config.yaml` file [source,yaml] ---- apiVersion: user.openshift.io/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> + 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 <4> -users: <5> + name: admins +users: - jane.smith@example.com - jim.adams@example.com ---- -<1> The last time this {product-title} group was synchronized with the LDAP server, in ISO 6801 ++ +where: + +`metadata.annotations.openshift.io/ldap.sync-time`:: Specifies the last time this {product-title} group was synchronized with the LDAP server, in ISO 8601 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. +`metadata.annotations.openshift.io/ldap.uid`:: Specifies the unique identifier for the group on the LDAP server. +`metadata.annotations.openshift.io/ldap.url`:: Specifies the IP address and host of the LDAP server where the record of the group is stored. +`metadata.name`:: Specifies the name of the group as specified by the sync file. +`users`:: Specifies the users that are members of the group, named as specified by the sync file. diff --git a/modules/ldap-syncing-running-all-ldap.adoc b/modules/ldap-syncing-running-all-ldap.adoc index b60b044fbce..71388658276 100644 --- a/modules/ldap-syncing-running-all-ldap.adoc +++ b/modules/ldap-syncing-running-all-ldap.adoc @@ -6,11 +6,12 @@ [id="ldap-syncing-running-all-ldap_{context}"] = Syncing the LDAP server with {product-title} -You can sync all groups from the LDAP server with {product-title}. +[role="_abstract"] +Sync all groups from your LDAP server with {product-title} so you can mirror your complete LDAP group membership in the cluster. .Prerequisites -* Create a sync configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `config.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -20,7 +21,7 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* To sync all groups from the LDAP server with {product-title}: +* Sync all groups from the LDAP server with {product-title} by running the following command: + [source,terminal] ---- @@ -29,7 +30,5 @@ $ oc adm groups sync --sync-config=config.yaml --confirm + [NOTE] ==== -By default, all group synchronization operations are dry-run, so you -must set the `--confirm` flag on the `oc adm groups sync` command to make -changes to {product-title} group records. +By default, all group synchronization operations are dry-run, so you must set the `--confirm` flag on the `oc adm groups sync` command to make changes to {product-title} group records. ==== diff --git a/modules/ldap-syncing-running-openshift.adoc b/modules/ldap-syncing-running-openshift.adoc index 5ce8f353eeb..25636e206a5 100644 --- a/modules/ldap-syncing-running-openshift.adoc +++ b/modules/ldap-syncing-running-openshift.adoc @@ -6,12 +6,14 @@ [id="ldap-syncing-running-openshift_{context}"] = Syncing {product-title} groups with the LDAP server -You can sync all groups already in {product-title} that correspond to groups in the -LDAP server specified in the configuration file. +[role="_abstract"] +Sync existing {product-title} groups with your LDAP server so you can update membership for groups that already exist in the cluster. + +You can sync all groups already in {product-title} that correspond to groups in the LDAP server specified in the configuration file. .Prerequisites -* Create a sync configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `config.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -21,7 +23,7 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* To sync {product-title} groups with the LDAP server: +* Sync {product-title} groups with the LDAP server by running the following command: + [source,terminal] ---- @@ -30,7 +32,5 @@ $ oc adm groups sync --type=openshift --sync-config=config.yaml --confirm + [NOTE] ==== -By default, all group synchronization operations are dry-run, so you -must set the `--confirm` flag on the `oc adm groups sync` command to make -changes to {product-title} group records. +By default, all group synchronization operations are dry-run, so you must set the `--confirm` flag on the `oc adm groups sync` command to make changes to {product-title} group records. ==== diff --git a/modules/ldap-syncing-running-subset.adoc b/modules/ldap-syncing-running-subset.adoc index 9f5872596ea..e172a0823d4 100644 --- a/modules/ldap-syncing-running-subset.adoc +++ b/modules/ldap-syncing-running-subset.adoc @@ -6,21 +6,18 @@ [id="ldap-syncing-running-subset_{context}"] = Syncing subgroups from the LDAP server with {product-title} -You can sync a subset of LDAP groups with {product-title} using whitelist files, -blacklist files, or both. +[role="_abstract"] +Sync a subset of LDAP groups with {product-title} so you can control which groups are synchronized using allowlist files, denylist files, or both. [NOTE] ==== -You can use any combination of blacklist files, whitelist files, or whitelist -literals. Whitelist and blacklist files must contain one unique group identifier -per line, and you can include whitelist literals directly in the command itself. -These guidelines apply to groups found on LDAP servers as well as groups already -present in {product-title}. +You can use any combination of denylist files, allowlist files, or allowlist literals. Allowlist and denylist files must contain one unique group identifier per line, and you can include allowlist literals directly in the command itself. +These guidelines apply to groups found on LDAP servers as well as groups already present in {product-title}. ==== .Prerequisites -* Create a sync configuration file. +* An LDAP sync configuration file exists. This procedure uses an example file named `config.yaml`. ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] * You have access to the cluster as a user with the `cluster-admin` role. endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] @@ -30,21 +27,25 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] .Procedure -* To sync a subset of LDAP groups with {product-title}, use any the following commands: +* To sync groups using an allowlist file, run the following command: + [source,terminal] ---- -$ oc adm groups sync --whitelist= \ +$ oc adm groups sync --whitelist= \ --sync-config=config.yaml \ --confirm ---- + +* To sync groups using a denylist file, run the following command: + [source,terminal] ---- -$ oc adm groups sync --blacklist= \ +$ oc adm groups sync --blacklist= \ --sync-config=config.yaml \ --confirm ---- + +* To sync a single group by the unique identifier of the group, run the following command: + [source,terminal] ---- @@ -52,27 +53,29 @@ $ oc adm groups sync \ --sync-config=config.yaml \ --confirm ---- + +* To sync a single group with both an allowlist and a denylist, run the following command: + [source,terminal] ---- $ oc adm groups sync \ - --whitelist= \ - --blacklist= \ + --whitelist= \ + --blacklist= \ --sync-config=config.yaml \ --confirm ---- + +* To sync existing {product-title} groups using an allowlist file, run the following command: + [source,terminal] ---- $ oc adm groups sync --type=openshift \ - --whitelist= \ + --whitelist= \ --sync-config=config.yaml \ --confirm ---- + [NOTE] ==== -By default, all group synchronization operations are dry-run, so you -must set the `--confirm` flag on the `oc adm groups sync` command to make -changes to {product-title} group records. +By default, all group synchronization operations are dry-run, so you must set the `--confirm` flag on the `oc adm groups sync` command to make changes to {product-title} group records. ==== diff --git a/modules/ldap-syncing-running.adoc b/modules/ldap-syncing-running.adoc index f06004acf9a..0b516ce86c7 100644 --- a/modules/ldap-syncing-running.adoc +++ b/modules/ldap-syncing-running.adoc @@ -6,5 +6,8 @@ [id="ldap-syncing-running_{context}"] = Running LDAP sync -Once you have created a sync configuration file, you can begin to sync. {product-title} allows administrators to perform a number of different sync types with the same server. +[role="_abstract"] +Review LDAP sync types before running group sync between your LDAP server and {product-title}. Each type defines sync direction and scope so you select the command that matches your directory layout. + +After you have created a sync configuration file, you can begin to sync. {product-title} allows administrators to perform several different sync types with the same server. diff --git a/modules/ldap-syncing-spec.adoc b/modules/ldap-syncing-spec.adoc index 37fb5ea85b0..9d2b5dd988a 100644 --- a/modules/ldap-syncing-spec.adoc +++ b/modules/ldap-syncing-spec.adoc @@ -6,38 +6,37 @@ [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. +[role="_abstract"] +Review the LDAP group sync configuration specification so you can identify required fields and schema-specific options for your sync configuration file. + +The following sections describe the object specification for the configuration file. Note that the different schema types define different fields. For example, the `v1.ActiveDirectoryConfig` schema type has no `groupsQuery` field, but the `v1.RFC2307Config` and `v1.AugmentedActiveDirectoryConfig` schema types include a `groupsQuery` field. [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 +There is no support for binary attributes. All attribute data coming from the LDAP server must be in the UTF-8 encoded string format. 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]] +[id="sync-ldap-v1-ldapsyncconfig_{context}"] == v1.LDAPSyncConfig -`LDAPSyncConfig` holds the necessary configuration options to define an LDAP -group sync. +`LDAPSyncConfig` holds the necessary configuration options to define an LDAP group sync. [options="header"] +[caption="Table 1. v1.LDAPSyncConfig fields"] |=== |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[] +|A camel case string value that represents the REST resource this object represents. Servers may infer this value from the endpoint that receives client requests. Clients cannot update this value. |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[] +|Defines the versioned schema for this object representation. Servers should convert recognized schemas to the latest internal value and may reject unrecognized values. |string |`url` -|Host is the scheme, host and port of the LDAP server to connect to: `scheme://host:port` +|Specifies the scheme, host, and port of the LDAP server to connect to, in the form `scheme://host:port`. |string |`bindDN` @@ -45,10 +44,11 @@ group sync. |string |`bindPassword` -|Optional password to bind with during the search phase. |v1.StringSource +|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. +|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` @@ -60,11 +60,11 @@ group sync. |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. +|Holds the configuration for extracting data from an LDAP server set up in a fashion similar to RFC 2307: first-class group and user entries, with group membership determined by a multi-valued attribute on the group entry that lists the members of the group. |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. +|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 member entries that lists the groups to which each member belongs. |v1.ActiveDirectoryConfig |`augmentedActiveDirectory` @@ -72,7 +72,7 @@ group sync. |v1.AugmentedActiveDirectoryConfig |=== -[[sync-ldap-v1-stringsource]] +[id="sync-ldap-v1-stringsource_{context}"] == v1.StringSource `StringSource` allows specifying a string inline, or externally via environment @@ -80,20 +80,21 @@ variable or file. When it contains only a string value, it marshals to a simple JSON string. [options="header"] +[caption="Table 2. v1.StringSource fields"] |=== |Name |Description |Schema |`value` -|Specifies the cleartext value, or an encrypted value if `keyFile` is specified. +|Specifies the plain text value, or an encrypted value if `keyFile` is specified. |string |`env` -|Specifies an environment variable containing the cleartext value, or an +|Specifies an environment variable containing the plain text 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. +|References a file containing the plain text value, or an encrypted value if a `keyFile` is specified. |string |`keyFile` @@ -101,12 +102,13 @@ encrypted value if the `keyFile` is specified. |string |=== -[[sync-ldap-v1-ldapquery]] +[id="sync-ldap-v1-ldapquery_{context}"] == v1.LDAPQuery `LDAPQuery` holds the options necessary to build an LDAP query. [options="header"] +[caption="Table 3. v1.LDAPQuery fields"] |=== |Name |Description |Schema @@ -136,17 +138,17 @@ Defaults to `always` if not set. |string |`pageSize` -|Maximum preferred page size, measured in LDAP entries. A page size of `0` means no paging will be done. +|Maximum preferred page size, measured in LDAP entries. A page size of `0` means no paging is done. |integer |=== -[[sync-ldap-v1-rfc2307config]] +[id="sync-ldap-v1-rfc2307config_{context}"] == v1.RFC2307Config -`RFC2307Config` holds the necessary configuration options to define how an LDAP -group sync interacts with an LDAP server using the RFC2307 schema. +`RFC2307Config` holds the necessary configuration options to define how an LDAP group sync interacts with an LDAP server using the RFC 2307 schema. [options="header"] +[caption="Table 4. v1.RFC2307Config fields"] |=== |Name |Description |Schema @@ -155,15 +157,15 @@ group sync interacts with an LDAP server using the RFC2307 schema. |v1.LDAPQuery |`groupUIDAttribute` -|Defines which attribute on an LDAP group entry will be interpreted as its unique identifier. (`ldapGroupUID`) +|Defines which attribute on an LDAP group entry is interpreted as the unique identifier of the group. The default value is `ldapGroupUID`. |string |`groupNameAttributes` -|Defines which attributes on an LDAP group entry will be interpreted as its name to use for an {product-title} group. +|Defines which attributes on an LDAP group entry are interpreted as the name of the group 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`. +|Defines which attributes on an LDAP group entry are interpreted as the members of the group. The values contained in those attributes must be queryable by your `userUIDAttribute` field. |string array |`usersQuery` @@ -171,24 +173,23 @@ group sync interacts with an LDAP server using the RFC2307 schema. |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`. +|Defines which attribute on an LDAP user entry is interpreted as the unique identifier of the user. It must correspond to values that are found from the `groupMembershipAttributes` field. |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. +|Defines which attributes on an LDAP user entry are used, in order, as the {product-title} user name of the user. 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. +|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 is tolerated and only an error is logged. If `false`, the LDAP sync job fails 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. +|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 is tolerated and only an error is logged. If `false`, the LDAP sync job fails if a user query searches 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]] +[id="sync-ldap-v1-activedirectoryconfig_{context}"] == v1.ActiveDirectoryConfig `ActiveDirectoryConfig` holds the necessary configuration options to define how @@ -196,6 +197,7 @@ an LDAP group sync interacts with an LDAP server using the Active Directory schema. [options="header"] +[caption="Table 5. v1.ActiveDirectoryConfig fields"] |=== |Name |Description |Schema @@ -204,23 +206,22 @@ schema. |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. +|Defines which attributes on an LDAP user entry are interpreted as the {product-title} user name of the user. 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. +|Defines which attributes on an LDAP user entry are interpreted as the LDAP groups that include the user as a member. |string array |=== -[[sync-ldap-v1-augmentedactivedirectoryconfig]] +[id="sync-ldap-v1-augmentedactivedirectoryconfig_{context}"] == 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. +The `AugmentedActiveDirectoryConfig` field 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"] +[caption="Table 6. v1.AugmentedActiveDirectoryConfig fields"] |=== |Name |Description |Schema @@ -229,12 +230,11 @@ Active Directory schema. |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. +|Defines which attributes on an LDAP user entry are interpreted as the {product-title} user name of the user. 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. +|Defines which attributes on an LDAP user entry are interpreted as the LDAP groups that include the user as a member. |string array |`groupsQuery` @@ -242,10 +242,10 @@ record. `mail` or `sAMAccountName` are preferred choices in most installations. |v1.LDAPQuery |`groupUIDAttribute` -|Defines which attribute on an LDAP group entry will be interpreted as its unique identifier. (`ldapGroupUID`) +|Defines which attribute on an LDAP group entry is interpreted as the unique identifier of the group. The default value is `ldapGroupUID`. |string |`groupNameAttributes` -|Defines which attributes on an LDAP group entry will be interpreted as its name to use for an {product-title} group. +|Defines which attributes on an LDAP group entry are interpreted as the name of the group to use for an {product-title} group. |string array |===