About

Stateless authentication microservice for "login-with" functionality, supporting:

Twitter
GitHub
Reddit
Facebook
Google
LinkedIn
Instagram
Mixer
Spotify
Strava
AppleID
... more to come (PRs welcome)

You can deploy with now or Docker (for mandatory and optional env variables see below).

$ now lipp/login-with
$ docker run lipp/login-with

This microservice must run in a subdomain of yours, e.g. login.yourdomain.com.

<a href='https://login.yourdomain.com/twitter?success=ON_SUCCESS_URL&failure=ON_FAILURE_URL'>
  Login with Twitter
</a>

On successful login two cookies will be created:

jwt - A "JSON Web Token" (JWT) containing profile information and the respective access tokens (Twitter/etc). http-only!
profile - A JSON string which containing non-sensitive information (accessible from browser JS):
- username - string / mandatory, the account specific user alias (e.g. Twitter name)
- photo - string / optional, the account specific user image link
- name - string / optional, the "real" name

The cookies will be available for your toplevel domain and all subdomains. In addition, the cookie's secure flag is set, which means that your other websites/webservices must run over https.

Supported by

If you want to easily add token-based authentication to your apps, feel free to check out Auth0's SDKs and free plan at auth0.com/overview .

Setup

The configuration is done by means of environment variables.

Mandatory environment variables

LW_SESSION_SECRET - The session secret used by the microservice
LW_JWT_SECRET - The secret to sign the JSON Web Token (JWT)
LW_SUBDOMAIN - The subdomain this microservice runs, e.g. login.yourdomain.com. All other subdomains (e.g. api.yourdomain.com) and the top-level (e.g. yourdomain.com)

Optional environment variables

LW_COOKIE_MAXAGE - The max age of the store cookie, defaults to 10 days
LW_PROFILE_COOKIENAME - The profile's cookie name, defaults to profile
LW_JWT_COOKIENAME - The JSON Web Token's (JWT) cookie name, defaults to jwt
LW_DYNAMIC_SCOPE - When set allows you to customize the scopes used in an authentication request, defaults to off
LW_COOKIE_DOMAIN - The explicit cookie domain, e.g. .foo.com. If not specified this will derive from LW_SUBDOMAIN, e.g. if LW_SUBDOMAIN=login.foo.com then the cookie domain "defaults" to .foo.com. This is ok unless you have multi level subdomain for (LW_SUBDOMAIN=dev.login.foo.com). In this case you must explicitly set LW_COOKIE_DOMAIN=.foo.com as .login.foo.com would be the auto guessed value.

GitHub specific environment variables

You need to create your own GitHub OAuth application. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/github/callback

LW_GITHUB_CLIENTID - Your GitHub Client ID
LW_GITHUB_CLIENTSECRET - Your GitHub Client Secret

Google specific environment variables

You need to create your own Google OAuth application. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/google/callback

LW_GOOGLE_CLIENTID - Your Google Client ID
LW_GOOGLE_CLIENTSECRET - Your Google Client Secret

Facebook specific environment variables

You need to create your own Facebook login application. If LW_SUBDOMAIN=login.yourdomain.com your allowed redirects must be: https://login.yourdomain.com/facebook/callback

LW_FACEBOOK_APPID - Your Facebook App ID
LW_FACEBOOK_APPSECRET - Your Facebook App Secret

LinkedIn specific environment variables

You need to create your own LinkedIn OAuth2 application. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/linkedin/callback

LW_LINKEDIN_CLIENTID - Your LinkedIn Client ID
LW_LINKEDIN_CLIENTSECRET - Your LinkedIn Client Secret

Reddit specific environment variables

You need to create your own Reddit OAuth application. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/reddit/callback

LW_REDDIT_CLIENTID - Your Reddit Client ID
LW_REDDIT_CLIENTSECRET - Your Reddit Client Secret

Twitter specific environment variables

You need to create your own Twitter OAuth application. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/twitter/callback

LW_TWITTER_CONSUMERKEY - Your Twitter Consumer Key
LW_TWITTER_CONSUMERSECRET - Your Twitter Consumer Secret

Mixer specific environment variables

You need to create your own Mixer OAuth Client. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/mixer/callback

LW_MIXER_CLIENTID - Your Mixer Client ID
LW_MIXER_CLIENTSECRET - Your Mixer Client Secret
LW_MIXER_SCOPE - Specify which scopes the authorization request with Mixer should have. Check Mixer's documentation for scopes.

Instagram specific environment variables

You need to create your own Instagram OAuth application. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/instagram/callback

LW_INSTAGRAM_CLIENTID - Your Instagram Client ID
LW_INSTAGRAM_CLIENTSECRET - Your Instagram Client Secret

Spotify specific environment variables

