Repository Authentication

Introduction

This article explains how to authenticate with two of the most popular cloud based Git hosting services Github and Bitbucket.

There are two methods:

  1. User and password: This is the simplest to set up, but it has the disadvantage that you will have to reenter your user name and password on a regular basis.
  2. Using SSH: This is more complicated to set up, but it has the advantage that it works seamlessly (you never have to enter your username and password).

The procedures should be very similar with hosted Git accounts from other suppliers such as Gitlab.

The article also describes how to authenticate with the following Microsoft based Git services:

  1. Team Foundation Server (On-premise)
  2. Visual Studio Team Services (Cloud Based)

Authenticating with these services is done slightly differently than Bitbucket/Github and requires some extra steps. Unfortunately at this time only username/password based authentication is supported.

Setup a Github repository [top]

  1. Create a Github account if you don’t have one.
  2. Log into your Github account.
  3. Click the + New repository button to create a repository:
  4. Choose the Owner, we chose to use the organization your-organization (rather than the account owner).
    Note: you can add organizations from the Github settings menu.
  5. Enter a Name for the repository, we used your-public-git-repo.
  6. Optionally enter a Description.
  7. If you have a paid account you can create a Private repository, in this case we chose Public.
  8. Click the green Create repository button.
  9. Your new repository will look similar to this:
    Note: This repository is empty which is exactly what we want for working with Iguana.
  10. Change to the settings tab, notice that the Restrict editing to users in teams with push access only is checked, this means that you have to supply a Username and Password or use an SSH Key to be able to write to this repository (if you uncheck this option then anyone can write to the repository).

Setup a Bitbucket repository [top]

  1. Create a Bitbucket account if you don’t have one.
  2. Log into your Bitbucket account.
  3. Choose Create repository from the Repositories menu to create a repository:
  4. Choose the Owner, we chose to use the user julianmuir (usually we would have chosen the interfaceware team).
    Note: you can add teams from the Teams menu.
  5. Enter a Name for the repository, we used your-bitbucket-repo.
  6. Check Access Level – This is a private repository
    Note: You can create a private repository for paid accounts, or for free accounts with up to 5 users.
  7. Select Repository type – Git.
  8. Click the blue Create repository button.
  9. Your new repository will look similar to this:
    Note: This repository is empty which is exactly what we want for working with Iguana.
  10. This repository is private so you will have to supply a Username and Password or use an SSH Key to be able to write to it (or to read it).

Connect to a Github repository with a user and password [top]

  1. Follow the procedure to add a new repository.
  2. Choose HTTPS and enter the HTTPS URL for your Github repository:
  3. Save the repository.
  4. Follow the Export Channels procedure and export one or more channels to the repository you just created.
  5. You will be prompted to enter the Username and Password for your Git repository:

Connect to a Bitbucket repository with a user and password [top]

  1. Follow the procedure to add a new repository.
  2. Choose HTTPS and enter the HTTPS URL for your Bitbucket repository:
  3. Save the repository.
  4. Follow the Export Channels procedure and export one or more channels to the repository you just created.
  5. You will be prompted to enter the Username and Password for your Bitbucket repository:

Create an SSH key [top]

We demonstrate how to use the ssh-keygen utility to create a public private key pair. The ssh-keygen utility is a standard component of the Secure Shell (SSH) found on Mac and Linux machines. However ssh-keygen is generally not installed on Windows, we suggest installing Git which includes SSH (though there are other ways like installing cygwin etc).

For Windows:

If you do not wish to install Git on your Windows computer, you can use PuTTYgen to create keys instead.

  1. Install Git (which includes ssh-keygen):
    • Choose the “Run Git from the Windows Command Prompt” option when using the installer.
      Note: This simply adds the Git install directory to your Windows PATH variable.
    • Alternatively append the Git install directory to your Windows PATH variable.
  2. Open a Command Prompt window.
  3. Run this command to generate an SSH private key (using your email as a comment):
    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
  4. When prompted enter a filename like /C/Users/<your user name>/.ssh/<private key>.pem, and press Enter.
    Note: You can actually store the key file anywhere and use any filename (with or without an extension).
  5. When prompted to enter a passphrase, do not enter any text just press Enter twice.
    Note: Iguana only accepts keys without a passphrase (password).
  6. This will create a public and private key pair, something like this:

For Mac or Linux:

  1. Open a Terminal window.
  2. Run this command to generate an SSH private key (using your email as a comment):
    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
  3. When prompted enter a filename like /Users/<your user name>/.ssh/<private key>.pem, and press Enter.
    Note: You can actually store the key file anywhere and use any filename (with or without an extension).
  4. When prompted to enter a passphrase, do not enter any text just press the Enter key twice.
    Note: Iguana only accepts keys without a passphrase (password).
  5. This will create a public and private key pair, something like this:

Connect to a Github repository using SSH [top]

  1. Follow the procedure to add a new repository.
  2. Get your Github SSH URL:
  3. Choose SSH and enter the SSH URL for your Github repository:

    The alternate format for the SSH URL also works:
  4. Browse to choose your SSH private key:
  5. Click Save Repository.
  6. Log into you Github account.
  7. Go to Settings>SSH keys: https://github.com/settings/keys.
  8. Add the corresponding public key to your account:
    • Click the New SSH key button.
    • Enter a Title for the key, we used “my-private-key” (the same as the file name).
    • Open the “.pub” file corresponding to your private key, and copy the contents.
    • Paste the corresponding OpenSSH formatted private key into the Key field.
      Note: The OpenSSH format key starts with “ssh-rsa” (PKCS format starting with “–––––BEGIN PUBLIC” does not work).

      • If you used ssh-keygen then open the “.pub” file corresponding to your private key, and copy the contents, in this case my-private-key.pem.pub:
      • Alternatively if you are using PuTTYgen to create keys you must copy the Public key for pasting into OpenSHH authorized_keys file: field:
    • Then press the green Add SSH key button:
  9. Your newly added key will look similar to this:
  10. Follow the Export Channels procedure and export one or more channels to the repository you just created.
  11. The export will work seamlessly, you will not be prompted to enter a Username and Password.

