You can use either secure hypertext transport protocol (HTTPS) or secure shell (SSH) to connect to Bitbucket. HTTPS requires you to enter a username/password each time you connect to the Bitbucket server, for example, when you push your changes. HTTPS is suitable for situations where you work with Bitbucket infrequently and make few code changes. However, if you do most of your coding with a Bitbucket hosted repository, you'll want to set up a SSH connection. After you configure SSH, Bitbucket no longer requires you to authenticate each remote communication with a username/password combination. This page contains the following topics:
How SSH and Bitbucket work together
To use SSH with Bitbucket, you create an SSH identity. An identity consists of a private and a public key which together are a key pair. The private key resides on your local computer and the public you upload to your Bitbucket account. Once you upload a public key to your account, you can use SSH to connect with repositories you own and repositories owned by others, provided those other owners give your account permissions. By setting up SSH between your local system and the Bitbucket server, your system uses the key pair to automate authentication; you won't need to enter your password each time you interact with your Bitbucket repository.
There are a few important concepts you need when working with SSH identities and Bitbucket.
- You cannot reuse an identity's public key across accounts. If you have multiple Bitbucket accounts, you must create multiple identities and upload their corresponding public keys to each individual account.
- You can associate multiple identities with a Bitbucket account. You would create multiple identities for the same account if, for example, you access a repository from a work computer and a home computer. You might create multiple identities if you wanted to execute DVCS actions on a repository with a script – the script would use a public key with an empty passphrase, allowing it to run without human intervention.
RSA (R. Rivest, A. Shamir, L. Adleman are the originators) and digital signature algorithm (DSA) are key encryption algorithms. Bitbucket supports both types of algorithms. You should create identities using whichever encryption method is most comfortable and available to you.
If you have multiple identities, you'll need a SSH authentication agent program on your local system. This program runs in the background. You load all your keys into the agent and it manages the authentication for you. In a Windows environment, a common authentication agent is Pageant. In Mac OSX and Linux systems,
ssh-agent is more common.
Deciding if you need a single or multiple identities
You only have to create two identities (keys) if you have two different Bitbucket accounts. The typical use case is the programmer who has a work-related Bitbucket account and a personal Bitbucket account. Each account must have its own SSH key.
SSH keys give you identity-based authentication. This means you can use the same identity from as many different systems as you like and connect to as many services with that identity. Whether you should do this depends on how security conscious you are or need to be.
You should definitely have separate private keys per origin. That means there is a single copy of each private key (not counting backups). It's ok to use the same private key between closely related machines, such as situations in which where breaking into one machine basically gives you access to the other (for example if they're in each other's shosts.equiv). Don't use the same private key to log in from different networks (e.g. home and work), never share a private key between two users, and never share a private key between a laptop and any other machine.
If you aren't concerned about securing an identity, you can copy your identity to multiple machines. If you are concerned, or if you have multiple Bitbucket accounts, you should create multiple identities.
Single or multiple identity setup
The Bitbucket 101 shows you how to setup and use a single default identity with Bitbucket. If you have completed the 101, much of what you have read so far may seem familiar. If you have not completed the 101, you should at least work through the sections on SSH. These sections are:
The following pages provide information on configuring multiple identities:
- Configure multiple SSH identities for GitBash, Mac OSX, & Linux
- Configure multiple SSH identities for TortoiseHg
Repository URL formats by connection protocol
The URL you use to access a repository depends on the connection protocol (HTTPS or SSH) and the DVCS program. The following table shows the URL format for each case Bitbucket supports:
|SSH URL format||HTTPS URL format|
In the SSH format, the
accountname appears after
firstname.lastname@example.org. In HTTPS format, the
Bitbucket displays repository-specific URLs for both Git and Mercurial on your repository Overview page.
Known host or Bitbucket's public key fingerprints
Each server that allows connection over the SSH provides its own public key to the connecting client. SSH stores the key in a known hosts list. In Mac OSX and Linux this list is in a
~/.ssh/known_hosts file. On Windows, PuTTYgen stores the information in the
HKEY_CURRENT_USER\SoftWare\SimonTatham\PuTTY\SshHostKeys registry key. Each time your client reconnects SSH checks the server's identity against your known hosts just as the host is checking your identity. This two-way mechanism prevents man-in-the-middle attacks.
Bitbucket hosts only allow Git and Mercurial to make SSH connections. The first time you access Bitbucket using the SSH URL, your SSH client checks to see if the Bitbucket host is a known host. If the host is not in your
~/.ssh/known_hosts file SSH warns you that it is adding the Bitbucket host to known hosts:
If you view the contents of known hosts is stored you find the actual key is stored in a base64 encoded format:
Technically, you should record the server's public host key before connecting to it for the first time. Depending on the security protocols in your network, the system administrator may maintain a centrally located list of approved known hosts. The public key fingerprints for the Bitbucket server are:
To get the format suitable for storage in the known hosts, you can use the following
SSH on Port 443
Some network administrators block outgoing SSH connections on port 22. If your network blocks this port, Bitbucket provides an alternate hostname and port combination you can use. The host
altssh.bitbucket.org supports SSH over port 443. Port 443 is typically used for HTTPS and administrator typically leave it open for outbound web browsing. If you are blocked, you can use these URLs.
|Alternate SSH URL format|