git-workshop/AZURE-DEVOPS-SSH-SETUP.md

Azure DevOps SSH Setup - Best Practices Guide

This guide provides comprehensive instructions for setting up SSH authentication with Azure DevOps. SSH is the recommended authentication method for secure Git operations.

Why SSH is Best Practice

SSH (Secure Shell) keys provide a secure way to authenticate with Azure DevOps without exposing passwords or tokens. Here's why SSH is the security best practice:

Security Benefits:

• No Password Exposure: Your credentials never travel over the network
• Strong Encryption: Uses RSA cryptographic algorithms
• No Credential Prompts: Seamless authentication after initial setup
• Better for Automation: Scripts and CI/CD pipelines benefit from passwordless authentication
• Revocable: Individual keys can be removed without changing passwords
• Auditable: Track which key was used for each operation

Comparison with HTTPS/PAT:

• HTTPS with Personal Access Tokens (PAT) requires storing tokens, which can be accidentally committed to repositories
• SSH keys separate your authentication (private key stays on your machine) from the service
• SSH connections are faster after initial setup (no token validation on every request)

---

Prerequisites

Before starting, ensure you have:

• Git 2.23 or higher installed

  git --version
  

• Azure DevOps account with access to your organization/project

  • If you don't have one, create a free account at dev.azure.com

• PowerShell 7+ or Bash terminal for running commands

  pwsh --version
  

---

Step 1: Generate SSH Key Pair

SSH authentication uses a key pair: a private key (stays on your computer) and a public key (uploaded to Azure DevOps).

Generate RSA Key

Open your terminal and run:

ssh-keygen -t rsa -b 4096 -C "your.email@example.com"

Important notes:

• Replace your.email@example.com with your actual email address
• The -C flag adds a comment to help identify the key later
• The -b 4096 flag specifies a 4096-bit key size for enhanced security

Note about RSA: Azure DevOps currently only supports RSA SSH keys. While newer algorithms like Ed25519 offer better security and performance, they are not yet supported by Azure DevOps. See the note at the end of this guide for more information.

Save Location

When prompted for the file location, press Enter to accept the default:

Enter file in which to save the key (/Users/yourname/.ssh/id_rsa):

Default locations:

• Linux/Mac: ~/.ssh/id_rsa
• Windows: C:\Users\YourName\.ssh\id_rsa

Passphrase (Optional but Recommended)

You'll be prompted to enter a passphrase, just press Enter no password is needed:

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

Passphrase pros and cons:

• With passphrase: Extra security layer - even if someone steals your private key, they can't use it without the passphrase
• Without passphrase: More convenient - no prompt when pushing/pulling (but less secure if your machine is compromised)

Recommendation: Use a passphrase, especially on laptops or shared machines.

Verify Key Generation

Check that your keys were created:

Linux/Mac: Windows PowerShell:

dir $HOME\.ssh\

You should see two files:

• id_rsa - Private key (NEVER share this)
• id_rsa.pub - Public key (safe to share)

---

Step 2: Add SSH Public Key to Azure DevOps

Now you'll upload your public key to Azure DevOps.

Navigate to SSH Public Keys Settings

1. Sign in to Azure DevOps at https://dev.azure.com
2. Click your profile icon in the top-right corner
3. Select User settings from the dropdown menu
4. Click SSH Public Keys

Navigate to your user settings by clicking the profile icon in the top-right corner

Add New SSH Key

5. Click the + New Key button

Click '+ New Key' to begin adding your SSH public key

Copy Your Public Key

Open your terminal and display your public key:

Linux/Mac:

cat ~/.ssh/id_rsa.pub

Windows PowerShell:

type $HOME\.ssh\id_rsa.pub

Windows Command Prompt:

type %USERPROFILE%\.ssh\id_rsa.pub

