github-auth

Pairing with strangers has never been so good.

github-auth allows you to quickly pair with anyone who has a GitHub account by adding and removing their public ssh keys from your authorized_keys file.

Description

If you agree to #pairwithme, we'll probably be SSHing into my laptop, your laptop, or some laptop in the sky. Sharing passwords over email is no fun, so we'll use public key authentication to keep things fun, fast, and secure.

Let's see how this works.

After you've installed gh-auth, you can give me ssh access with:

$ gh-auth add chrishunt
Adding 2 key(s) to '/Users/chris/.ssh/authorized_keys'

That was easy! When we're done working, you can revoke my access with:

$ gh-auth remove chrishunt
Removing 2 key(s) from '/Users/chris/.ssh/authorized_keys'

You can add and remove any number of users at the same time.

$ gh-auth add chrishunt zachmargolis
Adding 4 key(s) to '/Users/chris/.ssh/authorized_keys'

$ gh-auth remove chrishunt
Removing 2 key(s) from '/Users/chris/.ssh/authorized_keys'

$ gh-auth remove zachmargolis
Removing 2 key(s) from '/Users/chris/.ssh/authorized_keys'

Usage

Command Line

gh-auth can be used from the command line after the gem has been installed.

usage: gh-auth [--version] [add|remove] <username>

In You Project

Want to add/remove keys in your project, but not on the command line? That's ok too.

require 'github/auth'

# Add keys for GitHub user 'chrishunt'
Github::Auth::CLI.new(%w(
  add chrishunt
)).execute

# Remove keys for GitHub user 'chrishunt'
Github::Auth::CLI.new(%w(
  remove chrishunt
)).execute

Installation

Install the github-auth gem:

$ gem install github-auth

$ gh-auth
usage: gh-auth [--version] [add|remove] <username>

SSH Public Key Authentication (Mac OS X)

Public key authentication works with Mac OS by default, but you'll need to get your ssh server running. This is done by ticking 'Remote Login' in the 'Sharing' panel of System Preferences.

Now that SSH is running, make sure you have the correct permissions set for your authorized keys.

$ chmod 700 ~/.ssh
$ chmod 600 ~/.ssh/authorized_keys

Verification

If you'd like to verify that everything is working as expected, you can test locally on your own machine.

First, authorized yourself for ssh. (Make sure to replace 'chrishunt' with your Github username)

$ gh-auth add chrishunt
Adding 2 key(s) to '/Users/chris/.ssh/authorized_keys'

Now that your keys are added, verify that you can open an SSH session to your machine with public key authentication:

$ ssh -o PreferredAuthentications=publickey localhost

(localhost)$

Next, remove your public keys from the keys file:

$ gh-auth remove chrishunt
Removing 2 key(s) from '/Users/chris/.ssh/authorized_keys'

Since you've removed your keys, verify now that you can no longer login to your machine with public key authentication:

$ ssh -o PreferredAuthentications=publickey localhost

> Permission denied (publickey,keyboard-interactive)

Troubleshooting

How do people actually connect to my machine?

Good question! Others will connect to your machine using ssh:

$ ssh username@external-ip-address

What username do I use?

The username is going to be the same username that you used to add the keys. In most cases, it's a good idea to create a new pair account and use that account for all pairings. You don't want strangers reading your email!

Once you've created the pair account, you can switch to it yourself in a terminal with:

$ su - pair

How do I get my external IP?

You can get your external IP address with:

$ curl http://remote-ip.herokuapp.com

It's still not working! :(

In almost all cases, your laptop is not directly plugged into your modem. You're on a wirelress network or plugged directly into a router or switch. This means the external IP address that your pair is connecting to is not your machine, it's actually your router.

You can tell your router to forward ssh connections to your machine by enabling port forwarding. You will want to forward port 22 (ssh) to the local IP address of your machine.

If port 22 is already forwarded to another machine or you want to change things up, you can have ssh listen on another port and have your pair connect with:

ssh -p <port> username@external-ip-address

I can't enable port forwarding, my boss won't let me. Can I still pair?

Yes! A nice solution to this is to have a machine somewhere else that both of you can ssh into. Place this machine on a network that you do have the ability to forward ports. Maybe this machine is at home, a friend's house, or at a company your worked for in the past that forgot to turn it off.

If this isn't possible, then you can use a VPS provider like Linode to setup a pairing machine in the cloud.

Contributing

Please see the Contributing Document