Enable case insensitive login to Gerrit WebUI for LDAP authentication
Gerrit treats user names as case sensitive, while some LDAP servers
don't. On first login to Gerrit the user enters his user name and
Gerrit queries LDAP for it. Since LDAP is case-insensitive with regards
to the username, the LDAP authentication succeeds regardless in
which case the user typed in his user name. The username is stored in
Gerrit exactly as entered by the user. For further logins the user
always has to use the same case. If the user specifies his user name in
a different case Gerrit tries to create a new account which fails with
"Cannot assign user name ... to account ...; name already in use.".
This error occurs because the LDAP query resolves to the same LDAP
user and storing the username for SSH (which is by default always
lower case) fails because such an entry exists already for the first
account that the user created.
This change introduces a new configuration parameter that converts the
user name always to lower case before doing the LDAP authentication.
By this the login to the Gerrit WebUI gets case insensitive. If this
configuration parameter is set, the user names for all existing
accounts have to be converted to lower case. This change includes a
server program to do this conversion.
Change-Id: I2d9099509b9438eaf88506c99e4dd3cc82a9140f
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/pgm-LocalUsernamesToLowerCase.txt b/Documentation/pgm-LocalUsernamesToLowerCase.txt
new file mode 100644
index 0000000..9189fee
--- /dev/null
+++ b/Documentation/pgm-LocalUsernamesToLowerCase.txt
@@ -0,0 +1,68 @@
+LocalUsernamesToLowerCase
+=========================
+
+NAME
+----
+LocalUsernamesToLowerCase - Convert the local username of every
+account to lower case
+
+SYNOPSIS
+--------
+[verse]
+'java' -jar gerrit.war 'LocalUsernamesToLowerCase' -d <SITE_PATH>
+
+DESCRIPTION
+-----------
+Converts the local username for every account to lower case. The
+local username is the username that is used to login into the Gerrit
+WebUI.
+
+This task is only intended to be run if the configuration parameter
+link:config-gerrit.html#ldap.localUsernameToLowerCase[ldap.localUsernameToLowerCase]
+was set to true to achieve case insensitive LDAP login to the Gerrit
+WebUI.
+
+Please be aware that the conversion of the local usernames to lower
+case can't be undone.
+
+The program will produce errors if there are accounts that have the
+same local username, but with different case. In this case the local
+username for these accounts is not converted to lower case.
+
+This task can run in the background concurrently to the server if the
+database is MySQL or PostgreSQL. If the database is H2, this task
+must be run by itself.
+
+OPTIONS
+-------
+
+-d::
+\--site-path::
+ Location of the gerrit.config file, and all other per-site
+ configuration data, supporting libraries and log files.
+
+\--threads::
+ Number of threads to perform the scan work with. Defaults to
+ twice the number of CPUs available.
+
+CONTEXT
+-------
+This command can only be run on a server which has direct
+connectivity to the metadata database.
+
+EXAMPLES
+--------
+To convert the local username of every account to lower case:
+
+====
+ $ java -jar gerrit.war LocalUsernamesToLowerCase -d site_path
+====
+
+See Also
+--------
+
+* Configuration parameter link:config-gerrit.html#ldap.localUsernameToLowerCase[ldap.localUsernameToLowerCase]
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
