Anvil Connect lib for Express
Overview
This is a simple auth middleware for Express.js apps that works with the
Anvil Connect
authentication/authorization server (based on the
OpenID Connect and OAuth 2 stack), and the
anvil-connect-nodejs
client.
Installation
This library assumes that you have Node.js installed (it's developed and tested on Node 4 and above), and are familiar with Express routes and middleware. To install dependencies:
npm install
Configuration
Require the project and configure the client with an issuer
, a client_id
,
and a client_secret
. For more information on registering and configuring
OpenID Connect clients, see the
Anvil Connect Documentation.
var AnvilConnectExpress = // configure the REST clientvar oidc = issuer: 'https://connect.example.com' client_id: 'YOUR_CLIENT_ID_HERE' client_secret: 'YOUR_CLIENT_SECRET_HERE' // Your express app can go here... for example:var express = var app =
Usage
The Anvil Connect lib for Express allows you to require authentication and authorization for any requests to any number of Express endpoints (or even the entire server).
Single endpoint
app
All endpoints
app app app
Optionally Authenticate
By default, as in the above examples, if an endpoint uses the verifier()
middleware, it will throw an HTTP
401 Unauthorized
An access token is required
error if an access token is not included with that
request.
However, for some use cases, the access token is optional, but you still want
to invoke verifier()
so that the token is parsed, and the credentials are
added to the req
object for downstream use. For example, if the resource was
set to 'allow anyone to read' by its owner, a request with no token is
acceptable - no error should be raised until the control flow passes to a
downstream authorization component.
In this case, set the optional parameter allowNoToken
to true:
var verifyOptions = allowNoToken: true app
Optionally Load User Info
In addition to parsing and verifying the access token, you can ask verifier()
to also load user profile details from the OpenID Provider's /userinfo
endpoint:
var verifyOptions = loadUserInfo: true app
Customizations
The Anvil Connect lib for Express allows for some customization. You can
authorize with a required scope or even whitelist clients you want to allow by
client_id
.
Authorize with a required scope
// authorize one or more endpoints with a required scopevar authorize = oidcapp
//Authorize your entire server with a required scopeapp app app
Restrict to specific clients
var authorize = oidc
Unit Testing
To run the unit tests after installation:
npm test
License
MIT