charlesread / fastify-auth0

Auth0 authentication for Fastify apps

fastify-auth0

fastify-auth0 adds Auth0 authentication to Fastify-based apps. This plugin assumes that you know a bit about OAuth 2, and Auth0.

• Example
• Session, Cache, and Cookie
• Usage and Options
  • Options

Example

npm install --save fastify-auth0

'use strict'

const fastify = require('fastify')()

const plugin = require('fastify-auth0')

fastify
  .register(require('fastify-cookie'))
  .register(require('fastify-caching'))
  .register(require('fastify-server-session'), {
    secretKey: 'some-secret-password-at-least-32-characters-long',
    sessionMaxAge: 1000 * 60 * 15, // 15 minutes
    cookie: {
      domain: 'localhost',
      path: '/',
      expires: 1000 * 60 * 15,
      sameSite: 'Lax' // important because of the nature of OAuth 2, with all the redirects
    }
  })
  .register(plugin, {
    domain: '',
    client_id: '',
    client_secret: '',
    // optional
    transformer: async function (credentials) {
      credentials.log_in_date = new Date()
      credentials.foo = 'bar'
      // credentials.id = await someFunctionThatLooksUpId(credentials)
      return credentials
    },
    // optional
    success: async function (credentials) {
      console.log(`${credentials.given_name} logged in at ${credentials.log_in_date}`)
    }
  })

fastify.get('/', async function (request, reply) {
  // the credentials returned from Auth0 will be available in routes as request.session.credentials
  return reply.send({credentials: request.session.credentials})
})

fastify.listen(3000)
  .then(function () {
    console.log('listening on %s', fastify.server.address().port)
  })
  .catch(function (err) {
    console.error(err.stack)
  })

Session, Cache, and Cookie

This plugin requires a session provider to be accessible via request.session. fastify-auth0 works well out-of-the-box with fastify-server-session, a simple configuration is shown above.

Usage and Options

fastify-auth0 is a very typical fastify plugin, in that it is registered in the following fashion:

fastify.register(require('fastify-auth0'), options)

Options

TL;DR

At minimum you need a domain, client_id, and client_secret. You'll get back, from Auth0 upon successful auth, the things requested in scope, all of that stuff will become request.session.credentials in routes. After successful auth with Auth0 you'll be redirected to handlerPath, which does important stuff, it's the "callback URL" referenced a lot in documentation, which you need to whitelist with Auth0 (which here is really just appUrl + handlerPath, this goes to Auth0 as the redirect_uri query string parameter during redirection to Auth0 for authentication).

options itself is a simple object that allows the following keys:

Key		Type/[default]	Notes
domain	required	string	This is your Auth0 domain, like example.auth0.com
client_id	required	string	The id of your Auth0 client
client_secret	required	string	Your client's secret
scope		string/"profile openid email"	The scope of information about a user that you'd like back from Auth0 upon successful authentication
appUrl		"http://localhost:3000"	appUrl and handlerPath are fairly important. Together they produce the redirect_uri query string parameter in the redirection to Auth0. This is very useful in situations where your application is clustered or behind a load balancer or something, where you wouldn't necessarily want Auth0 redirecting back to a particular node of the cluster, for example.
handlerPath		"/callback"	The path that Auth0 will redirect to once successfully authenticated with Auth0, see the note above about appUrl.
success		[async] function (credentials, request)	A function that should be called when a user is successfully authenticated, this is for your purposes and has no effect on the plugin. credentials is that which Auth0 returns.
transformer		[async] function (credentials, request)	Very similar to [async] function success(credentials, request), except that this function can affect stuff. In particular that which this function returns will become request.session.credentials in your routes.
getSession		async function (request) { return request.session }	fastify-auth0 needs to set and retrieve session data, this function specifies how the plugin gets the session.

fastify-auth0's Issues

Failed Login

Hi,

I try your example but I have an issue with Auth0:
Password login via OIDC-conformant clients with externally-hosted login pages is unsupported. Alternatively, login could have been initiated from the wrong place (e.g., a bookmark).

Do you know if there is a solution to fix this issue ?

Thank you