37590801?s=460&v=4

A software engineer who dreams about non-electric sheep and autonomous vehicles and likes to champion security.

Software Engineer

Dan Arias

Learn how to use TypeScript and Auth0 to secure a feature-complete Express.js API. Tutorial on how to use Auth0 to implement authorization in Express.

Node.js and TypeScript Tutorial: Secure an Express API

andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn how to build client-server systems by applying the REST architecture principles.

REST Architecture - Part 1: Building The API

vincenzo-chianese

Vincenzo Chianese is an Italian Software Developer focused on Web APIs and User Interfaces. He has been working for the last years in API companies such as Apiary, Oracle, LunchBadger, Stoplight. Currently, he is working for Microsoft to help move Microsoft Graph forward and authored some open-source tools in the market (Prism, Express Gateway).

API Architect

Vincenzo Chianese

Learn how this API gateway, built on Express.js, can help you retain API compatibility with old clients while evolving the product according to new business needs.



**TL;DR:** In this article, you will learn how an API gateway can help you retaining API compatibility with **old** clients while _evolving_ the product according to the new needs of your business. If needed, you can find [the code shown here in this GitHub repository](https://github.com/XVincentX/apigateway-playground/tree/gateway-request-response-modification).

<include src="TweetQuote" quoteText="Learn how to keep your APIs backward compatible while being able to implement new features, fix bugs, and so on."/>

---

## Why Do I Need Backward-Compatible APIs?

Systems evolve continuously, and so do their WebAPIs. As they represent the interface for external clients to interact with your system, they're the first line **reflecting changes** in your organization.

Such API changes can happen for a number of reasons. Technological advancements, change in the line of business, important bug fixes, and so on.

Chances are these needs can end up introducing **breaking** changes in your WebAPI, which in turn means **breaking your clients**. Usually, to make these clients operational again, you will need to make changes to their source code and you will need to release new versions of them.

Sometimes, changes are **inevitable** and you need to deal with them in a way or in another. However, there's an entire class of problems that can be handled in a different way rather than breaking your API.

Among the possible solutions, you can:

1. Use a [Hypermedia API](https://medium.com/unexpected-token/how-your-api-could-benefit-from-hypermedia-b62780771ccb) that, with the forewords of putting the understanding in the runtime instead of sharing it ahead of the time, is prepared by definition to handle changes. Clients, if correctly coded, can handle such intrinsic changes in a non-breaking way and adjust the user experience accordingly.
2. Employ an [API Gateway][express-gateway] to retain the old compatibility while rolling out the new changes. This is a simple, yet effective, way to mask the internal changes of your services while keeping the same interface. In such way, you can extend the runaway of your API while evolving your services. Think about it as the WebAPI version of the [adapter pattern](https://en.wikipedia.org/wiki/Adapter_pattern).

In this article, you're going to explore the second approach. However, keep in mind that Hypermedia APIs are a good solution and that big companies have been employing such approach for ages.

![How an Express gateway works.](https://images.ctfassets.net/23aumh6u8s0i/7Ghx1UORjLYzZkATKmCtNb/3912c09624d91813c91bfca8d7a7fc9c/express-gateway)

## Express Gateway to the Help

It turns out [Express Gateway][express-gateway] is a **perfect** candidate for such task. In this example, you will learn two important things:

- how you can change the shape of a request's body coming into a service;
- and how you can modify the response body to keep the same interface exposed to the clients.

### Depicting the Problem

Imagine a simple use case where keeping an API compatibility with the clients is important (probably any note-worthy app needs this). Suppose you have a service, coded by your internal development team, that exposes an API able to return a customer by its ID on HTTP GET requests. The response would be similar to this:

```json
{
  "customerId": "123456789",
  "name": "Clark",
  "surname": "Kent"
}
```

Also, your API would accept new customers with a `POST` request using the following payload:

```json
{
  "name": "Clark",
  "surname": "Kent"
}
```

This operation would then return the created customer with a generated `customerId` and the operator that created such user:

```json
{
  "customerId": "123456",
  "createdBy": "vncz"
}
```

Suppose now that, given your business is growing, you decide that it makes sense to **replace your homemade customer service** with a third-party cloud service that's offering better customer management capabilities that perfectly fits your company needs.

Most likely, the offered API, as well as the provided features, will differ in multiple parts. For example, the URL space is going to be different as well as the accepted and returned payloads.

In this example, suppose the new service has an endpoint on `/v1/cust` (instead of `/customers`) and, instead of accepting a `name` and `surname` properties, it requires a unique `fullname` property. Also, as it's an external service, it does not include any `createdBy` property, as it's a property that exists exclusively in your system.

While these changes most likely make sense for your internal clients (due to business requirements for example), your existing third-party clients do not care that much about this change. So, while willing to migrate at a certain point in the future, flipping directly the switch would not be an option.

### Keeping the Legacy API Intact Using Express Gateway

It turns out that an [API Gateway][express-gateway] can solve this problem for you. Being an intermediate layer between the public interface **AND** the internal services, an Express Gateway can manipulate the requests and the responses during their journey.

Here's what you would need to do to set up a gateway:

- You would need to configure the [`proxy`][proxy] policy so that the request to the old endpoint get routed to the new, correct internal services.
- You would need to configure the `bodyModifier` policy to modify the request's body so that the new customer service can consume it. In the same way, you would use the same policy this time to modify the response object to make sure the `createdBy` property is correctly added.

### Installing Express Gateway

To solve these problems with Express Gateway, you would install and use a beta version of the framework. This version will most likely land in the `master` branch (thus as an official version) soon (the team supporting Express Gateway is still in the process of discussing some internal requirements, so they weren't able to make it happen officially yet).

```bash
npm install expressgateway/express-gateway#feat/proxy-events
```

### Set up Pipelines to Proxy Objects Back and Forth

Then, after installing this beta version, you would set up two pipelines that would proxy the requests to the new `/cust/v1` endpoint:

```yaml
apiEndpoints:
  customers:
    path: '/customers*'
serviceEndpoints:
  v1Cust:
    url: 'https://cool.Cloud.service/v1/cust'
policies:
  - proxy
  - bodyModifier
pipelines:
  customers:
    apiEndpoints:
      - customers
    policies:
      - proxy:
        - action:
            serviceEndpoint: v1Cust
```

### Using Express Gateway to Change the Request and Response Body

After that, you would use the `bodyModifier` policy to modify request/response payloads so they conform to the new service API.

```yaml
      - bodyModifier:
        - action:
            request:
              add:
                - name: fullname
                  value: "req.body.name + ' ' + req.body.surname"
              remove:
                - name: name
                - name: surname
            response:
              add:
                - name: createdBy
                  value: "req.user.id"
```

It should be easy to understand what's going on in the configuration above. This is concatenating the `name` and `surname` properties from the current request body and forming a new `fullname` property out of it. Once that's done, it removes these properties as they're not required by the new service.

Then, this configuration is performing a similar task for the response. That is, it is adding back the `createdBy` property based on the current user registered in the gateway.

If you put your system up now, you would be able to test the new features with the following command:

```bash
curl -X POST http://localhost:9876/customers/ -H "Content-Type: application/json" -d '{"name":"Clark", "surname": "Kent"}'
```

The system, despite the code changes in the internal service, would still be working (and, more importantly, responding) in the same way it did before.

<include src="asides/ExpressGateway" />

## Conclusions

It is important to note that this approach would keep the whole object in memory and would be taking the burden of parsing it. In case of huge payloads (several MBs), a more efficient way would be to parse the content as a stream, using [JSONStream](https://github.com/dominictarr/JSONStream) for example. This article won't explore this solution, but it should be the way to go in case you're expecting huge JSON objects. For small payloads the JSON parsing, although sync, the default solution wouldn't take more than 1ms.

<include src="TweetQuote" quoteText="Tools like Express Gateway can be life savers when developing apps based on the microservice approach."/>

[express-gateway]: https://express-gateway.io
[proxy]: https://express-gateway.io/docs/policies/proxy


Keep API Backward Compatibility with Express Gateway

001c9ddc5ceb9829b6aaf24f5d28502a

I am software developer with a keen interest in open-source technologies, Linux, and native development. I've worked on many different platforms Android, iOS, Win32, Linux, FreeRTOS, the Web, and others. I've gone through the whole stack and I enjoy learning and using the latest technologies. I now work as a full-stack developer at Auth0.

Senior Engineer

Sebastian Peyrott

Learn how to easily add 2FA/MFA to your Node.js + Express.js apps using TOTP


-----

Authentication has increasingly become an important part of all web applications and sites. Long gone are the days of applications that simply performed an action without getting any details about the identity of the user who performed the actions. In this post, we will explore one of the most powerful (and easiest) ways of improving the security of your authentication process: two-factor authentication (2FA / MFA).

-----

## Two-factor authentication
2FA has become quite popular. As you may have guessed, it works by providing an additional layer of authentication that is independent of the main layer. Most applications make use of the usual username + password combination, though any two independent authentication methods may be combined. In the following paragraphs, we will explore one authentication method that has become popular for use as the second step in 2FA: the time-based one-time password algorithm (TOTP).

## Time-based one-time password algorithm
TOTP is defined in [RFC 6238](https://tools.ietf.org/html/rfc6238). It is free and simple. There are many open-source implementations for both the client-side and server-side components. In particular, Google has developed an application that is freely available for Android, iOS and the web: Google Authenticator. This application allows us to integrate TOTP easily into our developments. We will explore how to do so in the following sections, but first I'll give you a quick summary of TOTP and how it usually works in two steps:

1. **Enrollment:** enabling 2FA for a specific user.
2. **Login:** using 2FA to log in.

![Typical 2FA flowchart](https://images.ctfassets.net/23aumh6u8s0i/33T9WITUHdahRvXb4ynlQq/69bb42ab3847e6f6fcc9396d9eee5359/Flowchart.png "Typical 2FA flowchart")

As you may have gathered from the chart above, the main requirement for TOTP to work is a **shared secret**. This shared secret needs to be generated and then stored by both the client- and the server-side components of the system. This usually means that an "enrollment" step is necessary before making TOTP available in an application.

Another important thing to keep in mind, as the name of the algorithm implies, the generated codes are time-dependent. The **client and the server need to synchronize their clocks**, and the codes become invalid after a certain amount of time.

## Adding TOTP to your Node.js application
As you have seen in the previous chart, adding 2FA with TOTP to an application requires two independent steps. In our example, the second step (the actual authentication) will be handled by passport-totp, a passport.js strategy that validates the user-entered TOTP code and requires access to the user-specific key. We will also require users to install Google Authenticator (or a similar app) to generate codes with their cellphone. A user may also choose to use the Google Authenticator Chrome app.

You can find all the code from the following snippets here: [app.js](https://github.com/sebadoom/auth0/blob/master/twofa/backend/app.js)

### Step one: enrollment
In our example, the first step will be handled manually by us. We will add code to generate a new random key and store it along with other user authentication information.

After the usual passport.js and express.js setup, we add the necessary TotpStrategy:

```javascript
passport.use(new TotpStrategy(
    function(user, done) {
        // The user object carries all user related information, including
        // the shared-secret (key) and password.
        var key = user.key;
        if(!key) {
            return done(new Error('No key'));
        } else {
            return done(null, base32.decode(key), 30); //30 = valid key period
        }
    })
);
```

As usual, passport will call this callback with the actual 'user' object as deserialized from the request. The 'user' object contains a 'key' string that may be null. If the key is null, we will consider TOTP disabled and allow logins with just a username and password. If the key is present, we will require an additional input from the user before proceeding with the login. The key must be provided to passport as a byte array, but for convenience (and because Google Authenticator requires so), we store it as a BASE32 encoded string. The 'period' is the amount of time a single TOTP code is valid from the moment it is requested to the moment it is entered.

The enrollment step requires the user to be already logged in (as this is necessary to enable or disable TOTP in the server for each specific account). If the user chooses to enable TOTP, we present the shared secret as a QR code ready to scan and save in Google Authenticator:

```javascript
app.get('/totp-setup',
    isLoggedIn,
    ensureTotp,
    function(req, res) {
        var url = null;
        if(req.user.key) {
            var qrData = sprintf('otpauth://totp/%s?secret=%s',
                                 req.user.username, req.user.key);
            url = "https://chart.googleapis.com/chart?chs=166x166&chld=L|0&cht=qr&chl=" +
                   qrData;
        }

        res.render('totp-setup', {
            strings: strings,
            user: req.user,
            qrUrl: url
        });
    }
);

app.post('/totp-setup',
    isLoggedIn,
    ensureTotp,
    function(req, res) {
        if(req.body.totp) {
            req.session.method = 'totp';

            var secret = base32.encode(crypto.randomBytes(16));
            //Discard equal signs (part of base32,
            //not required by Google Authenticator)
            //Base32 encoding is required by Google Authenticator.
            //Other applications
            //may place other restrictions on the shared key format.
            secret = secret.toString().replace(/=/g, '');
            req.user.key = secret;
        } else {
            req.session.method = 'plain';

            req.user.key = null;
        }

        res.redirect('/totp-setup');
    }
);
```

If the user chooses to enable TOTP, we generate a new secret key randomly. Then we encode it in BASE32 format for easy storage and to show it to the user. The 'ensureTotp' middleware makes sure that if 2FA is enabled, then the user has logged in using a TOTP code (see below for the implementation).

### Step two: a new authentication step
Once 2FA is enabled, logins will now have two steps: a username and password will be required as usual, and then, a six-digit code will be input, which the user will need to get from Google Authenticator every time he or she wants to login. So, we will add the necessary code to perform the login and allow the user to enter the code after the first step is complete.

#### Logins are now performed in two steps if the user has 2FA enabled

```javascript
app.post('/login',
    passport.authenticate('local', { failureRedirect: '/login' }),
    function(req, res) {
        if(req.user.key) {
            req.session.method = 'totp';
            res.redirect('/totp-input');
        } else {
            req.session.method = 'plain';
            res.redirect('/totp-setup');
        }
    }
);
```

After the usual username + password authentication, we check whether a TOTP code is required. If so, we redirect the user to the "totp-input" page. Otherwise we send him or her to the usual place after logging in (in this case, for simplicity, we just keep a totp-setup page as the landing page after a successful login). Keep in mind that all places that require authentication need to check for both the standard login and the TOTP login (which is optional) for this to be secure. For instance:

```javascript
app.get('/totp-setup',
    isLoggedIn,
    ensureTotp,
    function(req, res) {
        var url = null;
        if(req.user.key) {
            var qrData = sprintf('otpauth://totp/%s?secret=%s',
                                 req.user.username, req.user.key);
            url = "https://chart.googleapis.com/chart?chs=166x166&chld=L|0&cht=qr&chl=" +
                   qrData;
        }

        res.render('totp-setup', {
            strings: strings,
            user: req.user,
            qrUrl: url
        });
    }
);
```

And here are the implementations of the middleware elements that perform the check:

```javascript
function isLoggedIn(req, res, next) {
    if(req.isAuthenticated()) {
        next();
    } else {
        res.redirect('/login');
    }
}

function ensureTotp(req, res, next) {
    if((req.user.key && req.session.method == 'totp') ||
       (!req.user.key && req.session.method == 'plain')) {
        next();
    } else {
        res.redirect('/login');
    }
}
```

As you can see, for the TOTP check, we make use of a helper variable ('method') inside the session. Session information is stored on the server, so this is safe to do. The client just keeps a session ID. This extra session variable is set in the login handler (POST), which we have shown above.

## Is this production ready?
In the previous paragraphs we covered the basics of 2FA. Here's what you need to keep in mind when going into production:

- **Phone or device unavailable:** Consider what happens when users lose access to their code-generating device or application (or shared-secret). Provide a means for users to recover access to their account without compromising security (email links, SMS messages, etc.).
- **Reset 2FA from backend:** Depending on your use case, it may be necessary to add the means to disable or reset 2FA data directly from the backend. Usually, this is accomplished by requiring the user to perform the enrollment step one more time after login.
- **Fallback for people who don't have smartphones:** If a user chooses not to use a smartphone, any of the recovery methods may be enabled indefinitely.
- **Audit and notify users of changes:** Provide convenient ways for users to see if the authentication details (or methods) have been changed or enabled in their accounts. This allows for early detection of suspicious activity. Automated emails are a good choice.
- **Encrypt shared secrets**: Per [RFC 6238](https://tools.ietf.org/html/rfc6238#section-5), you should store shared-secrets using a cryptographically secure reversible algorithm and keep the keys in memory only as long as necessary. Do not reinvent the wheel; use existing and well-tested libraries for this.

<include src="TweetQuote" quoteText="Shared secrets should be stored using a cryptographically secure reversible algorithm"/>

## Conclusion
We showed in this blog post how easy it is to get started with 2FA using TOTP. It does not require a lot of infrastructure. Google Authenticator, Microsoft Authenticator, Authy and other TOTP applications are available in multiple platforms which makes adoption easy. But don't forget to take into account the non-happy-path: people reset their phone, it gets lost or stolen, or sometimes they don't even have one.

For simplicity, the code in our example uses a simple JSON file as storage. In production you would normally keep user data in a proper (and secure) database. Get the code: [app.js](https://github.com/sebadoom/auth0/blob/master/twofa/backend/app.js).

## Aside: How it works in Auth0
Auth0 provides convenient [2FA](https://auth0.com/learn/multifactor-authentication) methods that can easily be enabled. Check this out:

![Auth0 2FA](https://images.ctfassets.net/23aumh6u8s0i/wahzDruzjVuI0zcaeFPEq/d40a1eee5aec4843c87524ce82ea5d97/mfa.png "Easy 2FA with Auth0")

- **A Switch Away:** 2FA is enabled with just a toggle. No changes are required to your application.
- **Multiple TOTP Clients:** Auth0 works with various client-side TOTP-generating apps: Google Authenticator, Microsoft Authenticator, Authy, etc.
- **Contextual and Programmable 2FA:** Contextual 2FA: enforce 2FA for users according to your own scripted rules.

Check the [docs](https://auth0.com/docs/mfa) and the [multi factor authentication page](https://auth0.com/learn/multifactor-authentication).


"express.js"