SCMs typically support simple username and password combinations for authentication. However, in Fisheye and Crucible, more complex authentication methods are supported for the following repository types:

• Mercurial
• Git

The configuration of these authentication methods in Fisheye is described below. Note, the authentication method can also be configured as part of a particular repository's definition.

Although Subversion supports more complex authentication methods like ssh and ssl certificate authentication, these are not currently configurable in Fisheye. When using the bundled svnkit library, these are typically configured using Java property definitions.

On this page:

Authentication methods

The authentication methods are configured as part of a particular repository definition.

There are four authentication methods for a repository:

• No authentication — Used where no authentication is required to access a repository.
• Generate key pair for SSH — A SSH key is generated and managed by Fisheye to access the repository.
• Upload private key for SSH — A SSH key is created and managed externally to Fisheye.
• Password for http(s) — This is for the username / password method of authentication with http and https URLs (also known as basic-auth).

When a Fisheye repository type supports these authentication methods, you will see an Authentication section during repository configuration (e.g. the "Mercurial Authentication" section in the screenshot below). This section will be available when initially defining a repository configuration and also in the "SCM Details" section when maintaining a repository.

Screenshot: Selecting an authentication method

No authentication

This is the simplest authentication method. It means that Fisheye can connect to the repository using Git or Mercurial without any credentials or authentication. If you have supplied credentials via another mechanism (such as ssh-agent or a default passphrase-less private key for a ssh connection) Git or Mercurial will use this automatically.

This option is appropriate for,

1. public repositories which grant read-only access to anonymous users, or
2. internal repositories on a secure network which allow anonymous reads to network users, or
3. repositories which are accessible to the Fisheye server on the local filesystem.

Screenshot: 'No authentication' selected for a local repository

Fisheye's access to repositories is always read-only, so it can easily be used with repositories which only require authentication and authorization for write operations.

• If you specify No authentication but enter a repository URL which includes a username and password, Fisheye will remove the password from the URL and set the authentication method to Password, storing the password specified in the password field.

Generate key pair for SSH

If you want to control repository access using SSH keys, you can choose this method of authentication to have Fisheye generate and manage the public/private key pair for you. This is the most secure option for ssh access, as the private key is never transmitted across the network.

Click Generate to generate the key pair (see "Generating a SSH key pair" screenshot below). Fisheye will generate and store the public and private key pair. The key is specific to the repository being indexed.

Screenshot: Generating a SSH key pair

The public key will be displayed to allow you to copy it to your repository server and to associate the key with your user account (see "Public Key of Generated Key displayed" screenshot below). The private key is stored by Fisheye and never exposed to users or administrators.

Screenshot: Public key of generated key displayed

If you wish to change the key, click Remove and then generate a new key.

When using SSH keys, you will typically specify a username as part of the URL you use to access the repository.

Public hosting systems such as Bitbucket and GitHub provide simple web-based mechanisms for associating public keys with your account. For these systems, a generic username is used in the repository URL and it is the key that determines the account. See the screenshots below for examples of how to associate keys with Bitbucket and GitHub accounts.

Screenshot: Key management on Bitbucket

Screenshot: Key management on GitHub

Upload private key for SSH

If you are using SSH keys for repository access and already have an SSH key or you would prefer to manage your SSH keys yourself, this authentication method allows you to upload the private key to Fisheye. Please note however, that Fisheye can only use passphrase-less SSH keys. (To vote for support for private keys with passphrases, see http://jira.atlassian.com/browse/CRUC-5579.)

The private key is uploaded by your web browser file upload operation. As soon as Fisheye completes the file upload, it verifies that the provided key is in fact a valid private SSH key and that it does not have a passphrase. To change the stored key, remove the current key by clicking Remove, and then upload the new key.

Screenshot: Private key upload

Tip: If you are uploading under OSX and using 10.6 or later, you can press command-shift-period to display hidden files and directories. This makes it easier to access ssh key files stored in their default .ssh directory

Password

This authentication method is used when using http/https to access your repository with a username and password. For these repositories, the repository location URL includes the username for the account and the password is configured in the Password field (see "Password authentication" screenshot below).

Screenshot: Password authentication

It is possible to specify both the username and password in a repository URL. If you do this Fisheye will warn you to remove the password from the URL definition, as it would conflict with the password specified in the password field. When using password authentication, Fisheye will always manage the password separately from the repository URL.

Screenshot: Do not provide password in URL

 

Notes

Security considerations when using SSH key pairs

The Generate key pair for SSH option is the safest option to use, as private keys are never transmitted across the network. If an attacker gains access to your private key, they have access to all the services that are allowed by that key pair.

Since Fisheye only requires read access to your accounts, it is best to create a user that only has read access to the repositories you want to index and add the public key to that user's account settings. This way, even if the private key is compromised, while your source can be accessed, you can easily revoke that user's access and/or remove their public keys and the attacker will not be able to change or modify any of your data.

Using ssh-agent

If you are using a Unix-style system with SSH key authentication and do not want to perform key management in Fisheye at all, it is possible to launch Fisheye in the context of an ssh-agent process. When Fisheye launches sub-processes to interact with the repository, the ssh command in those sub-processes will inherit access to the ssh keys in the ssh-agent process. This approach would allow you to use ssh keys with passphrases. Please refer to your operating system documentation for more information on ssh-agent.

SSH connectivity tools under Windows

If your Fisheye installation is using Windows, you must use OpenSSH for SSH connectivity, rather than alternatives like TortoiseHg or Putty.

Download and install Git for Windows, as this includes OpenSSH. Be careful about the options you choose during the install:

• When asked how to adjust your PATH environment, select the option 'Run Git and included Unix tool from the Windows Command prompt'. This will ensure that Git and its associated tools (including OPENSSH) are available to the Fisheye server via the PATH environment variable.
• When asked for the SSH executable, select the option 'Use OpenSSH'. The Fisheye server doesn't work with alternatives like TortoiseHg or Putty.

How SSH works in Fisheye

Fisheye does not bundle any SSH clients and instead relies on what is available in your server infrastructure. For Unix-based systems, this is typically in the form of OpenSSH. When Fisheye attempts to connect to a repository, such as through a Bitbucket Server application link, it uses SSH to do so. Below are the steps that occur to identify and execute an SSH connection:

1. The connection is initiated to connect with repository using SSH.
2. Fisheye checks to see if SSH_EXEC environment variable is set on the server.
3. If SSH_EXEC is NOT set then it checks to see if the JVM argument -Dssh.exe is set.
4. If JVM argument -Dssh.exe is NOT set, it searches for SSH/SSH.exe on PATH.
5. If SSH is found on the PATH, then it resolves the canonical path for SSH.
6. Fisheye then sets SSH_EXEC environment variable with the canonical path it just resolved.

Using Centrify SSH

As noted, OpenSSH is in the default library used for SSH on Unix based systems. (For Windows, see below “SSH connectivity tools under Windows")

To run Fisheye with Centrify SSH, you will likely need to set the JVM argument -Dssh.exe to the path for SSH:

1. Set environment variable FISHEYE_OPTS with value

   -Dssh.exe=/path/to/ssh 
   

2. Restart the application.
3. Navigate to Administration > Sys Info/Support > System Info and check the output under JVM Input Arguments to verify the argument has been set.

 There is a known issue with running Centrify OpenSSH commands. Please review the Centrify KB article on how to deal with the execution of Centrify SSH.