SVN authentication options
- 1. Subversion access and authentication overview
- 2. SubGit authentication options
- 2.1 Using plain username and password
- 2.2 Using passwords file
- 2.3 SSH keyfile and passphrase
- 2.4 SSL keyfile and passphrase
- 2.5 Credential helper programs
- 2.6 Subversion configuration directory
Chapter 1. Subversion access protocols and authentication methods overview.
SubGit is a tool intended to translate data from Subversion to Git. To gather a data from a SVN repository, SubGit accesses remote Subversion server over the network as all other SVN clients do and, thus, SubGit acts like a regular SVN client and uses all the same protocols that the SVN supports. There are four protocols SubGit can use to access a SVN repository:
file://protocol; it is being used when both SVN and Git repositories reside on the same machine. In this case, local operating system account is used for access and no additional authentication configuration is needed.
svn://protocol that is being used in conjunction with a small, lightweight server program called
svnservecan use built-in CRAM-MD5 authentication, or, alternatively, there is a possibility to use the Cyrus Simple Authentication and Security Layer (SASL) library that can bring additional authentication possibilities like Kerberos, NTLM, and others. All those protocols, though, eventually rely on username and password.
svn://protocol may be tunneled over an
ssh://connection thus forming so called
svn+ssh://protocol. In this case, a SVN server actually relies on existing
sshinfrastructure for authentication and authorization. SubGit can use either password or key-based authentication to enter the SVN server.
finally, a SVN repository may be accessed through a web server (usually Apache) over
http(s)://. The web server may be set to use Basic, Digest, NTLM or Negotiate HTTP authentication thus relying upon username and password; additionally, a client SSL certificate may be requested to prove client’s identity.
All these protocols, but simple
file://, require some configuration and that is this document is intended for - to describe all the available configuration options and how to set SubGit to use different protocols for SVN access.
Chapter 2. SubGit configuration file authentication options.
SubGit has few configuration options spread across different configuration files and other places.
First, there is [auth] section in SubGit configuration file where a username and password for SVN access, SSH and SSL key files and passphrases, a path to SVN configuration directory and a path to a credential helper program may be set. There may be more than one [auth] section in the configuration file, but only
default is intended to store SVN authentication data, so we will refer to the [auth “default”] section later in this article.
Then, there is a password file (default is
subgit/passwd), that is intended to store SVN usernames and corresponding passwords. SubGit uses those usernames to access a SVN repository in compliance with author mapping.
Finally, there is a Subversion client configuration directory (
~/.subversion by default) where SVN can cache authentication data (like username and password, certificates passphrases etc.) and where SubGit can read it from.
Some configurations options are mutually exclusive and some cannot be used together, but basically, SubGit uses the following algorithm to determine which authentication option should be used in every particular case and find appropriate authentication data:
- if the
passwordoptions are set in [auth] section of the SubGit configuration file, SubGit will use them to access the SVN repository;
- if those options are not set, but the password file (
subgit/passwdby default) is filled out with SVN usernames and passwords, SubGit will use those users;
- if neither
password, not password file are set, SubGit will try to use SSL client certificate for authentication;
- if none of the above is set, SubGit will use SSH key file;
- if even the SSH key configuration option is not set, SubGit will try to user credential helper;
- if the path to the credential helper is not set, SubGit will try to find usable SVN authentication data in SVN configuration directory;
- if none of the above is found, SubGit will report an authentication error and stop the translation process.
Chapter 2.1 Username and password configuration options.
The simplest way to provide SubGit with SVN access is to set SVN username and appropriate password in
[auth] section of the SubGit configuration file. The settings are simple like this:
userName = NAME password = PASSWORD
NAME here represents a username to be used to enter to Subversion repository; the
PASSWORD refers to a password to be used with the explicitly specified user name. The password is being stored in clear text so it would worth to limit access to the SubGit configuration file.
If no other authentication data is set, SubGit will use this SVN username to access the SVN repository over all possible protocols.
As an example, suppose, you intend to use SVN user ‘user’ with password ‘Password’ to access a SVN project. To make it done you can set the
password in the SubGit configuration file:
[auth "default"] userName = user password = Password #passwords = #credentialHelper = #sshKeyFile = #sshKeyFilePassphrase = #sslClientCertFile = #sslClientCertPassphrase = #subversionConfigurationDirectory =
and that’s all that needed, SubGit will then use this account to access SVN for all the operations it performs. Note, all the rest
[auth] options may be either commented or removed since they are not needed in this configuration.
Chapter 2.2 Passwords configuration option.
The second configuration options that deals with SVN usernames and their passwords is
auth.passwords. This option represents a path to password file - namely, the file containing SVN username/password pairs that can be used to log into the Subversion repository. The path can be absolute or relative to the Git repository where import/mirror from SVN is being performed to:
passwords = PATH
default value is
subgit/passwd and this default file contains one username-password pair from scratch:
# This is SubGit password credentials file. # Username/password pairs specified in this file will be used to log into Subversion repository # both for reading and writing purposes. # # This file uses simple format, and consists of the lines in the following format: # # svnUserName svnUserPassword # subgit secret
of course, that ‘subgit secret’ pair is not valid SVN accout, it just represents how to set the username/passwords pairs and that is indeed that easy:
this looks similar to the
auth.password options we have described above and you may be wondering why the password file exists and why there are more than one username/password pair. The answer refers to authors mapping and how SubGit sets SVN revision author name during Git commit to SVN revision translation:
- at first step, SubGit takes the Git commit author’s name and looks into authors mapping file to find out which SVN name is this Git user mapped to.
- if there is a match and the SVN username is found, SubGit then searches the password file for that account password.
- if the record is found in the password file, SubGit uses this SVN account to access the SVN repository, translates the Git commit into a new SVN revision and sets that particular SVN username as the revision author.
- if, for any reason, there is no such user in the password file, SubGit uses any other available SVN account, creates new revision and sets the revision author name to this SVN username.
- after that, SubGit accesses the repostiory once again and changes
svn:authorproperty to the correct author’s name it found in the authors mapping file.
So if the password file is set and fullfilled with the correct usernames and passwords, it makes SubGit’s job to set the
svn:author a little easier. Note, that passwords are stored in clear text so it worth to set restrictive permissions on this file to keep them secret.
To illustrate this configuration, imagine that you are a development team of three members. You have a project in SVN repository and you intend to mirror that SVN project into Git repository to be able to use both SVN and Git. During a Git commit to SVN revision translation you want SubGit to create SVN revisions using a SVN user account that corresponds to a Git user created the commit. To get it done, first you need to fill out authors file, like:
john_doe = John Doe <firstname.lastname@example.org> jake_smith = Jake Smith <email@example.com> david_jones = David Jones <firstname.lastname@example.org>
This step is essential for this configuration since SubGit needs to know which SVN user name corresponds to which Git user in order to use correct SVN username for authentication. The next step is to set
passwords option in Subgit
[auth "default"] passwords = subgit/passwd #userName = #password = #credentialHelper = #sshKeyFile = #sshKeyFilePassphrase = #sslClientCertFile = #sslClientCertPassphrase = #subversionConfigurationDirectory =
Note that the rest configuration options may be either commented or removed. The default
passwd file resides in
subgit directory inside the Git repository. If that’s appropriate, just fill the file with SVN usernames and their passwords:
# This is SubGit password credentials file. # Username/password pairs specified in this file will be used to log into Subversion repository # both for reading and writing purposes. # # This file uses simple format, and consists of the lines in the following format: # # svnUserName svnUserPassword # john_doe Password jake_smith Secret david_jones passKey
passKey here represent those users passwords.
Chapter 2.3 SSH key-based authentication.
Another method to get authenticated on the SVN server is to use key-based SSH authentication. This is the authentication type SSH software provides so it evidently works only in conjunction with
svn+ssh:// protocol. The main idea behind the key-based authentication is that only private key can decrypt messages been encrypted by corresponding public key. So for the authentication, a public key is being placed on a server and a client possesses private key thus proving its identity by being able to decrypt a challenge the server sends to it. The private key can be additionally protected by the passphrase.
There are two configuration options in SubGit configuration file that have to be set to use key-based authentication. The first is a path to the private key that can be used to login:
sshKeyFile = PATH
The path can be either absolute or relative to the Git repository where import/mirror from SVN is being performed to.
The second option is the private key passphrase:
sshKeyFilePassphrase = passphrase
it is optional and can be omitted if the key doesn’t have the passphrase.
Additionally, SubGit needs a username to be specified when using key-based authentication. The username can be set either by
auth.userName in the configuration file:
userName = user
or it can be mentioned in the SVN project URL - that is, in
svn.url configuration option:
[svn] url = svn+ssh://email@example.com/svn/repository/project
Note, that key-based is mutually exclusive password-based authentication - that is if the
auth.sshKeyFile option is set, SubGit will use key-based authentication to access a SVN repository over
svn+ssh:// and the
auth.passwords options will be ignored.
To provide a key-based configuration example let’s suppose you have a SVN server where your project lives and another Linux server where you intend to install SubGit and host mirrored Git repository. To be able to access the SVN repository over
svn+ssh:// using key-based authentication first a key pair should be created that can be done by
$ ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Thepassphrase Enter same passphrase again: Thepassphrase Your identification has been saved in /home/user/.ssh/id_rsa. Your public key has been saved in /home/user/.ssh/id_rsa.pub. The key fingerprint is: 9a:75:52:d8:bb:22:06:a3:fe:86:d5:2b:cd:53:4a:bd firstname.lastname@example.org The key's randomart image is: +--[ RSA 2048]----+ | | | o | | . o | | . . | | o. .S o | | ..oo+oo . | | .o +=+... | | .. o.*.E. | | .o.. . | +-----------------+
Here the key is being created with a passphrase ‘Thepassprase’. By default, the key pair will be placed into
.ssh directory in a user’s home directory.
The next step is to place the public key to the SVN server. It can be done either manually or by using
ssh-copy-id utility, that’s intended just for that - copy the public key to a remote machine and prepare it to work.
$ ssh-copy-id email@example.com The authenticity of host 'svn.example.com' can't be established. ECDSA key fingerprint is 31:09:6f:4c:2f:5e:fb:4d:de:e6:52:5a:c9:f8:f1:03. Are you sure you want to continue connecting (yes/no)? yes /usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed /usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys firstname.lastname@example.org's password: Number of key(s) added: 1 Now try logging into the machine, with: "ssh 'email@example.com'" and check to make sure that only the key(s) you wanted were added.
If the key pair resides at the default location in
ssh-copy-id then the command can be invoked with no options but server address, like in the example; otherwise the command-line option
-i [identity_file] should be provided.
The next step is to set SubGit configuration options:
[svn] url = svn+ssh://svn.example.com/svn/repository/project [auth "default"] userName = user sshKeyFile = /home/user/.ssh/id_rsa sshKeyFilePassphrase = Thepassphrase #password = #passwords = subgit/passwd #credentialHelper = #sslClientCertFile = #sslClientCertPassphrase = #subversionConfigurationDirectory =
Note that SubGit has to have access to the private key file. In this example, the file is left in the ‘user’ home directory supposing SubGit installation is being run on behalf of the ‘user’. Generally, you can store the file anywhere you like, but check if the access to the file is granted to the user account of which behalf SubGit is working.
Chapter 2.4 SSL client certificate authentication.
In addition to username and password authentication, a web server, that hosts a Subversion repository, may require a client to provide SSL certificate to prove its identity. To be able to handle such a case SubGit has to configuration options:
sslClientCertFile = PATH sslClientCertPassphrase = PASSPHRASE
Their meaning is pretty evident, the first, sslClientCertFile, represents a path to the client SSL certificate file in PKSC#12 format; the path can be either absolute or relative to the Git repository. The second option, sslClientCertPassphrase, is the certificate passphrase in clear text.
Note, that a web server may either rely only on a SSL client certificate for authentication, or it may require username and password to be provided in addition to the certificate. In the latter case, SubGit will need not only the two options above to be set but additionally a username and password to be provided in any suitable way.
To illustrate such a case, suppose we have a SVN server that provides access through Apache and it is set to require both SSL client certificate and valid username and password. Apache’s configuration for the SVN repository may look like this:
<VirtualHost _default_:443> LogLevel warn SSLEngine on SSLCertificateFile /etc/httpd/conf/srvr.cer SSLCertificateKeyFile /etc/httpd/conf/srvr.key SSLVerifyClient require SSLVerifyDepth 1 SSLCACertificateFile /etc/httpd/conf/ca.cer <Location /svn> DAV svn SVNParentPath /svn SVNListParentPath on AuthType Basic AuthName "Subversion Repository" AuthUserFile /etc/httpd/conf/svn-auth-file Require valid-user </Location> </VirtualHost>
When access that SVN server, SubGit first will be asked for the SSL certificate and then, if passed, it will be asked for valid username and password. So we need to provide SubGit with both:
[svn] url = https://svn.example.com/svn/repository/project [auth "default"] userName = user password = Passw0rd sslClientCertFile = subgit/client.p12 sslClientCertPassphrase = Passphr4se #passwords = subgit/passwd #credentialHelper = #sslClientCertFile = #sslClientCertPassphrase = #subversionConfigurationDirectory = #sshKeyFile = #sshKeyFilePassphrase =
Note that using the
password options is not the only way to provide SubGit with the credentials - in fact, any method can be used - username and password in the configuration file, passwords file, cached credentials or even credential helper. You have to set appropriate option in the configuration file depending on what the method you decided to use. For example, if you intend to use passwords file you need to set the SubGit configuration like this:
[svn] url = https://svn.example.com/svn/repository/project [auth "default"] passwords = subgit/passwd sslClientCertFile = subgit/client.p12 sslClientCertPassphrase = Passphr4se #userName = #password = #credentialHelper = #sslClientCertFile = #sslClientCertPassphrase = #subversionConfigurationDirectory = #sshKeyFile = #sshKeyFilePassphrase =
and so you need to do in any other case, find the details in appropriate chapters.
Chapter 2.5 Credential helper program.
In addition to all the methods we have examined so far, SubGit supports so called “helper” programs. A “helper” is basically a non-interactive (producing no prompt) program that expects input and provides output in a format Git credential helper uses:
url = SVN_URL protocol = SVN_URL_PROTOCOL path = SVN_URL_PATH username = PREFFERED_SVN_USER_NAME
username = SVN_USER_NAME password = SVN_PASSWORD
This option makes possible to write some script that will gather information from external sources like LDAP catalog or any other authentication server or database.
To make SubGit able to use the helper there’s a configuration option in the configuration file:
credentialHelper = PATH [args]
that represents a path to the credential helper program and its optional arguments. The path can be absolute or relative to the Git repository.
During the initial configuration stage, SubGit will place sample credential helper script named
subgit/samples directory inside the Git repository. The script does not do much useful work, it just illustrates the “helper” concept and it’s as simple as:
#!/bin/sh echo username=svnUser echo password=svnPassword exit 0;
but it can be extended so that it provides real SVN username and password which SubGit will use to get authenticated to SVN server.
Chapter 2.6 Using SVN credentials cache.
Subversion has an ability to store a user’s name and password in cache to avoid requesting the credentials every time it access a repository: by default, whenever the SVN (especially native command-line) client successfully responds to a server’s authentication challenge, credentials are cached on disk and keyed on a combination of the server’s hostname, port, and authentication realm. SubGit, in turn, has an ability to use credentials SVN previously stored and thus avoid asking a user for the SVN repository account and password. The key settings to make SubGit able to use the cache are:
subversionConfigurationDirectory = PATH
useDefaultSubversionConfigurationDirectory = [true | false]
PATH represents a path that leads to any suitable Subversion configuration directory with cached credentials. The latter setting tells SubGit whether default Subversions configuration directory should be used. It worth to mention that the first one takes precedence of the second, that is if both settings are set only first one will be taken into account.
Default configuration directory location and that how credentials are being stored may depend on particular SVN client, but usually the clients stick to the following:
On Windows, the Subversion client stores passwords in the
%APPDATA%\Subversion\authdirectory. On Windows 2000 and later, the standard Windows cryptography services are used to encrypt the password on disk. Because the encryption key is managed by Windows and is tied to the user’s own login credentials, only the user can decrypt the cached password.
On Mac OS X, the Subversion client actually stores the credentials data in two locations: the authentication realm and username are being stored in the default Subversion’s directory
~/.subversion/auth/svn.simpleto be precise), while the password is being kept in the login keyring managed by the Keychain service, which is protected by the user’s account password. User preference settings can impose additional policies, such as requiring that the user’s account password to be entered each time the Subversion password is used.
For other Unix-like operating systems, no single standard “keychain” service exists, so by default the Subversion client stores the password unencrypted in the
~/.subversion/auth/caching area, asking the user for permission prior to doing so. It also can store passwords securely using the “GNOME Keyring”, “KDE Wallet”, and “GnuPG Agent” services. It worth to mention though, that at this moment SubGit supports only “GNOME Keyring”.
As an example, suppose you have a Linux workstation with no cached SVN credentials and you want to install SubGit to this workstation and make it uses cached login information to access the SVN repository. Since there is no credentials cache exists yet, the first step is to access the SVN repository with SVN client and provide valid username and password they to be stored in the cache. Almost any SVN command can be used here, e.g.
$ svn log -v -l 2 http://svn.example.com/svn/repository_1/project1 Authentication realm: <http://svn.example.com:80> Subversion Repository Password for 'user': ************ ----------------------------------------------------------------------- ATTENTION! Your password for authentication realm: <http://svn.example.com:80> Subversion Repository can only be stored to disk unencrypted! You are advised to configure your system so that Subversion can store passwords encrypted, if possible. See the documentation for details. You can avoid future appearances of this warning by setting the value of the 'store-plaintext-passwords' option to either 'yes' or 'no' in '/root/.subversion/servers'. ----------------------------------------------------------------------- Store password unencrypted (yes/no)? yes ------------------------------------------------------------------------ r202 | user | 2017-06-30 11:42:45 +0500 (Fri, 30 Jun 2017) | 1 line Changed paths: M /project1/trunk M /project1/trunk/source.txt minor changes ------------------------------------------------------------------------ r201 | I. Kh | 2017-06-30 11:41:18 +0500 (Fri, 30 Jun 2017) | 1 line Changed paths: M /project1/trunk M /project1/trunk/source.txt pre-rev-prop hook disabled ------------------------------------------------------------------------
Note, that the SVN client always asks for permission prior to store the password unencrypted. If permitted, it then stores the authentication data into hash-named text file in
$ ls -l ~/.subversion/auth/svn.simple total 4 -rw-r--r-- 1 user user 157 Jul 16 17:14 cdc0c76f1779d31e65924a4773e71d54 $ cat ~/.subversion/auth/svn.simple/cdc0c76f1779d31e65924a4773e71d54 K 8 passtype V 6 simple K 8 password V 12 Passw0rd K 15 svn:realmstring V 49 <http://svn.example.com:80> Subversion Repository K 8 username V 4 user END
Once the credentials are in the cache, the only thing left is to tell SubGit where the Subversion directory resides:
[auth "default"] subversionConfigurationDirectory = /home/user/.subversion #userName = #sshKeyFile = #sshKeyFilePassphrase = #password = #passwords = subgit/passwd #credentialHelper = #sslClientCertFile = #sslClientCertPassphrase =
And even better, SubGit always adds a path to the default Subversion configuration directory into its configuration file, so this step can be omitted in such case. That’s all, at this point, SubGit is able to obtain the SVN credentials from the SVN cache and thus is able to access the SVN repository.
Some additional configuration is needed in case if you intend to store password encrypted on Linux. By default, all the password stores are disabled in a Subversion configuration file:
[auth] ### Set password stores used by Subversion. They should be ### delimited by spaces or commas. The order of values determines ### the order in which password stores are used. ### Valid password stores: ### gnome-keyring (Unix-like systems) ### kwallet (Unix-like systems) ### gpg-agent (Unix-like systems) ### keychain (Mac OS X) ### windows-cryptoapi (Windows) # password-stores = gpg-agent,gnome-keyring,kwallet ### To disable all password stores, use an empty list: # password-stores =
which means none of them will be used. To enable a password store open the SVN configuration file
~/.subversion/config for editing, uncomment one of the
password-stores lines and set a list of the password stores you intend to use:
password-stores = gnome-keyring
In this case, we set SVN to use “GNOME Keyring” only. The next step is to access the SVN repository to store valid credentials:
$ svn log -v -l 2 http://svn.example.com/svn/repository_1/project1 Authentication realm: <http://svn.example.com:80> Subversion Repository Password for 'user': ************ r202 | user | 2017-06-30 11:42:45 +0500 (Fri, 30 Jun 2017) | 1 line Changed paths: M /project1/trunk M /project1/trunk/source.txt minor changes ------------------------------------------------------------------------ r201 | I. Kh | 2017-06-30 11:41:18 +0500 (Fri, 30 Jun 2017) | 1 line Changed paths: M /project1/trunk M /project1/trunk/source.txt pre-rev-prop hook disabled ------------------------------------------------------------------------
Note, that SVN doesn’t ask for permission this time. The authentication data is also being stored hash-named text file in
$ cat ~/.subversion/auth/svn.simple/cdc0c76f1779d31e65924a4773e71d54 K 8 passtype V 13 gnome-keyring K 15 svn:realmstring V 49 <http://svn.example.com:80> Subversion Repository K 8 username V 4 user END
excluding the password which is stored encrypted in the password keyring. The rest steps are basically the same as in the case of a unencrypted password. Once configured, SubGit will be able to access the SVN repository using authentication data from the SVN cache and the password stored in the keyring.
In fact, the same procedure works for MacOS X too. The only difference is that SVN uses ‘keychain’ to store the password with no additional configuration, so the password is stored encrypted by default. Thus, you just need to provide the SVN username and password once and then SubGit will be able to use cached SVN credentials and the password stored in ‘keychain’.
For Windows, all the steps are virtually the same, the main difference is that no password stores are used. Instead, SVN uses Windows CryptoAPI to encrypt the password and then writes down the resulting string right into the hash-named text file in the
> type %APPDATA%\Subversion\auth\svn.simple\cdc0c76f1779d31e65924a4773e71d54 K 8 passtype V 8 wincrypt K 8 password V 372 AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAboap9xzXTEKH5pqsLERrAwAAAAAyAAAAYQB1AHQAaABfAHMAdgBuAC4AcwBpAG0AcABsAGUALgB3AGkAbgBjAHIAeQBwAHQAAAAQZgAAAAEAACAAAABMoUB04Uh0Abm2 sXb1I4zspa3ZB2kv5TVywScvzCGm2QAAAAAOgAAAAAIAACAAAAC0Fc2mRCvN2maAlIxBfJhaGjmei13dpfExxiFPa8QBBxAAAABPl1s85G6/CczPABSfECbVQAAAAC2W/l+2bmITQtE6HEa7HRl/8cfBLln5Qtgp DhOHfJhtGPz+RZGehdsDavfCcjaMvP6Zyez+SYexIBNaZRx03EE= K 15 svn:realmstring V 49 <http://svn.example.com:80> Subversion Repository K 8 username V 4 user END
the only step needed is to set SubGit to use Subversion cache, and that’s all, SubGit will then be able to access the SVN repository with no additional requests.
In addition to username/password authentication data, Subversion is able to use SSL client certificate for authentication. A path to the PKCS#12 format client certificate file and its passphrase can be set in
~/.subversion/servers configuration file:
[global] # http-proxy-exceptions = *.exception.com, www.internal-site.org # http-proxy-host = defaultproxy.whatever.com # http-proxy-port = 7000 # http-proxy-username = defaultusername # http-proxy-password = defaultpassword # http-compression = no # http-auth-types = basic;digest;negotiate # No http-timeout, so just use the builtin default. # No neon-debug-mask, so neon debugging is disabled. # ssl-authority-files = /path/to/CAcert.pem;/path/to/CAcert2.pem # # Password / passphrase caching parameters: # store-passwords = no # store-plaintext-passwords = no # store-ssl-client-cert-pp = yes #store-ssl-client-cert-pp-plaintext = yes ssl-client-cert-file = /home/user/client.p12 ssl-client-cert-password = Passphr4se
SubGit, in turn, will be able to use that certificate with no additional configuration. Moreover, if the web server hosting a SVN repository requires both SSL client certificate and valid username and password, SubGit will be able to use both a certificate set in SVN
servers configuration file and cached credentials.