AuthRocket/Express middleware

The authrocket-middleware enables our streamlined integration with Express and other compatible frameworks.

If it’s possible to use the middleware as-is, we highly recommend it as this will get you up and running as quickly as possible. If not possible, then the code here will still serve as a valuable reference.

To talk directly to our API, see authrocket-node as well. Both libraries work well together if you need functionality provided by each.

If you’re working on the frontend part of your app, see loginrocket.js instead.

Usage

authrocket-middleware is designed to work with Express and any other framework that uses Express-compatible middleware, such as Connect.

Start by adding the npm package to your project.

Depending on your package manager, run one of:

npm install @authrocket/authrocket-middleware

yarn add @authrocket/authrocket-middleware

Setting up the middleware and /logout route

Next, add the middleware to your app (most commonly in app.js).

// add this near the top with the rest of your require() statements:
const { arMiddleware, cookieParser, fullLogout, requireLogin } = require('@authrocket/authrocket-middleware')

// ensure this is in your middleware list (anywhere before arMiddleware):
app.use(cookieParser())

// add this at the end of your middleware list, and *before* your routes:
app.use(arMiddleware({
  authrocket: {
    loginrocketUrl: 'https://SAMPLE.e2.loginrocket.com/'
  }
}))

// add this with the rest of your routes (at the beginning is fine)
app.use('/logout', fullLogout)

loginrocketUrl will be unique to your app and is available in the AuthRocket management portal at Realm -> Integration -> LoginRocket Web.

Alternatively, you may use an environment variable instead:

LOGINROCKET_URL=https://SAMPLE.e2.loginrocket.com/

Then setup arMiddleware like so:

app.use(arMiddleware())

Protecting resources

You may require a login to access your entire app, individual routes, or a group of routes via a sub-router.

In all cases, if a user is already logged in, each route will proceed normally. If a user isn’t logged in yet, they’ll be redirected to your LoginRocket page, and after logging in (or signing up), will be redirect back to the original route.

Entire app

Add requireLogin as another middleware. Make sure it’s after arMiddleware:

app.use(requireLogin)

Individual routes

Add requireLogin to individual routes:

app.get('/protected',
  requireLogin,
  function(req, res, next) {
    // normal route behavior here, eg:
    res.render('protected')
  }
)

This works the same for sub-routes (router.get(...)) too.

Groups of routes

A common pattern is to group a set of routes into a sub-router.

For example, app.js might have something like this:

app.use('/admin', adminRouter)

Then to admin.js, you’ll add this:

// ...existing require() statements
const { requireLogin } = require('@authrocket/authrocket-middleware')
router.use(requireLogin)

// ...router.get('/', ...)

Helpers for account and user info & generating links

authrocket-middleware also provides a number of helper functions for use in your routes/controllers and your views.

In your routes, helpers are accessed using req.authrocket.currentOrg. In your views, the same would be accessed simply as authrocket.currentOrg. Remaining examples will use the shorter version, but the same set of helpers is available in both places.

The current Membership and Org (account) are accessible as:

authrocket.currentOrg
authrocket.currentMembership

Similarly, the current User and Session are also available:

authrocket.currentUser
authrocket.currentSession

A number of URL/link helpers make it easy to build the proper links to move users seamlessly between LoginRocket and your app:

authrocket.arLoginUrl()     // Login
authrocket.arSignupUrl()    // Signup
authrocket.arProfileUrl()   // Manage profile
authrocket.arAccountUrl()   // Manage current account
authrocket.arAccountsUrl()  // Switch accounts (when using AuthRocket in team/multi-user mode)

Here’s a simple example nav using pug/jade that demonstrates a few of these:

body
  nav
    if authrocket.currentUser
      span Hi, #{authrocket.currentUser.name}!
      a(href=authrocket.arProfileUrl({redirect_uri: authrocket.requestUri()})) Manage Profile
      a(href='/logout') Logout
    else
      a(href=authrocket.arSignupUrl()) Signup
      a(href=authrocket.arLoginUrl()) Login

Customizing the integration

The middleware’s default configuration tries to handle as much for you as possible. However, there may be times when you want to modify the default behavior.

Logouts

By default, visiting /logout will log the user out of both your app and LoginRocket. In some instances, you might want to log them out of your app, but not LoginRocket.

To do this, simply change this:

const { fullLogout } = require('@authrocket/authrocket-middleware')
...
app.use('/logout', fullLogout)

to this:

const { localLogout } = require('@authrocket/authrocket-middleware')
...
app.use('/logout', localLogout)

arMiddleware

arMiddleware supports some configuration options:

arMiddleware({
  // This object used to configure the AuthRocket client internally. It is the same as provided
  //   to `new AuthRocket({...})` when using `authrocket-node`.
  authrocket: { ... },

  // Disables storage of token in cookies.
  // cookie: false,

  // Change the default settings used to create the token-storing cookie.
  cookieOptions: {
    httpOnly: true,
    // maxAge: 86400000,        // Default: matches expiration of the token
    secure: 'auto',             // 'auto' becomes true if site accessed via https, else false
    // any other param supported by Node's Response.cookie()
  },
})

Cookies

authrocket-middleware uses a cookie called arToken to persist the token. This uses the cookie-parser plugin. arMiddleware imports this for you (you may also import your own version directly), but you still need to enable it. Customize the settings using cookie or cookieOptions as described above.

If disabling cookies with cookie: false (see above), cookieParser may also be skipped. This is generally only appropriate for API-only apps (see below).

Building an API app

If your backend is just an API, perhaps because your frontend is a separate SPA, then login tokens work a little differently.

Your frontend will need to capture the login token directly, save it, and then add it to requests to the backend.

If you’re using loginrocket.js, see the example processResponse() function in the loginrocket.js Integration Guide, in particular setting window.sessionStorage.arToken. You can access that property directly to add the login token to your backend requests.

On the backend, authrocket-middleware will automatically detect login tokens sent via the Authorization header. The frontend (or any other client) simply needs to send this HTTP header:

Authorization: Bearer TOKEN-GOES-HERE