Table of Contents |
---|
SubGit, like any other Subversion client, can access a Subversion repository [auth "default"]by using one of the following protocols.
Table 1. Subversion repository access protocols
...
file://
...
svn://
...
svn+ssh://
...
http(s)://
...
All the other access methods to a Subversion repository require the appropriate authentication settings for SubGit.
Obtaining the authentication data for a Subversion repository
SubGit obtains the authentication data from the [auth default] section of the SubGit configuration file that is located at GIT_REPO/subgit/config.
Depending on the configuration, your Subversion server can request the following authentication data to log in to a Subversion repository:
- a username and a password
- an SSL client certificate
- an SSH private key
In the [auth "default"] section of the SubGit configuration file, you can specify the authentication settings depending on the authentication data that is required to log in to a Subversion repository.
...
You can specify credentials to log in to a Subversion repository in the following settings:
Code Block |
---|
[auth "default"]
userName =
password =
passwords =
credentialHelper =
subversionConfigurationDirectory =
useDefaultSubversionConfigurationDirectory = |
SubGit refers to these settings in the sequence presented below. If some setting is not specified or the credentials fetched from the setting are not valid, SubGit refers to the next one until it is able to log in to a Subversion repository.
- The
userName
andpassword
settings. - The
passwords
setting that refers to the passwords file for a username-password pair. - A credential helper program.
- Subversion credentials cache from the Subversion client configuration directory.
If none of the settings is specified or fetched credentials are not valid, SubGit reports the authentication error.
The userName
and password settings
The userName
and password
settings specify a username and a password to access a Subversion repository.
Note |
---|
The password is stored as plain text. For security reason, it is recommended to limit the access to the SubGit configuration file. |
The passwords setting
The passwords
setting defines a path to the passwords file that can contain the list of username-password pairs to log in to a Subversion repository. The path can be either absolute or relative to the Git repository.
The default value:
Code Block |
---|
[auth "default"]
passwords = subgit/passwd |
The default password file is located in the subgit directory within a Git repository. In this file, you can specify the list of username-password pairs as plain text in the following format:
Code Block |
---|
svnUserName svnUserPassword |
The credentials from the passwords file may be used for mapping Git authors to Subversion revision authors when you translate Git commits to Subversion revisions. For the mapping purpose, you can specify the list of available usernames and passwords in the passwords file, though it is not obligatory. For more information on authors mapping, refer to the Authors Mapping section.
Tip |
---|
When you have several Git repositories mapped from the same Subversion repository, you can log in to this Subversion repository using a single passwords file. |
Using credential helper programs
SubGit supports credential helper programs to obtain the authentication data to log in to a Subversion repository. A credential helper program is a script that fetches credentials from the external sources, for example, from LDAP catalogs, authentication servers or databases.
To enable a credential helper program, specify the following setting:
Code Block |
---|
[auth "default"]
credentialHelper = PATH [args] |
The credentialHelper
setting defines a path to a credential helper program and its optional arguments. The path can be either absolute or relative to the Git repository.
The initial SubGit configuration places the sample credential helper script (the credentialHelper.sh
file) to the subgit/samples
directory in the Git repository.
The initial script contains the following:
Code Block |
---|
#!/bin/sh
echo username=svnUser
echo password=svnPassword
exit 0; |
You can configure this script to fetch the credentials from some external source to log in to a Subversion repository. Use the standard Git credential helper input/output format with the exception that the command name is not required.
Input:
Code Block |
---|
url = SVN_URL
protocol = SVN_URL_PROTOCOL
path = SVN_URL_PATH
username = PREFFERED_SVN_USER_NAME |
Output:
Code Block |
---|
username = SVN_USER_NAME
password = SVN_PASSWORD |
...
SubGit can refer to the Subversion credentials cache to log in to a Subversion repository.
To enable the authentication with Subversion credentials cache, specify the following settings:
Code Block |
---|
[auth "default"]
subversionConfigurationDirectory = PATH
useDefaultSubversionConfigurationDirectory = [true | false] |
...
The useDefaultSubversionConfigurationDirectory
setting specifies whether SubGit will use the default Subversion configuration directory to obtain the authentication data or not.
Info |
---|
The 1st setting takes priority over the 2nd. If the path to the appropriate Subversion directory with caсhed credentials is specified, SubGit refers to it and ignores the default Subversion configuration directory. |
...
- On Windows
Subversion clients store encrypted passwords in the %APPDATA%\Subversion\auth\svn.simple
directory. Passwords are encrypted by the standard Windows cryptographic services.
- On Mac OS X
...
- On Unix-like operating systems
By default, Subversion clients ask permission to store unencrypted passwords in the ~/.subversion/auth/svn.simpl
e directory. The secure storage can be provided by the GNOME Keyring, KDE Wallet or GnuPG Agent services.
Note |
---|
Currently, SubGit supports only GNOME Keyring. |
The example below shows how to use the Subversion credentials cache with encrypted passwords on Linux.
Example: Use of credentials cache with encrypted passwords on Linux
All the passwords stores are disabled in the Subversion configuration file:
Code Block |
---|
[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 = |
...
To enable a password store, in the Subversion configuration file, uncomment a password-stores line and specify the store that you want to enable.
Note |
---|
Currently, SubGit supports only GNOME Keyring. |
For example, password-stores = gnome-keyring
...
SubGit can use the credentials cache from this directory to log in to a Subversion repository.
Using the SSL client certificate authentication
If you want to use the SSL client certificate authentication to access a Subversion repository, specify the following settings:
Code Block |
---|
[auth "default"]
sslClientCertFile = PATH
sslClientCertPassphrase = passphrase |
The sslClientCertFile
setting defines a path to the SSL client certificate file in PKSC#12 format. The path can be either absolute or relative to the Git repository.
The sslClientCertPassphrase
setting specifies a passphrase that can be optionally used to protect the SSL certificate.
A web server that hosts a Subversion repository can be configured to request a username and password after the authentication with an SSL client certificate. For the information on the settings that you can use to specify a username and password, see the Specifying a username Specifying a username and a password section.
The other way to specify a path to an SSL client certificate and an optional passphrase is the the Subversion servers file that is located in the default Subversion configuration directory.
Code Block |
---|
[global]
ssl-client-cert-file = PATH
ssl-client-cert-password = passphrase |
In this case, no additional settings are required in the [auth "default"] section of the SubGit configuration file. SubGit refers to the servers file for an SSL certificate to log in to a Subversion repository.
If a web server that hosts a Subversion repository along with an SSL client certificate requires a username and a password for authentication, SubGit refers to the servers configuration file for an SSL certificate and uses the Subversion credentials cache to log in to a Subversion repository. To specify the settings that fetch the Subversion credentials cache, see the Using the Subversion credentials cache section.
Using the SSH key-based authentication
If you want to use the SSH key-based authentication to access a Subversion repository, specify the following authentication settings:
Code Block |
---|
[auth "default"]
sshKeyFile = PATH
sshKeyFilePassphrase = passphrase |
The sshKeyFile
setting defines a path to the file that contains the SSH private key to log in to a Subversion repository. The path can be either absolute or relative to the Git repository.
Note |
---|
Make sure that a SubGit user is granted the reading permissions for an SSH private key file. |
The sshKeyFilePassphrase
setting specifies a passphrase that can be optionally used to protect the SSH private key.
SubGit also requires a Subversion username when using the SSH key-based authentication. In this case, the username can be specified in one of the following settings:
Code Block |
---|
[auth "default"]
userName = user |
...
Children Display |
---|