micro-github

A tiny microservice that makes adding authentication with GitHub to your application easy.

Usage

Running your own micro-github is a single now command away:

# Deploy this repository using now.sh
now mxstbr/micro-github -e GH_CLIENT_ID=xyz123 -e GH_CLIENT_SECRET=asdf123 -e REDIRECT_URL=https://google.com

Environment variables

You'll need to provide three environment variables when running micro-github:

# Your GitHub application client id
GH_CLIENT_ID=xyz123
# Your GitHub application client secret
GH_CLIENT_SECRET=asdf123
# The URL to redirect the user to once the authentication was successful
REDIRECT_URL=https://google.com
# Optional: Specify the GitHub host when using GitHub Enterprise
GH_HOST=github.my-company.com

Create an application on GitHub here to get your client id and secret if you haven't done that already.

When authentication was successful, the user will be redirected to the REDIRECT_URL with the access_token query param set to the GitHub access token. You can then use that token to interact with the GitHub API!

E.g. setting REDIRECT_URL=https://google.com will redirect them to https://google.com/?access_token=asdf123. (where asdf123 is the provided access token)

Finish setup

To make this work you have to set the authorization callback URL of your application on GitHub to whatever URL now gave you plus the path /callback e.g. http://localhost:3000/callback:

To log people in provide a link to url now gave you plus the path login e.g. http://localhost:3000/login when they click on the link it will redirect to https://github.com/login/oauth/authorize?client_id=asdf123&state. (where client_id is your GitHub app client id in .env and state is a randomly generated string). This will redirect them to the GitHub sign in page for your app, which looks like this:

You can change the scope of the data you can access with the scope query param, see the GitHub docs!

When authentication is successful, the user will be redirected to the REDIRECT_URL with the access token from GitHub for you to use! ?

Error handling

In case an error happens (either by the service or on GitHub) the user will be redirected to the REDIRECT_URL with the error query param set to a relevant error message.

Development

git clone git@github.com:mxstbr/micro-github.git

Move .env.example to .env and fill in your GitHub API details and redirect url

npm run dev

The server will then be listening at localhost:3000, so set the authorization callback URL of your dev application on GitHub to http://localhost:3000/callback.

Updating

The master branch of this repository is what you will be deploying. To update to a new version with potential bugfixes, all you have to do is run the now command again and then set the authorization callback URL on GitHub to the new URL that now gave you! ?

License

Copyright (c) 2017 Maximilian Stoiber, licensed under the MIT license. See LICENSE.md for more information.