diff --git a/modules/admin_manual/pages/configuration/server/occ_commands/app_commands/_ldap_integration_commands.adoc b/modules/admin_manual/pages/configuration/server/occ_commands/app_commands/_ldap_integration_commands.adoc index d15f84396b..5efba5e0fc 100644 --- a/modules/admin_manual/pages/configuration/server/occ_commands/app_commands/_ldap_integration_commands.adoc +++ b/modules/admin_manual/pages/configuration/server/occ_commands/app_commands/_ldap_integration_commands.adoc @@ -5,24 +5,111 @@ Marketplace URL: {oc-marketplace-url}/apps/user_ldap[LDAP Integration] [source,console] ---- ldap - ldap:check-user Checks whether a user exists on LDAP. + ldap:check-user Checks whether a user exists on LDAP ldap:create-empty-config Creates an empty LDAP configuration ldap:delete-config Deletes an existing LDAP configuration + ldap:invalidate-cache Invalidates the LDAP cache ldap:search Executes a user or group search ldap:set-config Modifies an LDAP configuration ldap:show-config Shows the LDAP configuration ldap:test-config Tests an LDAP configuration ---- +== Search for a User + Search for an LDAP user, using this syntax: [source,console,subs="attributes+"] ---- -{occ-command-example-prefix} ldap:search [--group] [--offset="..."] [--limit="..."] search +{occ-command-example-prefix} ldap:search [options] [--] ---- +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| `search` +| The search string (can be empty) +|=== + +=== Options + +[width="100%",cols="20%,70%",] +|=== +| `--group` +| Searches groups instead of users + +| `--offset=OFFSET` +| The offset of the result set. Needs to be a multiple of limit. defaults to 0. [default: 0] + +| `--limit=LIMIT` +| Limit the results. 0 means no limit, defaults to 15 [default: 15] +|=== + +Note that the search sting can be empty to list all users, or groups when the `--group` option is set. In this case, the search sting must be declared with `''`. It is by default a prefix search. Start the string with `*` to change to infix (substring) search. + +=== Search Configuration and Rules + +Search attributes are configurable in the LDAP wizard (menu:Settings[Admin > User Authentication > LDAP]) or via an occ command `ldap:set-config` as described below: + +.General rule +. If User/Group _Search Attributes_ are *NOT* defined (empty), the entry defined in the User/Group _Display Name Field_ is used as search attribute, for details see below. +. Important when having multiple search attributes, results are unique as long hits correspond to a unique user or group entry. + +.Rules for users +. If *User Search Attributes* are defined (not empty) in: ++ +menu:Settings[Admin > User Authentication > LDAP > Advanced > User Search Attributes] ++ +`ldapAttributesForUserSearch` + +.. Example ++ +If your search attributes would be `givenName` and `sn` you can find users by first name + last name very quickly. You will find "Terri Hanson" by searching for `te ha`. Trailing whitespace is ignored. +. Else use the *User Display Name Field* which usually defaults to the default displayname attribute "displayname" ++ +menu:Settings[Admin > User Authentication > LDAP > Advanced > User Display Name Field] ++ +`ldapUserDisplayName` + + +.Rules for groups +. If *Group Search Attributes* are defined (not empty) in: ++ +menu:Settings[Admin > User Authentication > LDAP > Advanced > Group Search Attributes] ++ +`ldapAttributesForGroupSearch` +. Else use the *Group Display Name Field* which usually defaults to the default displayname attribute "cn" ++ +menu:Settings[Admin > User Authentication > LDAP > Advanced > Group Display Name Field] ++ +`ldapGroupDisplayName` + +.Offset and Limit +The best way understanding `offset` and `limit` is the following table when using `occ ldap:search '' [options]` +[caption=] +[width="50%",cols="20%,30%",options="header"] +|=== +| Options +| Result Set + +| `--offset 0` + +`--limit 5` +| "A", "B", "C", "D" and "E" -Searches match at the beginning of the attribute value only. -This example searches for `givenNames` that start with 'rob': +| `--offset 5` + +`--limit 5` +| "F", "G", "H", "I" and "J" + +| `--offset 1` + +`--limit 3` +| "B", "C" and "D" +|=== + + + +=== Examples + +Searches match at the beginning of the attribute value only. This example searches for `givenNames` that contain 'rob': [source,console,subs="attributes+"] ---- @@ -37,39 +124,90 @@ Broaden the search to find, for example, `jeroboam` with the asterisk wildcard: {occ-command-example-prefix} ldap:search "*rob" ---- -User search attributes are set with `ldap:set-config` (below). -For example, if your search attributes are `givenName` and `sn` you can find users by first name + last name very quickly. -For example, you’ll find 'Terri Hanson' by searching for `te ha`. -Trailing whitespace is ignored. +The following examples use `offset` and `limit` options: + +[source,console,subs="attributes+"] +---- +{occ-command-example-prefix} ldap:search "re" +Rebecca OShea (Rebecca.OShea) +Rebecca Vintin (Rebecca.Vintin) +Rebekka Da-Cahuna (Rebekka.Da-Cahuna) +Rekha Cox (Rekha.Cox) +Rekha Craft (Rekha.Craft) +---- + +[source,console,subs="attributes+"] +---- +{occ-command-example-prefix} ldap:search "re" --offset 0 --limit 3 +Rebecca OShea (Rebecca.OShea) +Rebecca Vintin (Rebecca.Vintin) +Rebekka Da-Cahuna (Rebekka.Da-Cahuna) +---- + +[source,console,subs="attributes+"] +---- +{occ-command-example-prefix} ldap:search "re" --offset 3 --limit 3 +Rekha Cox (Rekha.Cox) +Rekha Craft (Rekha.Craft) +---- + +== Check if an LDAP User Exists + +This only works if the ownCloud server is connected to an LDAP server. + +[source,console,subs="attributes+"] +---- +ldap:check-user [options] [--] +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| `ocName` +| The user name as used in ownCloud (see e.g. the user's Federated Cloud ID). +|=== -Check if an LDAP user exists. -This works only if the ownCloud server is connected to an LDAP server. +=== Options + +[width="100%",cols="20%,70%",] +|=== +| `--force` +| Ignores disabled LDAP configuration +|=== + +Example: [source,console,subs="attributes+"] ---- {occ-command-example-prefix} ldap:check-user robert ---- -`ldap:check-user` will not run a check when it finds a disabled LDAP connection. -This prevents users that exist on disabled LDAP connections from being marked as deleted. -If you know for sure that the user you are searching for is not in one of the disabled connections, and exists on an active connection, use the `--force` option to force it to check all active LDAP connections. +`ldap:check-user` will not run a check when it finds a disabled LDAP connection. This prevents users that exist on disabled LDAP connections from being marked as deleted. If you know for sure that the user you are searching for is not in one of the disabled connections and exists on an active connection, use the `--force` option to force a check of all active LDAP connections. [source,console,subs="attributes+"] ---- {occ-command-example-prefix} ldap:check-user --force robert ---- -`ldap:create-empty-config` creates an empty LDAP configuration. -The first one you create has no `configID`, like this example: +== Create an Empty LDAP Configuration + +Create an empty LDAP configuration. [source,console,subs="attributes+"] ---- -{occ-command-example-prefix} ldap:create-empty-config - Created new configuration with configID '' +ldap:create-empty-config [] ---- -This is a holdover from the early days, when there was no option to create additional configurations. -The second, and all subsequent, configurations that you create are automatically assigned IDs. +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| `configID` +| Create a configuration with the specified id +|=== + +Configurations that you create without assigning a are automatically assigned IDs. [source,console,subs="attributes+"] ---- @@ -77,21 +215,66 @@ The second, and all subsequent, configurations that you create are automatically Created new configuration with configID 's01' ---- -Then you can list and view your configurations: +== List and View Your Configurations + +You can list and view your configurations: + +[source,console,subs="attributes+"] +---- +{occ-command-example-prefix} ldap:show-config [options] [--] [] +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| `configID` +| Will show the configuration of the specified id +|=== + +=== Options + +[width="100%",cols="20%,70%",] +|=== +| `--show-password` +| Show LDAP bind password + +| `--output[=OUTPUT]` +| The output format to use (plain, json or json_pretty). [default: "plain"] +|=== + +==== Examples + +If you omit the `configID`, all configuration ID's with their settings are listed: [source,console,subs="attributes+"] ---- {occ-command-example-prefix} ldap:show-config ---- -And view the configuration for a single `configID`: +View the configuration for a single `configID`: [source,console,subs="attributes+"] ---- {occ-command-example-prefix} ldap:show-config s01 ---- -`ldap:delete-config [configID]` deletes an existing LDAP configuration. +== Delete an Existing LDAP Configuration + +Deletes an existing LDAP configuration. + +[source,console,subs="attributes+"] +---- + ldap:delete-config +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| `configID` +| The configuration ID +|=== [source,console,subs="attributes+"] ---- @@ -99,77 +282,122 @@ And view the configuration for a single `configID`: Deleted configuration with configID 's01' ---- -The `ldap:set-config` command is for manipulating configurations, like this example that sets search attributes: +== Invalidate LDAP Cache + +This command invalidates the LDAP cache for all users: + +[source,console,subs="attributes+"] +---- +{occ-command-example-prefix} ldap:invalidate-cache +---- + +== Manipulate LDAP Configurations + +This command manipulates LDAP configurations. [source,console,subs="attributes+"] ---- -{occ-command-example-prefix} ldap:set-config s01 ldapAttributesForUserSearch -"cn;givenname;sn;displayname;mail" +{occ-command-example-prefix} ldap:set-config ---- -The command takes the following format: +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| `configID` +| The configuration ID +| `configKey` +| The configuration key + +| `configValue` +| The new configuration value +|=== + +If a `configKey` allows multiple entries like the key `ldapAttributesForUserSearch`, use semicolons without a whitespace to separate them. + +This example sets search attributes: + +[source,console,subs="attributes+"] ---- -ldap:set-config +{occ-command-example-prefix} ldap:set-config s01 ldapAttributesForUserSearch "cn;givenname;sn;displayname;mail" ---- -All of the available keys, along with default values for configValue, are listed in the table below. +Available keys, along with default values for configValue, are listed in the table below. [width="70%",cols=",",options="header",] |=== -| Configuration | Setting -| hasMemberOfFilterSupport | -| hasPagedResultSupport | -| homeFolderNamingRule | -| lastJpegPhotoLookup | 0 -| ldapAgentName | cn=admin,dc=owncloudqa,dc=com -| ldapAgentPassword | _*_ -| ldapAttributesForGroupSearch | -| ldapAttributesForUserSearch | -| ldapBackupHost | -| ldapBackupPort | -| ldapBase | dc=owncloudqa,dc=com -| ldapBaseGroups | dc=owncloudqa,dc=com -| ldapBaseUsers | dc=owncloudqa,dc=com -| ldapCacheTTL | 600 -| ldapConfigurationActive | 1 -| ldapDynamicGroupMemberURL | -| ldapEmailAttribute | -| ldapExperiencedAdmin | 0 -| ldapExpertUUIDGroupAttr | -| ldapExpertUUIDUserAttr | -| ldapExpertUsernameAttr | ldapGroupDisplayName cn -| ldapGroupFilter | ldapGroupFilterGroups -| ldapGroupFilterMode | 0 -| ldapGroupFilterObjectclass | -| ldapGroupMemberAssocAttr | uniqueMember -| ldapHost | ldap://host -| ldapIgnoreNamingRules | -| ldapLoginFilter | (&((objectclass=inetOrgPerson))(uid=%uid)) -| ldapLoginFilterAttributes | -| ldapLoginFilterEmail | 0 -| ldapLoginFilterMode | 0 -| ldapLoginFilterUsername | 1 -| ldapNestedGroups | 0 -| ldapOverrideMainServer | -| ldapPagingSize | 500 -| ldapPort | 389 -| ldapQuotaAttribute | -| ldapQuotaDefault | -| ldapTLS | 0 -| ldapUserDisplayName | displayName -| ldapUserDisplayName2 | -| ldapUserFilter | ((objectclass=inetOrgPerson)) -| ldapUserFilterGroups | -| ldapUserFilterMode | 0 -| ldapUserFilterObjectclass | inetOrgPerson -| ldapUuidGroupAttribute | auto -| ldapUuidUserAttribute | auto -| turnOffCertCheck | 0 +| Configuration | Setting +| hasMemberOfFilterSupport | +| hasPagedResultSupport | +| homeFolderNamingRule | +| lastJpegPhotoLookup | 0 +| ldapAgentName | cn=admin,dc=owncloudqa,dc=com +| ldapAgentPassword | _*_ +| ldapAttributesForGroupSearch | +| ldapAttributesForUserSearch | +| ldapBackupHost | +| ldapBackupPort | +| ldapBase | dc=owncloudqa,dc=com +| ldapBaseGroups | dc=owncloudqa,dc=com +| ldapBaseUsers | dc=owncloudqa,dc=com +| ldapCacheTTL | 600 +| ldapConfigurationActive | 1 +| ldapDynamicGroupMemberURL | +| ldapEmailAttribute | +| ldapExperiencedAdmin | 0 +| ldapExpertUUIDGroupAttr | +| ldapExpertUUIDUserAttr | +| ldapExpertUsernameAttr | +| ldapGroupDisplayName | cn +| ldapGroupFilter | +| ldapGroupFilterMode | 0 +| ldapGroupFilterObjectclass | +| ldapGroupMemberAssocAttr | uniqueMember +| ldapHost | ldap://host +| ldapIgnoreNamingRules | +| ldapLoginFilter | (&((objectclass=inetOrgPerson))(uid=%uid)) +| ldapLoginFilterAttributes | +| ldapLoginFilterEmail | 0 +| ldapLoginFilterMode | 0 +| ldapLoginFilterUsername | 1 +| ldapNestedGroups | 0 +| ldapOverrideMainServer | +| ldapPagingSize | 500 +| ldapPort | 389 +| ldapQuotaAttribute | +| ldapQuotaDefault | +| ldapTLS | 0 +| ldapUserDisplayName | displayName +| ldapUserDisplayName2 | +| ldapUserFilter | ((objectclass=inetOrgPerson)) +| ldapUserFilterGroups | +| ldapUserFilterMode | 0 +| ldapUserFilterObjectclass | inetOrgPerson +| ldapUuidGroupAttribute | auto +| ldapUuidUserAttribute | auto +| turnOffCertCheck | 0 | useMemberOfToDetectMembership | 1 |=== -`ldap:test-config` tests whether your configuration is correct and can bind to the server. +== Test Your Configuration + +Tests whether your configuration is correct and can bind to the server. + +[source,console,subs="attributes+"] +---- +{occ-command-example-prefix} ldap:test-config +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| `configID` +| The configuration ID +|=== + +Example: [source,console,subs="attributes+"] ---- @@ -177,6 +405,8 @@ All of the available keys, along with default values for configValue, are listed The configuration is valid and the connection could be established! ---- +== Set and Unset LDAP App Configurations + [source,console,subs="attributes+"] ---- {occ-command-example-prefix} config:app:set user_ldap updateAttributesInterval --value=7200 @@ -204,9 +434,9 @@ If you want to allow new LDAP logins to attempt to reuse existing `oc_accounts` Below is an example of how to do so. [source,console,subs="attributes+"] -.... -{occ-command-example-prefix} config:app:set user_ldap reuse_accounts --value=yes -.... +---- +{occ-command-example-prefix} config:app:set user_ldap reuse_accounts --value="yes" +---- This functionality is valuable for several reasons; these are: @@ -214,9 +444,9 @@ This functionality is valuable for several reasons; these are: * It allows auto-provisioned users with Shibboleth to be moved over to an LDAP server, but be able to continue using ownCloud. [IMPORTANT] -== +==== This functionality will not work in the following situations: . No user or group account exists with the supplied username. . A user or group account exists, but it uses a different backend. -== +====