You need to create your own Spotify OAuth application. If LW_SUBDOMAIN=login.yourdomain.com is your Authorization callback URL must be: https://login.yourdomain.com/spotify/callback

LW_SPOTIFY_CLIENTID - Your Spotify Client ID
LW_SPOTIFY_CLIENTSECRET - Your Spotify Client Secret

Strava specific environment variables

You need to create your own Strava OAuth application. If LW_SUBDOMAIN=login.yourdomain.com your Authorization callback URL must be: https://login.yourdomain.com/strava/callback

LW_STRAVA_CLIENTID - Your Strava Client ID
LW_STRAVA_CLIENTSECRET - Your Strava Client Secret

AppleID specific environment variables

You need to be Apple Developer:

LW_APPLE_TEAMID - Team ID at your membership page
LW_APPLE_KEYID - register new key. Add "Sign in with Apple" capability, download key. it downloads only once
LW_APPLE_KEYLOCATION - path to key file relative to your server
LW_APPLE_SERVICEID - register Services ID
LW_APPLE_CALLBACK - enable "Sign in with Apple" capability in service you created, configure your callback url (should be like: https://yourwebsite.com/apple/callback)

Endpoints

/twitter - login with Twitter account (if configured through env variables)
/facebook - login with Facebook account (if configured through env variables)
/github - login with GitHub account (if configured through env variables)
/google - login with Google account (if configured through env variables)
/reddit - login with Reddit account (if configured through env variables)
/mixer - login with Mixer account (if configured through env variables)
/linkedin - login with LinkedIn account (if configured through env variables)
/instagram - login with Instagram account (if configured through env variables)
/spotify - login with Spotify account (if configured through env variables)
/strava - login with Strava account (if configured through env variables)
/apple - login with AppleID (if configured through env variables)
/logout - logout and clears the respective cookies

All endpoints expect the query parameters:

success A url to redirect to in case of successful login (use encodeURIComponent for proper escaping)
failure A url to redirect to in case of failed login (use encodeURIComponent for proper escaping)

Don't forget to encodeURIComponent on them.

Testing

Say you deployed your login-with container with:

correct environment variables
properly configured services (e.g. Twitter callback)
served via https on auth.your-domain.com

Then you can test everything by just "visiting" your login strategy with the browser, e.g. https://auth.your-domain.com/twitter. In case of success, you will be finally redirected and see the contents of your profile as JSON. In case of error, the error will be shown as JSON.

Example

Visit login-with.com. The source code is here.

Deployment with now

Note: You need a custom domain to run this microservice with now. Chrome (and maybe other browsers) explicitly prevent usage of wildcard cookies on .now.sh, which are required for this microservice to work.

Create your secrets for the environment variables
Deploy, e.g. with now

now lipp/login-with \
	-e NODE_ENV=production \
	-e LW_SUBDOMAIN=login.yourdomain.com \
	-e LW_SESSION_SECRET=@lw-session-secret \
	-e LW_JWT_SECRET=@lw-token-secret \
	-e LW_REDDIT_CLIENTID=@lw-reddit-clientid \
	-e LW_REDDIT_CLIENTSECRET=@lw-reddit-clientsecret \
	-e LW_GITHUB_CLIENTID=@lw-github-clientid \
	-e LW_GITHUB_CLIENTSECRET=@lw-github-clientsecret \
	-e LW_TWITTER_CONSUMERKEY=@lw-twitter-consumerkey \
	-e LW_TWITTER_CONSUMERSECRET=@lw-twitter-consumersecret \
	-e LW_INSTAGRAM_CLIENTID=@lw-instagram-clientid \
	-e LW_INSTAGRAM_CLIENTSECRET=@lw-instagram-clientsecret \
	--alias login.yourdomain.com

Deployment with Docker

Create your secrets for the environment variables
Deploy, e.g. with Docker

docker run lipp/login-with -p 80:3000 \
	-e NODE_ENV=production \
	-e LW_SUBDOMAIN=login.yourdomain.com \
	-e LW_SESSION_SECRET=@lw-session-secret \
	-e LW_JWT_SECRET=@lw-token-secret \
	-e LW_REDDIT_CLIENTID=@lw-reddit-clientid \
	-e LW_REDDIT_CLIENTSECRET=@lw-reddit-clientsecret \
	-e LW_GITHUB_CLIENTID=@lw-github-clientid \
	-e LW_GITHUB_CLIENTSECRET=@lw-github-clientsecret \
	-e LW_TWITTER_CONSUMERKEY=@lw-twitter-consumerkey \
	-e LW_TWITTER_CONSUMERSECRET=@lw-twitter-consumersecret \
	-e LW_INSTAGRAM_CLIENTID=@lw-instagram-clientid \
	-e LW_INSTAGRAM_CLIENTSECRET=@lw-instagram-clientsecret \

ripkens / login-with Goto Github PK

login-with's Introduction