@rill/auth
v3.0.0
Published
Simple session login and logout for Rill.
Downloads
140
Maintainers
Readme
Simple session authentication with login and logout for Rill with support for timeouts, refreshes and more.
Installation
npm install @rill/session @rill/auth
Example
const rill = require('rill')
const app = rill()
const session = require('@rill/session')
const auth = require('@rill/auth')
// Setup middleware
app.use(session()) // A session is required
app.use(auth())
// Work with authentication.
app.use((ctx, next)=> {
var user = ...
// A user can be anything.
ctx.login(user, {
ttl: '30 minutes', // optionally override ttl option
refresh: false // optionally override refresh option
})
// User is attached to and a cookie created.
ctx.locals.user === user //-> true
// Test if a user is logged in.
ctx.isLoggedIn() //-> true
ctx.isLoggedOut() //-> false
// Removes the user cookie.
ctx.logout()
});
// Route that only allows logged in users.
app.get('/a', auth.isLoggedIn(), ...)
// Route that only allows logged out in users.
app.get('/b', auth.isLoggedOut(), ...)
Options
// To enable a login that automatically refreshes and expires after 1 hour of inactivity you can use:
{
"key": "different-cookie-key", // change cookie name
"ttl": "1 hour", // change when the auth expires.
"refresh": true // automatically reset auth expiry on page load.
}
Utilities
auth.isLoggedIn({ fail, redirect, fallback })
Creates a middleware that will only continue if a user is logged in.
If the fail
option is supplied it will throw a 401 error with the provided message when the user is not logged in.
app.use(auth.isLoggedIn({ fail: 'You must be logged in to access the api.' }))
If the redirect
option is supplied it will redirect when the user is not logged in.
app.use(auth.isLoggedIn({ redirect: '/login' }))
If the fallback
option is supplied it will call the fallback function when the user is not logged in.
app.use(auth.isLoggedIn({ fallback: handleUserNotLoggedIn }))
function handleUserNotLoggedIn (ctx, next) {...}
Otherwise nothing will happen but the next middleware will not be called.
auth.isLoggedOut({ fail, redirect, fallback })
If the fail
option is supplied it will throw a 401 error with the provided message when the user is logged in.
app.use(auth.isLoggedOut({ fail: 'This page is only accessable when not logged in' }))
If the redirect
option is supplied it will redirect when the user is logged in.
app.use(auth.isLoggedOut({ redirect: '/dashboard' }))
If the fallback
option is supplied it will call the fallback function when the user is logged in.
app.use(auth.isLoggedOut({ fallback: handleUserLoggedIn }))
function handleUserLoggedIn (ctx, next) {...}
Otherwise nothing will happen but the next middleware will not be called.
Contributions
- Use
npm test
to run tests.
Please feel free to create a PR!