The output will look like this:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC2YbXnrSK5TTflZSwUv9KUedvI4p3JJ4dHgwp/SeJGqMNWnOMDbzQQzYT7E39w9Q8ItrdWsK4vRLGY2B1rQ+BpS6nn4KhTanMXLTaUFDlg6I1Yn5S3cTTe8dMAoa14j3CZfoSoRRgK8E+ktNb0o0nBMuZJlLkgEtPIz28fwU1vcHoSK7jFp5KL0pjf37RYZeHkbpI7hdCG2qHtdrC35gzdirYPJOekErF5VFRrLZaIRSSsX0V4XzwY2k1hxM037o/h6qcTLWfi5ugbyrdscL8BmhdGNH4Giwqd1k3MwSyiswRuAuclYv27oKnFVBRT+n649px4g3Vqa8dh014wM2HDjMGENIkHx0hcV9BWdfBfTSCJengmosGW+wQfmaNUo4WpAbwZD73ALNsoLg5Yl1tB6ZZ5mHwLRY3LG2BbQZMZRCELUyvbh8ZsRksNN/2zcS44RIQdObV8/4hcLse30+NQ7GRaMnJeAMRz4Rpzbb02y3w0wNQFp/evj1nN4WTz6l8= your@email.com

Copy the entire output (from ssh-rsa to your email address).

Paste and Name Your Key

6. In the Azure DevOps dialog:
   • Name: Give your key a descriptive name (e.g., "Workshop Laptop 2026", "Home Desktop", "Work MacBook")
   • Public Key Data: Paste the entire public key you just copied
7. Click Save

Your SSH key has been successfully added and is ready to use

Naming tip: Use names that help you identify which machine uses each key. This makes it easier to revoke keys later if needed.

---

Step 3: Configure SSH (Optional but Recommended)

Create or edit your SSH configuration file to specify which key to use with Azure DevOps.

Create/Edit SSH Config File

Linux/Mac:

mkdir -p ~/.ssh
nano ~/.ssh/config

Windows PowerShell:

if (!(Test-Path "$HOME\.ssh")) { New-Item -ItemType Directory -Path "$HOME\.ssh" }
notepad $HOME\.ssh\config

Add Azure DevOps Host Configuration

Add these lines to your ~/.ssh/config file:

Host ssh.dev.azure.com
  IdentityFile ~/.ssh/id_rsa
  IdentitiesOnly yes

For Windows users, use backslashes in the path:

Host ssh.dev.azure.com
  IdentityFile C:\Users\YourName\.ssh\id_rsa
  IdentitiesOnly yes

What this does:

• Host ssh.dev.azure.com - Applies these settings only to Azure DevOps
• IdentityFile - Specifies which private key to use (your RSA key)
• IdentitiesOnly yes - Prevents SSH from trying other keys

Save the Configuration

Save and close the file:

• Nano: Press Ctrl+X, then Y, then Enter
• Notepad: Click File → Save, then close

---

Step 4: Test SSH Connection

Verify that your SSH key is working correctly.

Test Command

Run this command to test your connection:

ssh -T git@ssh.dev.azure.com

Expected Output

First-time connection will show a host key verification prompt:

The authenticity of host 'ssh.dev.azure.com (20.42.134.1)' can't be established.
RSA key fingerprint is SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og.
Are you sure you want to continue connecting (yes/no)?

Type yes and press Enter to add Azure DevOps to your known hosts.

Successful authentication will show:

remote: Shell access is not supported.
shell request failed on channel 0

Successful SSH test output showing authenticated connection

This is normal! Azure DevOps doesn't provide shell access, but this message confirms your SSH key authentication worked.

Troubleshooting Connection Issues

If the connection fails, see the Troubleshooting section below.

---

Step 5: Using SSH with Git

Now that SSH is configured, you can use it for all Git operations.

Clone a Repository with SSH

To clone a repository using SSH:

git clone git@ssh.dev.azure.com:v3/{organization}/{project}/{repository}

Example (replace placeholders with your actual values):

git clone git@ssh.dev.azure.com:v3/myorg/git-workshop/great-print-project

How to find your SSH URL:

1. Navigate to your repository in Azure DevOps
2. Click Clone in the top-right
3. Select SSH from the dropdown
4. Copy the SSH URL

Select SSH from the clone dialog to get your repository's SSH URL

Convert Existing HTTPS Repository to SSH

If you already cloned a repository using HTTPS, you can switch it to SSH:

cd /path/to/your/repository
git remote set-url origin git@ssh.dev.azure.com:v3/{organization}/{project}/{repository}

Verify the change:

git remote -v

You should see SSH URLs:

