mxstbr / micro-github

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

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 is 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 [email protected]: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.

micro-github's Issues

Make the response mode configurable: fragment, query or form_post

For single page apps, you don't want to send the access tokens to the backend server. Putting the access token in the query string will do that. So for single page apps, you'll want to use the hash fragment instead (https://mysite.com#access_token=xyz).

For web applications you might want to use a form post instead of the query string. The end result is the same (both post and querystring will be available in the req), but the main difference is that with a form post the access token is not exposed in the browser history etc...

Support state

When opening the first GitHub link to let the user authenticate, one can add a state parameter:

state: An unguessable random string. It is used to protect against cross-site request forgery attacks.

This state will then be sent back by GitHub on the second step:

If the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, the request has been created by a third party and the process should be aborted.

The issue is that the microservice has no chance of knowing the state users send to GitHub in the first step.

---

One way I figured out to work around this is to have people login by providing a link to

my-url.now.sh/login

Which would redirect to the GitHub login page with some random string stored in memory, which we can then compare in the second step.

Does that make sense?

(GitHub source)

Specify scopes with a query parameter: how?

The readme mentions:

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

Where does the query string go? According to GitHub's documentation, it would go in the authorize request, which is hardcoded in micro-github. It doesn't appear to do anything on the /login or /callback endpoints. I certainly might be very wrong, but afaict, the only way you'd be able to change the scope of the data you can access is by forking this project and modifying that line.

Support more providers and rename this repo to a more generic name

So, this is a great idea, but I see no reason for it to be limited to just github.
All oauth authentication services are very similar, just the URL change.

Why not make this support Github, Google, Linkedin, Instagram, etc?
If not, some other repos like this one will start appearing, but I believe yours should be the default one.

Support GitHub Enterprise

Clarification

Hey.
In GitHub OAuth Apps, the Call back URL needs to be the redirection URL right?
I am trying to use it for an application like https://codepan.net

But my authentication is failing :/