To add basic auth capabilities to an Express app, we can use the express-basic-auth package.
With it, we can check for a given username and password in the URL in our protected routes.
In this article, we’ll take a look at how to use it.
How to Install
express-basic-auth is available as a Node package, we can install it by running:
npm install express-basic-auth
Basic Usage
We can use it as follows:
const express = require('express');
const basicAuth = require('express-basic-auth')
const app = express();
app.use(basicAuth({
users: { 'admin': 'supersecret' }
}))
app.get('/', (req, res) => {
res.send('authorized');
});
app.listen(3000, () => console.log('server started'));
In the code above, we included the basicAuth middleware from express-basic-auth from in our app.
Then we can call app.use with an object that has the users property with the usernames as the keys and the corresponding passwords as the values.
Then if we make a GET request to a URL like:
https://admin:supersecret@ThistleDarkExponents--five-nine.repl.co
Then we’ll get the authorized response back since the username and password matches what we listed in the object in our app.
Otherwise, we’ll get a 401 response and a configurable body, which is empty by default.
Custom Authorization
We can also pass in our own authorizer function to check for credentials that we want.
We shouldn’t use standard string comparison with == or === when comparing user input with sercet credentials since it’ll make our app vulenrable to timing attacks.
Timing attacks are a side-channel attack where the attacker tries to compromise a system by analyzing the time taken to run cryptographic algorithms.
We should use the safeCompare method provided by the package instead.
Also, we should use bitwise logic operators instead of standard ones for the same reason.
For example, we can use the following:
const express = require('express');
const basicAuth = require('express-basic-auth')
const app = express();
app.use(basicAuth({
authorizer: (username, password) => {
const userMatches = basicAuth.safeCompare(username, 'admin')
const passwordMatches = basicAuth.safeCompare(password, 'supersecret')
return userMatches & passwordMatches
}
}))
app.get('/', (req, res) => {
res.send('authorized');
});
app.listen(3000, () => console.log('server started'));
In the code above, we have a function that calls safeCompare to match the username and password respectively and then use the AND bitwise operator to combine the 2 to make sure that both are true .
Async Authorization
We can set the authorizeAsync option to true and set a function with a cb parameter for the callback as the authorizer function to check credentials asynchronously:
const express = require('express');
const basicAuth = require('express-basic-auth')
const app = express();
app.use(basicAuth({
authorizer: (username, password, cb) => {
const userMatches = basicAuth.safeCompare(username, 'admin')
const passwordMatches = basicAuth.safeCompare(password, 'supersecret')
if (userMatches & passwordMatches)
return cb(null, true)
else
return cb(null, false)
},
authorizeAsync: true,
}))
app.get('/', (req, res) => {
res.send('authorized');
});
app.listen(3000, () => console.log('server started'));
We return the cb callback call instead of returning the result directly in our authorizer function.
Unauthorized Response Body
We can set the unauthorizedResponse property to a function that returns a response that we want to show when a credential check failed.
For example, we can write:
const express = require('express');
const basicAuth = require('express-basic-auth')
const app = express();
app.use(basicAuth({
users: { 'admin': 'supersecret' },
unauthorizedResponse: (req) => {
return `unauthorized. ip: ${req.ip}`
}
}))
app.get('/', (req, res) => {
res.send('authorized');
});
app.listen(3000, () => console.log('server started'));
to return something like:
unauthorized. ip: ::ffff:172.18.0.1
when basic authentication fails.
The function we set unauthorizedResponse to takes the Express request object, so we can use any properties from there in the function.
Challenge
We can make browsers show a popup so that users can enter credentials for authentication by add a challenge: true option to the object.
In addition, we set the realm to identify the system to authenticate against and can be used to save credentials of the challenge by passing a static or a function that gets passed the request object and is expected to return the challenge:
const express = require('express');
const basicAuth = require('express-basic-auth')
const app = express();app.use(basicAuth({
users: { 'admin': 'supersecret' },
challenge: true,
realm: 'foo',
}))
app.get('/', (req, res) => {
res.send('authorized');
});
app.listen(3000, () => console.log('server started'));
With the code above, we should get a dialog box to enter the username and password when we load the / page.
Conclusion
Adding basic auth to an Express app is easy with the express-basic-auth package.
It lets us add a list of valid credentials or use a function to validate credentials.
We can also let users enter the username and password and display custom content when the user is unauthorized.