origin  git@ssh.dev.azure.com:v3/myorg/git-workshop/great-print-project (fetch)
origin  git@ssh.dev.azure.com:v3/myorg/git-workshop/great-print-project (push)

Daily Git Operations

All standard Git commands now work seamlessly with SSH:

# Pull latest changes
git pull

# Push your commits
git push

# Fetch from remote
git fetch

# Push a new branch
git push -u origin feature-branch

No more credential prompts! SSH authentication happens automatically.

---

Troubleshooting

Permission Denied (publickey)

Error:

git@ssh.dev.azure.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Causes and solutions:

1. SSH key not added to Azure DevOps

   • Go back to Step 2 and verify your public key is uploaded
   • Check you copied the entire public key (from ssh-rsa to your email)

2. Wrong private key being used

   • Verify your SSH config file points to the correct key
   • Test with: ssh -vT git@ssh.dev.azure.com (verbose output shows which keys are tried)

3. SSH agent not running (if you used a passphrase)

   • Start the SSH agent:

     eval "$(ssh-agent -s)"
     ssh-add ~/.ssh/id_rsa
     

Connection Timeout

Error:

ssh: connect to host ssh.dev.azure.com port 22: Connection timed out

Causes and solutions:

1. Firewall blocking SSH port (22)

   • Check if your organization's firewall blocks port 22
   • Try using HTTPS as a fallback

2. Network restrictions

   • Try from a different network (mobile hotspot, home network)
   • Contact your IT department about SSH access

3. Proxy configuration

   • If behind a corporate proxy, you may need to configure SSH to use it
   • Add to ~/.ssh/config:

     Host ssh.dev.azure.com
       ProxyCommand nc -X connect -x proxy.company.com:3128 %h %p
     

Host Key Verification Failed

Error:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!

Causes and solutions:

1. Azure DevOps updated their host keys (rare but happens)

   • Check Azure DevOps SSH key fingerprints
   • If fingerprint matches, remove old key and re-add:

     ssh-keygen -R ssh.dev.azure.com
     

2. Man-in-the-middle attack (security risk!)

   • If fingerprint doesn't match Microsoft's published keys, DO NOT PROCEED
   • Contact your security team

SSH Key Not Working After Creation

Symptoms:

• Created key successfully
• Added to Azure DevOps
• Still getting "Permission denied"

Solutions:

1. Check file permissions (Linux/Mac only)

   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/id_rsa
   chmod 644 ~/.ssh/id_rsa.pub
   

2. Verify key format

   • Ensure you copied the public key (.pub file) to Azure DevOps, not the private key
   • Public key starts with ssh-rsa

3. Test with verbose output

   ssh -vvv git@ssh.dev.azure.com
   

   • Look for lines like "Offering public key" to see which keys are tried
   • Check for "Authentication succeeded" message

---

Security Best Practices

Follow these security guidelines to keep your SSH keys safe:

Use Passphrase Protection

Always use a passphrase for your SSH keys, especially on:

• Laptops (risk of theft)
• Shared machines
• Devices that leave your office/home

How to add a passphrase to an existing key:

ssh-keygen -p -f ~/.ssh/id_rsa

Never Share Your Private Key

Critical security rule:

• NEVER share your private key (~/.ssh/id_rsa)
• NEVER commit private keys to Git repositories
• NEVER send private keys via email or chat

Only share:

• Public key (~/.ssh/id_rsa.pub) - This is safe and intended to be shared

Use Different Keys for Different Purposes

Consider creating separate SSH keys for:

• Work projects
• Personal projects
• Different organizations

Benefits:

• Limit blast radius if one key is compromised
• Easier to revoke access to specific services
• Better audit trail

Example: Create a work-specific key:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_work -C "work.email@company.com"

Then add to ~/.ssh/config:

Host ssh.dev.azure.com-work
  HostName ssh.dev.azure.com
  IdentityFile ~/.ssh/id_rsa_work

Rotate Keys Periodically

Recommended schedule:

• Personal projects: Annually
• Work projects: Every 6 months
• High-security projects: Every 3 months

How to rotate:

1. Generate new SSH key pair
2. Add new public key to Azure DevOps
3. Test the new key works
4. Remove old public key from Azure DevOps
5. Delete old private key from your machine

