• Introduction
• Setup a Github repository
• Setup a Bitbucket repository
• Connect to a Github repository with a user and password
• Connect to a Bitbucket repository with a user and password
• Create an SSH key
• Connect to a Github repository using SSH
• Connect to a Bitbucket repository using SSH
• Authenticating with Team Foundation Server
• Authenticating with Azure DevOps (formally Visual Studio Team Services)
• More Information

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. Azure DevOps (formally 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.

If you have any questions please contact us at support@interfaceware.com

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" -m PEM

   Tip: Iguana requires PEM format keys. The ssh-keygen utility recently changed to using the (more secure) openssh private key format by default – whereas previously the default was PEM format. To generate PEM format we added the “-m PEM” option to the old command.

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" -m PEM

   Tip: Iguana requires PEM format keys. The ssh-keygen utility recently changed to using the (more secure) openssh private key format by default – whereas previously the default was PEM format. To generate PEM format we added the “-m PEM” option to the old command.

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.

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

Supported as of Iguana v6.1.1

You will need an SSH public and private key to communicate with git repos hosted on Azure DevOps. You can find links with more information about how to generate SHH keys in the Create an SSH key section.

1. Open up the web address for the collection hosted Team Foundation Server (can be found in the Team Foundation Server Admin Console).
2. Login using your Windows user credentials.
3. Navigate to the menu bar at the top, and go to security as shown below.
   
4. Click on “SSH public keys”, then “Add”.
   
5. Enter a proper description for your key, then paste in the contents of your public key into the Key Data box and click save. 
6. When adding the Team Foundation Server hosted repo into Iguana, there is one extra step that will need to be done compared to adding a cloud based repository over SSH. Navigate to the “Add/Configure Repositories” section in Iguana and click “New Repository”.
7. Name the repository then select SSH for the protocol and enter the repo SSH URL and private key path. The SSH URL and private key path are familiar if you have ever added a remote SSH repository to Iguana, but as of v6.1.1 there is now a SSH username input. You will need to enter your Windows username that is associated with the account used on Team Foundation Server (the one you logged in with to add the public key).
   
8. This is required for Team Foundation Server repositories and any other hosted repositories that don’t format the SSH URL in such a way that the username can’t be pulled from it. Once you have entered the username click “Save Repository” to add it to Iguana. At this point if the inputs are all correct you should be able to import/export to the repo.

Authenticating with Azure DevOps (formally Visual Studio Team Services) [top]

Authenticating with a username and password

In order to access repositories hosted on Azure DevOps 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 Azure DevOps 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 Azure DevOps 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

Supported as of Iguana v6.1.1

You will need an SSH public and private key to communicate with git repos hosted on Azure DevOps. You can find links with more information about how to generate SHH keys in the Create an SSH key section.

1. Similarly to authenticating with a username and password, once you create your project you can navigate to the main project page and click on the SSH button to display the git ssh path to the repo, as well as a link to “Manage SSH Keys” as shown below. (alternatively you can click on your username in the main menubar and go to “security”.
2. Once on the security page click “SSH public keys”, then click “Add”.
   
3. Enter a proper description for your key, then paste in the contents of your public key into the Key Data box, like you would do for many of the other git cloud providers.
4. If you configure Iguana to use the hosted repo over SSH using the matching private key file, you will now be able to export/import channels to/from the Azure DevOps repo.

More Information [top]

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

• Github: Generating a new SSH key
• Bitbucket: Set up SSH for Git