Connect to a Bitbucket repository using SSH [top]

  1. Follow the procedure to add a new repository.
  2. Get your Bitbucket SSH URL:
    • Click Clone and copy the clone command:
    • Remove “git-clone ” from the start of the command git clone git@bitbucket.org:julianmuir/your-bitbucket-repo.git to get the SSH URL.
  3. Choose SSH and enter the SSH URL for your Bitbucket repository:

    The alternate format for the SSH URL also works:
  4. Browse to choose your SSH private key:
  5. Click Save Repository.
  6. At the top right of the Bitbucket screen choose avatar > Bitbucket settings:
  7. Choose Security>SSH keys from the menu on the left.
  8. Add the corresponding public key to your account:
    • Click the Add key button.
    • Enter a Label for the key, we used “my-private-key” (the same as the file name).
    • Open the “.pub” file corresponding to your private key, and copy the contents.
    • Paste the corresponding OpenSSH formatted private key into the Key field.
      Note: The OpenSSH format key starts with “ssh-rsa” (PKCS format starting with “–––––BEGIN PUBLIC” does not work).

      • If you used ssh-keygen then open the “.pub” file corresponding to your private key, and copy the contents, in this case my-private-key.pem.pub:
      • Alternatively if you are using PuTTYgen to create keys you must copy the Public key for pasting into OpenSHH authorized_keys file: field:
    • Then press the blue Add key button:
  9. Your newly added key will look similar to this:
  10. Follow the Export Channels procedure and export one or more channels to the repository you just created.
  11. The export will work seamlessly, you will not be prompted to enter a Username and Password.

Authenticating with Team Foundation Server [top]

Authenticating with a username and password

Out of the box, TFS does not support authentication over HTTP(S) with a username and password.

The default authentication protocol over HTTP(S) is the Windows based NTLM. This authentication protocol is not supported currently in our source control stack, as support for NTLM has not been added for Unixy platforms.
When using Team Foundation Server in this way it is highly recommended to setup SSL certificates on your server and turn on HTTPS instead of using plain HTTP. If you don’t your credentials will be transmitted in plain text and are vulnerable to being compromised. (an example of how to go about setting this up can be found from popular certificate authority Digicert here)
In order to authenticate with your username/password over http(s) you will need to enable the basic authentication protocol on your team foundation server installation using the following steps:
  1. Team Foundation Server needs to be installed, and your project collection has to be setup via the Team Foundation Server Admin Console (see here for help with this).
  2. You will now have to enable basic authentication via IIS (Internet Information Services) Manager. Navigate to your programs list in Windows and open it.
  3. On the side panel you will see your servers and the sites running on them. Navigate to the Team Foundation Server site and click on it:
  4. Select the authentication icon, then find basic authentication in the list, right click on it and select enable:
  5. Only perform this step if basic authentication isn’t present in the list described above, if it is there then skip to step 6.
    1. You will need to install the basic authentication package for IIS. From you Windows program list, open up “Server Manager”.
    2. In Server Manager, navigate to the top right menubar and go to “Manage > Add Roles and Features”.
    3. Click next in the Wizard and then Select “Role-based or Feature-based installation” then click next again.
    4. Select your server that TFS is running on from the list, then click next again.
    5. Scroll down in the list until you find “Basic Authentication” then select it and click next to install it.
    6. It should now be available as an authentication option within IIS.
  6. Similar to step 3, on the side panel now navigate to the Team Foundation Server virtual folder within the site as shown below. Select the authentication icon again, then enable basic authentication from the list like we did for the top level site:
  7. At this point you should be able to access the repo hosted on the collection over http(s) using your windows username/password in Iguana. If logging in as a local user you will be able to enter your username as “DOMAIN\USER” or “USER” in the Iguana prompt and it should work. If logging in using a domain user account, then you may have to use “DOMAIN\USER”.
  8. Adding the repo into Iguana is the same as adding any other repo described above when using a username and password. Make sure you are specifying the correct address of your on-premise server and using the right IP/domain name.

Authenticating over SSH

Unfortunately SSH based authentication is not yet supported for Team Foundation Server.

Authenticating with Visual Studio Team Services [top]

Authenticating with a username and password

In order to access repositories hosted on VSTS from Iguana, you will have to generate and enable alternative git credentials. Microsoft unfortunately does not allow you to use your standard Windows account credentials that are used to login to VSTS itself. Follow the steps below to set this up:

  1. Once you have created your project (see here for more info ), click on the project to navigate to the main project page as seen below:
  2. As shown below, click on “Generate Git Credentials” and enter alternative credentials for your user and click save.
  3. These credentials will now be accessible on your VSTS user settings page. Click on your user icon in the top right corner and go to your user settings page. As you will see, your alternative credentials are now created and enabled.
  4. If you configure Iguana to use the hosted repo over http(s), these will be the credentials you will enter to access it when prompted. The repo will be added into Iguana just like any other repo authenticating over http(s).

Authenticating over SSH

Unfortunately SSH based authentication is not yet supported for Visual Studio Team Services.

More Information [top]

Note: Iguana keys do not use a passphrase (password) so just ignore the ssh-agent instructions (ssh-agent is only used to store a passphrase).

 

Please don't hesitate to take anonymous feedback survey or leave us a comment.

Leave A Comment?