Revoke Compromised Keys Immediately

If your private key is exposed:

1. Immediately remove the public key from Azure DevOps
   • User Settings → SSH Public Keys → Click the key → Delete
2. Generate a new key pair
3. Update all repositories to use the new key

Protect Your Private Key File

Ensure correct file permissions:

Linux/Mac:

chmod 600 ~/.ssh/id_rsa

Windows:

icacls "$HOME\.ssh\id_rsa" /inheritance:r /grant:r "$($env:USERNAME):F"

Use SSH Agent Forwarding Carefully

SSH agent forwarding (-A flag) can be convenient but risky:

• Only use with trusted servers
• Prefer ProxyJump instead when possible

Enable Two-Factor Authentication (2FA)

While SSH keys are secure, enable 2FA on your Azure DevOps account for additional security:

1. Azure DevOps → User Settings → Security → Two-factor authentication
2. Use an authenticator app (Microsoft Authenticator, Google Authenticator)

---

Additional Resources

• Azure DevOps SSH Documentation: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate
• SSH Key Best Practices: https://security.stackexchange.com/questions/tagged/ssh-keys
• Git with SSH: https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key

---

Quick Reference

Common Commands

# Generate RSA key
ssh-keygen -t rsa -b 4096 -C "your.email@example.com"

# Display public key (Linux/Mac)
cat ~/.ssh/id_rsa.pub

# Display public key (Windows)
type $HOME\.ssh\id_rsa.pub

# Test SSH connection
ssh -T git@ssh.dev.azure.com

# Clone with SSH
git clone git@ssh.dev.azure.com:v3/{org}/{project}/{repo}

# Convert HTTPS to SSH
git remote set-url origin git@ssh.dev.azure.com:v3/{org}/{project}/{repo}

# Check remote URL
git remote -v

SSH URL Format

git@ssh.dev.azure.com:v3/{organization}/{project}/{repository}

Example:

git@ssh.dev.azure.com:v3/mycompany/git-workshop/great-print-project

---

Important Note: RSA and Modern SSH Key Algorithms

Why This Guide Uses RSA:

This guide exclusively uses RSA keys because Azure DevOps currently only supports RSA SSH keys. As of January 2026, Azure DevOps does not support modern SSH key algorithms like Ed25519, ECDSA, or other newer formats.

About RSA Security:

RSA is an older cryptographic algorithm that has been the industry standard for decades. While RSA with 4096-bit keys (as used in this guide) is still considered secure for most use cases, it has some limitations compared to modern alternatives:

RSA Drawbacks:

• Larger key sizes: RSA requires 4096 bits for strong security, resulting in larger keys
• Slower performance: Key generation and signature operations are slower than modern algorithms
• Older cryptographic foundation: Based on mathematical principles from the 1970s
• More CPU-intensive: Authentication operations require more computational resources

Modern Alternatives (Not Supported by Azure DevOps):

If Azure DevOps supported modern algorithms, we would recommend:

Ed25519:

• Faster: Significantly faster key generation and authentication
• Smaller keys: 256-bit keys (much smaller than RSA 4096-bit)
• Modern cryptography: Based on elliptic curve cryptography (ECC) with strong security guarantees
• Better performance: Less CPU usage, faster operations
• Widely supported: GitHub, GitLab, Bitbucket, and most modern Git platforms support Ed25519

ECDSA:

• Also based on elliptic curve cryptography
• Faster than RSA but slightly slower than Ed25519
• Supported by many platforms

Current State:

RSA with 4096-bit keys remains secure and is acceptable for Git authentication, despite being outdated compared to modern algorithms. The Azure DevOps team has not provided a timeline for supporting Ed25519 or other modern key types.

For Other Platforms:

If you're using GitHub, GitLab, Bitbucket, or other Git hosting services, we strongly recommend using Ed25519 instead of RSA:

# For platforms that support Ed25519 (GitHub, GitLab, Bitbucket, etc.)
ssh-keygen -t ed25519 -C "your.email@example.com"

References:

• Ed25519 Wikipedia
• SSH Key Algorithm Comparison
• Azure DevOps SSH Documentation

---

You're all set! SSH authentication with RSA keys is now configured for secure, passwordless Git operations with Azure DevOps.