micro-oauth

A tiny microservice that makes it easier to add OAuth authentication to your application. This supports any provider that follows the OAuth2 protocol, like GitHub and Instagram.

Usage

Clone this repo

Clone the repo:

git clone git@github.com:brunolemos/micro-oauth.git

Enviroment variables

Edit the env field inside now.json. Example:

{
  // The provider you are authenticating on
  "PROVIDER": "GitHub",
  // or Instagram, ...

  // The provider authorize url (to request permissions from the user)
  "AUTHORIZE_URL": "https://github.com/login/oauth/authorize",
  // or https://www.instagram.com/oauth/authorize, ...

  // The URL to redirect the user to once the authentication was successful
  // PS: You can also pass this as a ?callback_url parameter on AUTHORIZE_URL env variable above
  "CALLBACK_URL": "myapp://oauth/github",
  // or http://localhost:1234/my/oauth/callback/xxx, ...

  // Your application client id
  "CLIENT_ID": "abc123",

  // Your application client secret
  "CLIENT_SECRET": "abc123",

  // Provider's url to get the access token
  "GET_TOKEN_URL": "https://github.com/login/oauth/access_token"
  // or https://api.instagram.com/oauth/access_token, ...
}

Create an application on the provider website (e.g. GitHub, Instagram, ...) to get your CLIENT_ID and CLIENT_SECRET if you haven't done that already.

Deploy

now

More details

To request people authorization, you need to send them to http://localhost:3000/ or the url generated by now.

You can pass a ?scope= query param to set the permissions you request from the user, check the provider docs (GitHub, Instagram, ...) You can actually pass any other parameter and they will be passed to the callback as well

When authentication was successful, the user will be redirected to the CALLBACK_URL with the access_token query param set to the provider access token. You can then use that token to interact with the Provider API! (see: GitHub API, Instagram API, ...)

E.g. setting CALLBACK_URL=myapp://oauth/github will redirect them to myapp://oauth/github/?access_token=abc123. (where abc123 is the provided access token)

If you passed other parameters to AUTHORIZE_URL, e.g. http://xxx.com/?xxx=1, it will be passed to the callback url, e.g. http://callbackurl.com/?access_token=abc123&xxx=1

Finish setup

To make this work you have to set the authorization callback URL on the provider website to whatever URL now gave you:

or localhost for testing:

Error handling

In case an error happens on the server, the user will be redirected to the CALLBACK_URL with the error query param set to a relevant error message.

License

Copyright (c) 2018 Bruno Lemos & Maximilian Stoiber, licensed under the MIT license. See LICENSE.md for more information.