jimena-garbarino

Jimena is an experienced result and value-oriented programmer with a strong engineering background. She excels with Ruby on Rails, Java, and Scrum development. She has worked in web development for 10+ years in many industries and has a master's degree in software engineering from Universidad de Buenos Aires.

Spring Cloud Developer

Jimena Garbarino

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Google GKE using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Google GKE Using Terraform and Kubernetes

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Azure AKS using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Azure AKS Using Terraform and Kubernetes

matt-raible

Matt Raible is a well-known figure in the Java community and has been building web applications for most of his adult life. For over 20 years, he has helped developers learn and adopt open source frameworks and use them effectively. He's a web developer, Java Champion, and Developer Advocate at Okta. Matt is a frequent contributor to open source and a big fan of Java, IntelliJ, TypeScript, Angular, and Spring Boot. 

Developer Advocate

Matt Raible

This tutorial shows you how to build a microservices architecture with Spring Boot and Spring Cloud.

Java Microservices with Spring Boot and Spring Cloud

This tutorial explains what micro frontends are and how you can use them with Java microservices.

Micro Frontends for Java Microservices

A walk-through of building a microservices architecture with JHipster, Keycloak, Auth0, and Google Kubernetes Engine (GKE) deployment.

Identity in Spring Boot with Kubernetes, Keycloak, and Auth0

deepu-sasidharan

Deepu is a polyglot developer, Java Champion, and OSS aficionado. He mainly works with Java, JS, Rust, and Golang. He co-leads JHipster and created the JDL Studio and KDash. He's a Principal Developer Advocate at Okta. He is also an international speaker and a published author.

Principal Developer Advocate

Deepu K Sasidharan

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Amazon EKS using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Amazon EKS Using Terraform and Kubernetes

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

See how easy it is to integrate Java's powerful backend technologies with the latest frontend libraries using Yeoman + JHipster

<div class="alert alert-success alert-icon">
 <i class="icon-budicon-500"></i>
 <strong>Hey there! We wrote a new and updated version of this blog post that you can find in here: <a href="https://auth0.com/blog/full-stack-java-with-react-spring-boot-and-jhipster/">Full Stack Java with React, Spring Boot, and JHipster</a>.</strong>
</div>

Java's library ecosystem is deep and complex. This is both a blessing and a curse: there are great tools out there, but picking the right combination and setting them up to work together can be quite complex. Furthermore, the depth and breath of many of these libraries makes the getting-started step somewhat hard. [JHipster](http://jhipster.github.io/) comes to the rescue. See how easy it is to get started on your new Java + JavaScript web app with it. Read on!

<include src="TweetQuote" quoteText="Java's library ecosystem is deep and complex. This is both a blessing and a curse."/>

-----

## Introduction: Java in the Modern Web
Java's viability as a web platform is tried and tested. Huge projects, such as Netflix, have been in production mode using Java technologies in the backend for extended periods of time. Although popular technologies such as Node.js, Ruby on Rails and Django have been on the rise among startups and a new generation of developers, Java's benefits are undeniable. Although some may find tried and tested technologies boring, Java remains a safe bet for a big number of use cases. So how does Java fit in the ever changing landscape of web development nowadays?

### Modern web apps: REST and Microservices
The rise of [IaaS](https://en.wikipedia.org/wiki/Infrastructure_as_a_service) and [PaaS](https://en.wikipedia.org/wiki/Platform_as_a_service) solutions has pushed [microservices](https://auth0.com/blog/2015/09/04/an-introduction-to-microservices-part-1/) to the forefront. Familiarity with the web has also made [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) the preferred architectural style. Java's extensive support for all sorts of technologies does not fail in this case. A whole bunch of libraries and frameworks are available to pick from. So what are some of the most popular alternatives?

#### Spring
For a long time, [Spring](https://spring.io/) has been one of the most used frameworks in the Java world. With a strong [inversion-of-control (IoC)](https://en.wikipedia.org/wiki/Inversion_of_control) ideology and a somewhat pervasive reliance on annotations in recent releases, Spring has use cases in nearly any backend application. Spring covers many areas of backend development: authentication/authorization, data access, messaging, transaction management, REST services, testing, among others.

#### Netflix Tools
Netflix has contributed a series of open-source tools based on their necessities. [Eureka](https://github.com/Netflix/eureka/wiki/Eureka-at-a-glance), a service registry and failover service that goes hand-in-hand with microservice-based architectures; [Zuul](https://github.com/Netflix/zuul/wiki), a proxy with dynamic routing; and [Ribbon](https://github.com/Netflix/ribbon/wiki), a load-balancer.

#### Hibernate
[Hibernate](http://hibernate.org/), an implementation of the Java Persistence API, is a popular alternative for object-relational mapping (ORM). Although you may prefer to skip ORM, Java has great support for it.

#### SQL and NoSQL
Popular choices in the SQL camp include [MySQL/MariaDB](https://en.wikipedia.org/wiki/MariaDB) and [PostgreSQL](http://www.postgresql.org/). In the NoSQL camp: [MongoDB](https://www.mongodb.org/) and [Cassandra](http://cassandra.apache.org/) are good alternatives.

Setting up a combination of these libraries, frameworks and tools can be quite bothersome. Let's see how we can do that with JHipster.

## Setup a New Project with JHipster
First, we have to make sure we have all the baseline dependencies: [Java 8](https://java.com/en/download/) and [Node.js](https://nodejs.org/en/).

#### 1. Install JHipster

```sh
npm install yo generator-jhipster
```

It is also a good idea to make sure Gulp and Bower are available:

```sh
npm install gulp bower
```

> You can perform global installations using `npm install -g <package>`.

#### 2. Create a Project

```sh
yo jhipster
```

![JHipster screenshot](https://images.ctfassets.net/23aumh6u8s0i/3GJoD0dvqAPO7uPSV60VAC/1cccdf552ba212a328291e78c4d2851d/jhipster)

You will be asked a series of questions about your project. Most of these are [self explanatory](http://jhipster.github.io/creating-an-app/). There is one question that may not be entirely obvious: monolithic vs microservice application. JHipster makes a hard distinction between applications that bundle frontend and backend components in a single distributable/runnable artifact and applications that don't. As you can imagine, monolithic applications are those that bundle frontend and backend components together. The [microservices profile](http://jhipster.github.io/microservices-architecture/) allows you to build independent components that run in separate instances, usually providing RESTful services. In this case, Netflix Eureka is used to register services and make sure they are running. If these are your first steps developing Java + JavaScript apps, go for the monolithic approach. You will find it simpler, for now.

After all questions are answered, run the boot step. This will make sure all dependencies are installed and you are ready to start working on your app:

```sh
# In case you picked Maven:
mvn spring-boot:run

# In case you picked Gradle:
gradle bootRun
```

#### 3. Fire up Your IDE!
I love [IntelliJ IDEA](https://www.jetbrains.com/idea/). Most Java IDEs can import Maven and Gradle project setups. Open your IDE and point it to your new JHipster project directory.

![Import JHipster project](https://images.ctfassets.net/23aumh6u8s0i/2rprBw9UpYSHWdJGwueJt2/ed9c265b3b1196171b6f5b68348ae567/import)

Additional IDE specific settings may improve your experience. For instance, you may want to setup autocompletion for the frontend libraries if supported. JHipster docs provide details for [Eclipse and IntelliJ IDEA](http://jhipster.github.io/configuring-ide/).

#### 4. Next Steps
The sky is the limit. In general, you will want to create new views, models and controllers and create some sort of mapping between them and other components in your application. JHipster's help does not stop at the project creation stage: it can help you add new components to your existing app. For this, we can create *entities* using `yo jhipster:entity <entityName>`. New entities create database documents or tables, the necessary ORM code, an AngularJS controller (and router and service), a HTML view and tests. In other words, JHipster does all the boilerplate for you.

But there's more. Complex applications usually have many entities and relationships. Keeping track of these can be problematic. Furthermore, designing a coherent architecture can be troublesome without proper visualization tools. Again, JHipster comes to the rescue: [JHipster-UML](http://jhipster.github.io/jhipster-uml/) and [JDL-Studio](http://jhipster.github.io/jdl-studio/). JHipster-UML takes the output from common UML editors (such as Modelio) and generate entities from them. JDL-Studio, on the other hand, is a web-based UML-like visual editor that can create `JDL` files. These files can then be fed to JHipster's entity generator. How cool is that?!

![JHipster's JDL studio](https://images.ctfassets.net/23aumh6u8s0i/4qIrzSGvdooiOSctkqc8dQ/2612d9e791f40faef5ae94ee51fbb9e3/jdl-studio)

Application logic may be more complex than what can be reasonably put inside entities. In this case, separate units of work may be required. These are called [services](http://jhipster.github.io/creating-a-service/) by JHipster. A call to `yo jhipster:service <serviceName>` will create a service stub for you to modify.

You will also want to focus on cross-cutting concerns such as authentication/authorization, logging and monitoring. Fortunately, Spring excels at this thanks to its aspect-oriented design. The base JHipster project has a good example of this in the `LoggingAspect` class.

## Aside: Did you know you can use Auth0 with Java?
JHipster comes with three choices for authentication: standard session based authentication, OAuth2 authentication and JWT authentication. If you know what we do at Auth0, you know we use JWTs everywhere. Therefore, it should come as no surprise to know you can add Auth0 to a JHipster app.

But before getting started a word of caution: JHipster generators write a lot of code for you. In fact, the basic application generated by JHipster sets up a database for authentication when picking JWT as the choice. Therefore, some work is needed to set up Auth0 as the backend. We will use the monolithic base application, using JWT as an auth mechanism. So, let's get started!

<include src="TweetQuote" quoteText="JHipster generators write a lot of code for you."/>

#### 1. Set up Auth0 Lock and its frontend dependencies
As JHipster apps are Angular apps, adding the dependencies is as easy as:

```sh
bower install auth0-lock auth0-angular a0-angular-storage --save
gulp # to automatically update the index.html file.
```

#### 2. Set up Auth0's Java library
If you picked Gradle, open `build.gradle` and add the following dependency:

```Groovy
dependencies {
    compile 'com.auth0:auth0:0.1.1'
    // (...)
}
```

Or, if you picked Maven:

```XML
<dependency>
  <groupId>com.auth0</groupId>
  <artifactId>auth0</artifactId>
  <version>0.1.1</version>
</dependency>
```

#### 3. Set up Auth0 Lock
Create a new app in the [Auth0 dashboard](https://manage.auth0.com) and get the application domain and client id. Then set these in `src/main/webapp/app/app.module.js`:

```JavaScript
angular
    .module('testApp', [
        'ngStorage',
        'tmh.dynamicLocale',
        'pascalprecht.translate',
        'ngResource',
        'ngCookies',
        'ngAria',
        'ngCacheBuster',
        'ngFileUpload',
        'ui.bootstrap',
        'ui.bootstrap.datetimepicker',
        'ui.router',
        'infinite-scroll',
        // jhipster-needle-angularjs-add-module JHipster will add new module here
        'angular-loading-bar',
        'angular-storage', // <---- ADD THIS
        'auth0'            // <---- ADD THIS
    ])
    .config(config)
    .run(run);

// New config function, add it.
function config(authProvider) {
    authProvider.init({
        domain: 'YOUR_AUTH0_DOMAIN',
        clientID: 'YOUR_CLIENT_ID'
    });

    authProvider.on('loginSuccess', function($location, profilePromise, idToken, store, $localStorage) {
        profilePromise.then(function(profile) {
            $localStorage.authenticationToken = idToken;
        });
    });

    authProvider.on('loginFailure', function($location, error) {
        console.log('Login error');
    });

    authProvider.on('authenticated', function($location) {
        console.log('Still authenticated');
    });
}
```

#### 4. Set the right client secret in Application.yml
Open `Application.yml`, find `jhipster.security.authentication.jwt.secret` and set it to the client secret found in your Auth0 dashboard.

```yml
jhipster:
    security:
        authentication:
            jwt:
                secret: YOUR_CLIENT_SECRET
```

#### 5. Show Auth0 Lock when requested
Now, when the user wants to login, rather than show JHipster's custom login form, we will show Auth0 Lock. To do this, edit `login.service.js`. You can find this file at `src/main/webapp/app/components/login/login.service.js`:

```JavaScript
function LoginService ($uibModal, auth, $localStorage, $rootScope) {
    var service = {
        open: open
    };

    var modalInstance = null;
    var resetModal = function () {
        modalInstance = null;
    };

    return service;

    function open () {
        auth.signin({
            authParams: {
                scope: 'openid app_metadata'
            }
        });
    }
}
```

Normally at this point you would set up an Angular HTTP interceptor to add the JWT to each HTTP request. Fortunately this was already done by JHipster. You can see this at `src/main/webapp/app/blocks/interceptor/auth.interceptor.js`.

#### 6. Add roles to your users!
A piece of cake. Go to to the Auth0 dashboard, then go to [rules](https://manage.auth0.com/#/rules). Add a new rule:

```JavaScript
function (user, context, callback) {
  user.app_metadata = user.app_metadata || {};
  // You can add a Role based on what you want
  // In this case I check domain
  var addRolesToUser = function(user, cb) {
    var endsWith = '@admindomain.com';
    if (user.email && (user.email.substring(user.email.length - endsWith.length, user.email.length) === endsWith)) {
      if (!user.email_verified) {
        return callback(new UnauthorizedError('Please verify your email before logging in.'));
      } else {
        return callback(null, user, context);
      }
      cb(null, ['admin']);
    } else {
      cb(null, ['user']);
    }
  };

  addRolesToUser(user, function(err, roles) {
    if (err) {
      callback(err);
    } else {
      user.app_metadata.roles = roles;
      auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
        .then(function(){
          context.idToken['https://admindomain.com/roles'] = user.app_metadata.roles;
          callback(null, user, context);
        })
        .catch(function(err){
          callback(err);
        });
    }
  });
}
```

This rule will make all users with `admindomain.com` emails administrators by adding the `admin` role to their JWT.

> **Note:** Since you are giving the `admin` role to some users, it will be a good idea to require that these users have to [verify their emails before proceeding](https://auth0.com/rules/email-verified).

#### 7. Change the backend to pick the roles from the right key
Go to `TokenProvider.java` and change `getAuthentication` in the following manner:

```Java
public Authentication getAuthentication(String token) {
    Claims claims = Jwts.parser()
        .setSigningKey(secretKey)
        .parseClaimsJws(token)
        .getBody();

    String principal = claims.getSubject();

    // CHANGES START HERE
    String roles = claims.get(AUTHORITIES_KEY, Map.class).get("roles").toString();
    if(roles != null && roles.length() > 0) {
        roles = roles.substring(1, roles.length() - 1);
    }

    Collection<? extends GrantedAuthority> authorities =
        Arrays.asList(roles.split(",")).stream()
            .map(authority -> new SimpleGrantedAuthority("ROLE_" + authority.toUpperCase()))
            .collect(Collectors.toList());    

    return new UsernamePasswordAuthenticationToken(principal, token, authorities);
}
```

As you can see, roles are present in a different key in JHipster example. With the above code, our new roles key works as expected.

Also note that the token is now passed to `UsernamePasswordAuthenticationToken`. This makes it easy to retrieve the id token in the future.

#### 8. Go nuts!
Now its time to wreak havoc. It is up to you to choose what you prefer at this point. JHipster's `UserRepository`, `UserService`, `UserDetailsService`, `AccountResource`, `UserResource` and `UserJWTController` handle logins by fetching user information from a database. You may choose to follow this path by mapping or creating new users in this database with the information provided by Auth0. Or you may choose to remove all this code and settle with a simple proxy to Auth0's user profile service. Whatever you choose, these classes and their respective frontend counterparts will need to be modified. Bear in mind Auth0's Java API does not provide a user list service. In other words, user management as shown by JHipster's sample application cannot be implemented without a database in your backend.

Retrieving the user profile is as easy as:

```Java
@Service //Or some other Spring-enabled entity
public class SomeClass {
    private static final Auth0 auth0 = new Auth0("YOUR_AUTH0_DOMAIN", "YOUR_CLIENT_ID");

    public Request<UserProfile> getUserProfile() {
        SecurityContext securityContext = SecurityContextHolder.getContext();
        Authentication authentication = securityContext.getAuthentication();
        String token = (String)authentication.getCredentials();
        AuthenticationAPIClient client = auth0.newAuthenticationAPIClient();
        return client.tokenInfo(token);
    }
}
```

Using the returned `Request` object is simple enough:

```Java
request.start(new BaseCallback<UserProfile>() {
    @Override
    public void onSuccess(UserProfile u) {
        //u.getId()
        //u.getEmail()
        //u.getName()        
    }
    @Override
    public void onFailure(Auth0Exception error) {
    }
});
```

For simpler use cases there is also `spring-security-auth0`, a library to easily secure request paths using Auth0 and Spring. See the [docs](https://auth0.com/docs/server-apis/java-spring-security) to find if this fits your use case the best. Or <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up</a> and try it yourself!

## Conclusion
Java frameworks are complex beasts. Dependency injection, broad applications, and great flexibility come at a cost: getting started can be quite a burden. Fortunately JHipster can take a lot of that pain away, as long as the choice of preselected tools is what you had in mind. If Angular.js + Spring is your cup of tea, forget about the boilerplate and get started in a few minutes. Try it, you might be pleasantly surprised.

<div class="mv-widget" data-widget="poll" data-id="HJuZF52qot0XaO0wpIP1YT6z1mv" data-width="100%" data-height="auto"></div>
<script src="//d6launbk5pe1s.cloudfront.net/widget.js" async></script>


Easily Generate a Full-Stack Java + JavaScript App with JHipster

joydip-kanjilal

I received the Microsoft MVP award in ASP.NET for six consecutive years from 2007 to 2012. I'm a software architect, author, and speaker. I've more than 25 years of experience in the software industry, with more than 18 years in Microsoft .NET and its related technologies. These days I'm exploring AI and Machine Learning.

Software Architect and Advisor

Joydip Kanjilal

Learn how nanoservices differ from microservices and how to build them with ASP.NET and Azure Functions.

Implementing Nanoservices in ASP.NET Core

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

1097492785caf9ffeebffeb624202d8f?s=200 avatar

1097492785caf9ffeebffeb624202d8f?s=200

Prosper is a great speaker, community leader, open source hacker, technical consultant, and a fervent Developer Advocate. He is a full-stack software engineer who has worked on biometric, health and developer tools. Prosper recently co-founded a startup called Eden that’s focused on improving the quality of lives in Nigeria and currently leads the engineering team. He also co-founded forloop, the largest developer community in Africa.

Former Auth0 Employee

Prosper Otemuyiwa

Lumen is a PHP micro-framework built to deliver microservices and blazing fast APIs. Learn how to build and secure RESTful APIs with Lumen

Developing RESTful APIs with Lumen (A PHP Micro-framework)

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.

Andrea Chiarelli

Learn how to add authentication and authorization to gRPC for microservices in .NET Core.

Securing gRPC-based Microservices in .NET Core

Learn how to build efficient microservices in .NET Core 3.1 by leveraging gRPC.

Implementing Microservices with gRPC and .NET Core 3.1

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

Express Gateway is an API gateway that sits at the heart of any microservices architecture, securing your microservices and exposing them through APIs.



**TL;DR:** In this tutorial, I'll show you how an API gateway can collect application specific metrics for you.
You can get [the code example in this GitHub repository](https://github.com/XVincentX/express-gateway-prometheus-metrics-example).

---

## Introduction

Unless you're building a proof of concept or an application that's not aiming to reach production, you definitely want to add **monitoring** and **metrics** to your system. In this installment, we're going to look how **Express Gateway** can help you to add application specific metrics and expose them through an HTTP endpoint that can be queried by an external service, such as [Prometheus][prometheus-homepage].

<include src="TweetQuote" quoteText="Monitoring and metrics are an important part of your system."/>

## Express Gateway to Rescue

Express Gateway is an API gateway that sits at the heart of any microservices architecture (regardless of what language or platform is being used), **securing** the different pieces and exposing them through **APIs**. All these magic works by using [Node.js](https://nodejs.org), [ExpressJS](https://expressjs.com/), and [Express middleware](https://expressjs.com/en/guide/writing-middleware.html).

![Express Gateway Diagram](https://images.ctfassets.net/23aumh6u8s0i/SsB12EeBdofDnsa69tJzv/26a9fd4972def879fd3181e203d91b11/express-gateway-diagram)

Express Gateway centralizes all the application configuration for the API use case into one YAML (or JSON) file. Within the YAML file there is an easy to understand description of what is configured and how.

Express Gateway entities, like _policies_, _pipelines_, _conditions_, and _actions_ wrap around Express middleware to make it **dynamic**. Any Express middleware can be plugged into Express Gateway to take advantage of its dynamic capabilities. It also features a hot-reload mechanism so you can change its configuration without having to restart the gateway at all.

## Writing a Plugin for Express Gateway

Express Gateway comes with a plugin framework used to extend the Express Gateway core.

The plugin framework enables anyone to take **Express middleware** and integrate them into Express Gateway as plugins. Express Gateway provides a declarative way to take advantage of Express middleware to be driven centrally and executed dynamically.

We're going to leverage such framework in order to build a plugin that'll hook in our HTTP responses and collect the information we need.

### Scaffold a Plugin

A plugin is nothing more than a JavaScript object that you export. It's shape is described in detail [in the documentation][plugin-shape]

```javascript
module.exports = {
  init: function (pluginContext) {

  },
}
```

In our case, we will create a plugin that:

1. Exposes a policy that will hook in the [response][express-response], collecting information in
[Prometheus format][prometheus-format].
2. Extend the [Admin API][admin-api] to expose an additional endpoint that will serve all the collected information.

#### What Metrics Are We Going to Collect?

There are a lot of ways to slice and dice metrics. They may vary according to your needs.

In this example, we will label all the responses that are on the way to the client according to:

* Success/Failed responses (discerned on the status code).
* The status code itself.
* The consumer id (if the request is authenticated).
* The [API Endpoint][apiendpoint] that triggered the Gateway.

#### What format do we expose the metrics?

To leverage the existing tooling around, we will expose the collected metrics in the [Prometheus Text Based Wire Format][prometheus-format]. In this way, we can **leverage the tools** that are already on the space to push and visualize the information, such as [Grafana][grafana].

```javascript
const metrics = require('prom-client');

const statusCodeCounter = new metrics.Counter({
  name: 'status_codes',
  help: 'status_code_counter',
  labelNames: ['type', 'status_code', 'consumer', 'apiendpoint']
});

module.exports = {
  version: '1.0.0',
  policies: ['metrics'],
  init: (pluginContext) => {
    pluginContext.registerAdminRoute((app) => {
      app.get(pluginContext.settings.endpointName, (req, res) => {
        if (req.accepts(metrics.register.contentType)) {
          res.contentType(metrics.register.contentType);
          return res.send(metrics.register.metrics());
        }

        return res.json(metrics.register.getMetricsAsJSON());
      });
    });

    pluginContext.registerPolicy({
      name: 'metrics',
      policy: ({ consumerIdHeaderName }) => (req, res, next) => {
        res.once('finish', () => {
          const apiEndpoint = req.egContext.apiEndpoint.apiEndpointName;
          const consumerHeader = req.header(consumerIdHeaderName) || 'anonymous';
          const statusCode = res.statusCode.toString();
          const responseType = res.statusCode >= 200 && res.statusCode < 300 ? 'SUCCESS' : 'FAILED';
          statusCodeCounter.labels(responseType, statusCode, consumerHeader, apiEndpoint).inc();
        });

        next();
      }
    });
  }
};

```

Let's go through the code and see the relevant parts:

```javascript
const statusCodeCounter = new metrics.Counter({
  name: 'status_codes',
  help: 'status_code_counter',
  labelNames: ['type', 'status_code', 'consumer', 'apiendpoint']
});
```

Here we're declaring a new Prometheus Counter called `status_code` that will track all the responses and categorize
them based on the declared labels (`['type', 'status_code', 'consumer', 'apiendpoint']`):

```javascript
pluginContext.registerAdminRoute((app) => {
  app.get(pluginContext.settings.endpointName, (req, res) => {
    if (req.accepts(metrics.register.contentType)) {
      res.contentType(metrics.register.contentType);
      return res.send(metrics.register.metrics());
    }

    return res.json(metrics.register.getMetricsAsJSON());
  });
});
```

This part of code is registering a new [route][admin-route-plugin] that will expose all the collected metrics. According to the `Accept` header, we're either returning the data in Prometheus format as JSON or in text format. The external tool collecting the data (such as InfluxDB or a Prometheus server) will query this endpoint **periodically** to grab the latest updates.

*Note:* Prometheus also supports [data pushing](https://prometheus.io/docs/instrumenting/pushing/) instead of polling it periodically. If you go in this way, you can **avoid to expose an endpoint** at all. Based on your requirements (such as security) you may opt for this other option.

```javascript
pluginContext.registerPolicy({
  name: 'metrics',
  policy: ({ consumerIdHeaderName }) => (req, res, next) => {
    res.once('finish', () => {
      const apiEndpoint = req.egContext.apiEndpoint.apiEndpointName;
      const consumerHeader = req.header(consumerIdHeaderName) || 'anonymous';
      const statusCode = res.statusCode.toString();
      const responseType = res.statusCode >= 200 && res.statusCode < 300 ? 'SUCCESS' : 'FAILED';
      statusCodeCounter.labels(responseType, statusCode, consumerHeader, apiEndpoint).inc();
    });

    next();
  }
});
```

Then, we export a new policy that will register an event handler once the response is terminated. Here we can now **inspect** all the response as well as request details that will populate our labels.

*Note:* [`egContext`][egcontext] is an Express Gateway specific object that contains additional information on the request that's being handled.

## Put it in production

We have our plugin ready to be used. Now we have to install it in our Gateway and enabled it.

Express Gateway plugins are nothing more than **NPM packages**, so we can simply publish our package to the registry and then install it using the command line.

For this tutorial, I've already published a plugin called `express-gateway-prometheus-metrics-example` with the exact same code we saw above. Hence, we can install the plugin directly by simply typing `eg plugins install express-gateway-prometheus-metrics-example`

*Note:* Express Gateway can also load [plugins inline][inline-load]. This is useful when you want to test them before publishing them. In this case, you could point the `package` property to our `index.js` file.

Now let's modify our [`gateway.config`][gateway-config] and configure a policy that will take advantage of such policy:

```yaml
http:
  port: 8080
admin:
  port: 9876
apiEndpoints:
  api:
    host: '*'
serviceEndpoints:
  httpbin:
    url: 'http://httpbin.org'
policies:
  - proxy
  - metrics
pipelines:
  - name: basic
    apiEndpoints:
      - api
    policies:
      - metrics:
      - proxy:
          - action:
              serviceEndpoint: httpbin
              changeOrigin: true
```

## See it live

Let's spin up the gateway and throw some requests to it:

```bash
$ ab -n 20 http://localhost:8080/
```

Once the command is terminated, we can now query our metrics endpoint to see what happened with such requests:

```bash
$ curl http://localhost:9876/metrics
# HELP status_codes status_code_counter
# TYPE status_codes counter
status_codes{type="FAILED",status_code="502",consumer="anonymous",apiendpoint="api"} 15
status_codes{type="SUCCESS",status_code="200",consumer="anonymous",apiendpoint="api"} 5
```

You can see we received back the Prometheus metrics with all the data we collected.

## Byproduct — Use JSON Schema to validate your parameters

Express Gateway relies on **JSON Schemas** to make sure all the configurations that goes in its funnel it's correct.

You can leverage the same mechanism to specify the **required** parameters, good defaults and **validation** rules for your plugin.

In our case, for instance, it's pretty clear that the Admin API path where the metrics will be exposed is **mandatory**; also we might want to configure the header where the consumer id information is stored.

With these two requirements in mind, we can write something like this:

```javascript
module.exports = {
  version: '1.0.0',
  policies: ['metrics'],
  schema: {
    $id: 'http://express-gateway.io/plugins/metrics.json',
    type: 'object',
    properties: {
      endpointName: {
        type: 'string',
        default: '/metrics'
      }
    }, required: ['endpointName']
  },
  init: function (pluginContext) {
    pluginContext.registerAdminRoute((app) => {
      // admin route code
    });

    pluginContext.registerPolicy({
      name: 'metrics',
      schema: {
        $id: 'http://express-gateway.io/policies/metrics.json',
        type: 'object',
        properties: {
          consumerIdHeaderName: {
            type: 'string',
            default: 'eg-consumer-id'
          }
        }, required: ['consumerIdHeaderName']
      },
      policy: ({ consumerIdHeaderName }) => (req, res, next) => {
        // policy code
      }
    });
  }
};

```

Thanks to this small addition, the gateway will **validate** the provided parameters against the schema and will
refuse to load the plugin if the validation does not pass.

<include src="asides/ExpressGateway" />

## Conclusions

Metrics are **hard**. In a Microservices context, it's even **harder**. In this installment we discovered how to leverage the shared **middleware** (our API gateway) to collect data **without** having to modify the services' code at all, and have a **centralized** way to push and display these.

<include src="TweetQuote" quoteText="Metrics are hard. In a Microservices context, it's even harder. See how Express Gateway and Auth0 can help you with that"/>

[plugin-shape]: https://www.express-gateway.io/docs/plugins/plugin-development/
[express-response]: http://expressjs.com/en/4x/api.html#res
[admin-api]: https://www.express-gateway.io/docs/admin/#markdown
[apiendpoint]: https://www.express-gateway.io/docs/configuration/gateway.config.yml/apiEndpoints/#markdown
[prometheus-format]: https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md
[grafana]: https://grafana.com/plugins?type=datasource
[admin-route-plugin]: https://www.express-gateway.io/docs/plugins/route-development/#exporting-admin-routes-to-plugin
[egcontext]: https://www.express-gateway.io/docs/policies/customization/eg-context/
[inline-load]: https://github.com/XVincentX/express-gateway-prometheus-metrics-example/blob/master/gateway/config/system.config.yml#L9
[gateway-config]: https://www.express-gateway.io/docs/configuration/gateway.config.yml/
[prometheus-homepage]: https://prometheus.io/


Application Specific Metrics with Express Gateway

Express Gateway is an API Gateway that sits at the heart of any microservices architecture, securing your microservices and exposing them through APIs.



**TL;DR:** In this tutorial, I'll show you how an API Gateway can be a great tool when you have multiple
microservices that need to share multiple tasks. You can get the code example [here](https://github.com/XVincentX/apigateway-playground).

---

## Introduction

[Microservices](https://auth0.com/blog/an-introduction-to-microservices-part-1/) is an architectural style with the basic idea of **decomposing** a system in a collection of services, each one implementing a particular capability/feature of the system itself based on business, technical, and other requirements.

[This has several benefits compared to a monolithic approach](https://auth0.com/blog/getting-a-competitive-edge-with-a-microservices-based-architecture/):

* It enables the **continuous delivery** of large, complex applications by deploying the singular pieces **independently**.
* It enables to select the framework and the programming language that you think it's the best for the job. You can use the latest technologies on a microservice while keep the other parts in legacy mode.
* It improves your teams agility, the ability to iterate on a small, focused piece of functionality quickly and to see results.
* It improves the resiliency of your system because a crash of a microservice **does not halt** your entire system (you can gracefully degrade the user experience).

The above points can be summarized with two keywords: **independence** and **isolation**.

This concept has been riding high during the last years with [blog posts](https://auth0.com/blog/tags/microservices/), articles, [websites](http://microservices.io), and even dedicated conferences although this is nothing really new—but rather a culmination of **best practices** in the modern web era, pushed by a tech giant that felt the need almost [ten years ago](http://www.zdnet.com/article/soa-done-right-the-amazon-strategy/).

Most of the time we don't necessarily have the same web scale, but we can benefit anyway from the paradigm of microservices.

## Challenges

The challenge though is that with microservices the knowledge is spread among multiple little pieces. However, on the other hand, the end game of your application is, most of the time, the exposure of what you're building through an **uniform API**.

So, we have two sides of the same coin: on one side, we want to break up our app into a set of services and [evergreen](https://blog.juriba.com/evergreen-it-concept-or-reality) them; on the other, we still want to offer an uniform experience.

Suppose you need to create a `Coffee` order system that will let people, registered as `Customers`, request for a coffee through an `Order`.

After a bunch of meetings, everybody in the company agrees that the `User` and registration part of your application will be written in JavaScript and run on [Node.js](https://nodejs.org/en/), while the `Order` system will be written in Go. Among the technical requirements, you want all the requests must be authenticated and, in order to prevent flooding, you want to put a [rate limiting policy](https://auth0.com/docs/connections/database/rate-limits).

Now, with such requirements, a couple of questions stand:

1. Writing **idiomatic** JavaScript is different than writing idiomatic Go. According to the programming language and the framework you're using the API you're exposing in Go might be **completely** different with regards to the other one exposed from the JavaScript microservice. How do you make sure that the final API—intended as the the whole surface exposed by your application—is _uniform_ and _consistent_?
2. _Rate limiting_, _authentication_, _authorization_, and a bunch of other stuff are things that should be shared across multiple microservices in your organisation. If you re-implement these things in each single microservice, you are **duplicating** the code at first, but more importantly you have two different pieces of software to maintain. This will mean that you will also need to make sure they behave in the same way (that's not trivial, since you could be potentially using two libraries for that).

## Solution

It turns out that, no matter the way you're doing microservices (whether you're dividing your system by business features, by domain, or coming up with a microservice architecture starting from your data), there are parts of them that are sharing functionalities.

[Microservices need a **superglue** and that glue is an **API Gateway**](https://auth0.com/blog/an-introduction-to-microservices-part-2-API-gateway/).

## API Gateway

An _API Gateway_ is a centralized middleware that encapsulates the internal system architecture and provides an API that can be shaped based on real client needs rather than simply returning what the particular microservice is sending you back. These gateways are effectively implementing the [**facade pattern**](https://en.wikipedia.org/wiki/Facade_pattern) in the microservices world.

API Gateway can have other responsibilities such as _authentication_, _monitoring_, _load balancing_, _caching_, _request shaping and management_, and _static response handling_.

## API Gateway in Practice

Let's move from theory to practice and see how to configure an API Gateway to serve our needs.

Let's suppose that we have `Customer` and `Order` microservices listening to `http://customers` and `http://orders` respectively. Using [Docker](https://docker.com) or [Kubernetes](https://kubernetes.io) achieving such scenario should be fairly easy.

We will configure an instance of an API Gateway that will sit on the edge of our system. This gateway will serve as a router for our microservices, but we'll also move some shared logic from the microservices to it. This will enable our applications to focus on the business logic.

This gateway will also throttle all the requests based on clients' IP addresses and make sure that all the
requests are authenticated based on a **JWT** that _Auth0_ is going to provide. [Auth0 will work as our **system of record** for our users](https://auth0.com/blog/360-view-of-customer-by-managing-identity/).

There are multiple API Gateways on the market. Some of them are offered by big software companies as a managed hosted solution and others are open source products. Of course, you can technically write your own solution too, but why reinvent the wheel? Instead, let's take advantage of [Express Gateway](https://express-gateway.io).

## Meet Express Gateway

Express Gateway is an API Gateway that sits at the heart of any microservices architecture (regardless of what language or platform you're using), **securing** the different pieces and exposing them through **APIs**. All these magic works by using [Node.js](https://nodejs.org), [ExpressJS](https://expressjs.com/), and [Express middleware](https://expressjs.com/en/guide/writing-middleware.html).

![Express Gateway Diagram](https://images.ctfassets.net/23aumh6u8s0i/SsB12EeBdofDnsa69tJzv/26a9fd4972def879fd3181e203d91b11/express-gateway-diagram)

Express Gateway centralizes all the application configuration for the API use case into one YAML (or JSON) file. Within the YAML file there is an easy to understand description of how and what is configured.

Express Gateway entities, like _policies_, _pipelines_, _conditions_, and _actions_, wrap around Express middleware to make it **dynamic**. Any Express middleware can be plugged into Express Gateway to take advantage of its dynamic capabilities. It also features an hot-reload mechanism so you can change its configuration without having to restart the gateway at all.

### Hands On

Installing [Express Gateway](https://express-gateway.io) is dead simple:

`~$ npm i -g express-gateway`

This will install the command line `eg` in your system, so you can now bootstrap a new gateway instance:

```shell
~$ eg gateway create
? What\'s the name of your Express Gateway? eg-example
? Where would you like to install your Express Gateway? eg-example
? What type of Express Gateway do you want to create? Getting Started with…
     created package.json
     created server.js
      ...  To start eg-example, run the following commands:
     cd eg-example && npm start
```

Next, change the working directory to `eg-example` (`cd eg-example`) and modify the [`gateway.config.yml`](https://www.express-gateway.io/docs/configuration/gateway.config.yml/) file. This is the file that controls your gateway’s behavior. For a complete configuration reference, you can see the [documentation](http://www.express-gateway.io/docs/).

```yml
http:
  port: 8080
apiEndpoints:
  customers:
    host: customers.company.com
  orders:
    host: orders.company.com
serviceEndpoints:
  customers:
    url: 'http://customers'
  orders:
    url: 'http://orders'
policies:
  - jwt
  - proxy
  - rate-limit
pipelines:
  customers:
    apiEndpoints:
      - customers
    policies:
      - rate-limit:
        - action:
            max: 1
            windowMs: 1000
      - jwt:
        - action:
            secretOrPublicKeyFile: ./key/pubKey.pem
            checkCredentialExistence: false
      - proxy:
          - action:
              serviceEndpoint: customers
              changeOrigin: true
  orders:
    apiEndpoints:
      - orders
    policies:
      - rate-limit:
        - action:
            max: 1
            windowMs: 1000
      - jwt:
        - action:
            secretOrPublicKeyFile: ./key/pubKey.pem
            checkCredentialExistence: false
      - proxy:
          - action:
              serviceEndpoint: orders
              changeOrigin: true
```

Let's go through the main part of the current configuration. The gateway will listen for HTTP requests on port `8080` (you might want to change it to `80` when going into production). Then, we have defined two **pipelines** (one per microservice) where we have enabled the [rate limit policy](https://www.express-gateway.io/docs/policies/rate-limiter) and the
[JWT](https://www.express-gateway.io/docs/policies/jwt) verification policy.

> **Note:** the configuration is shown in a extended form for clarity. However, it can be shortened by using [YAML references](http://blog.daemonl.com/2016/02/yaml.html).

> **Note:** if you want to test this locally, you'll need to make sure that `company.com` domain points to your local machine. This can be achieved by using [`dnsmasq`](http://www.thekelleys.org.uk/dnsmasq/doc.html) or by [modifying your hosts file](https://support.rackspace.com/how-to/modify-your-hosts-file/), putting both `customers.company.com` **and** `orders.company.com` to point to `localhost`. Another alternative would be to manually put the `HOST` header to the correct value while issuing requests.

### Configure the Client and the User in Auth0

Let's now configure Auth0 to work as our **system of record** for users and **issue JWTs** for them. If you don't already have an Auth0 account, <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one now</a>.

From the [Auth0 management dashboard](https://manage.auth0.com/), click on the **APIs** menu item, and then on the **Create API** button. You will need to give your API a name and an identifier. The name can be anything you choose, so make it as descriptive as you want. The identifier will be used to identify your API, this field cannot be changed once set.

For our example, I'll name the API **billings** and identify it as `http://orders`. I'll also leave the signing algorithm as `RS256` and click on the **Create API** button.

![Creating billings API on Auth0](https://images.ctfassets.net/23aumh6u8s0i/2wgySpoX1QsiKHgITJWh11/646b7364760f17fdbb9800a280045c18/create-auth0-api)

Now point your browser to `https://yourAPI.auth0.com/pem` (where `yourAPI` is the Auth0 domain that you chose when creating your account) and download the **public key** file. This is the key that we will
use to verify that the JSON Web Tokens (JWTs) issued by Auth0 are valid. Save it as `pubKey.pem` and place it in the same directory specified in `secretOrPublicKeyFile` parameter of the `jwt` policy (that is, in a directory called `key` in the project root).

The API Gateway has now been configured correctly to handle the scenarios.

### Test Drive

Start the gateway using `npm start` in the project root. Once running, let's try to issue a couple of requests to it:

```shell
$ curl http://customers.company.com:8080 & curl http://customers.company.com:8080
$ [1] 4495
$ Unauthorized
$ [1]+  Done
$ Too many requests, please try again later.
```

You can see that the first request has been denied with `Unauthorized` status. That's because we didn't
provide any JWT with the request, so it didn't go through.

Moreover, the second request has been refused by the rate limiting policy, without event arriving to the
**authentication** phase. Policies are executed following the definition order in the configuration file.

Now grab any HTTP client and let's configure it to start an OAuth 2.0 authorization process against our API hosted in Auth0. We can grab all the necessary parameters going on _Applications_ -> _billings (Test Application)_ -> _Settings_ -> _Advanced Settings_ -> _Endpoints_

In my case, I am going to use `curl`, but you can use the one you prefer:

```bash
curl --request POST \
  --url https://bkrebs.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"my-client-id-copied-from-auth0-application",
    "client_secret":"my-super-secret-copied-from-auth0-application",
    "audience":"http://orders",
    "grant_type":"client_credentials"
}'
```

Now, by simply copying the `access_token` attribute from the response, we will be able to communicate with the API through Express Gateway (you can verify the returned token by using [JWT.io](https://jwt.io/#debugger)). This is the token to be used in order to access the protected resource. So, just try to issue requests making sure that the token is now sent as a `Bearer` Authorization to the endpoint. The response should hopefully be `200`.

```bash
export JWT="ey...the-rest-of-the-token"
curl -H "Authorization: Bearer "$JWT http://customers.company.com:8080
```

## Conclusions

Thanks to [Express Gateway](https://express-gateway.io), we have moved two shared concerns (authentication and rate limiting) from the microservices to a centralized middleware that—no matter how many microservices we're going to have—it is going to behave in a consistent way.

We can now safely remove the code handling that from our microservices and assume that, if they're receiving a request, it's both **authenticated** and it passed the **rate-limit** checks. You now have **guarantees**.

However, this is just the tip of the iceberg.

The benefits of an API Gateway do not stop here. In this example, we've shown how it can make some checks on **inbound** requests, but it can also be used to modify the **outbound** responses.

In the initial part of the article, we were talking about the uniform API. An API Gateway could transform the response coming from a particular microservice so that the returned payload is consistent with the other microservices, even though the original data is shaped in a different way. Hopefully, we will explore this in a future article.

In the meantime, you can see some other interesting use cases on [Express Gateway website](http://www.express-gateway.io/resources/).


API Gateway: the Microservices Superglue

99c4080f412ccf46b9b564db7f482907?s=200 avatar

99c4080f412ccf46b9b564db7f482907?s=200

I'm currently a Senior Developer Advocate at MongoDB. I'm also a Google Developer Expert for Web Technologies and spend most my time giving talks at conferences and meetups, mentoring developers and running workshops, and creating online content to help technology professionals.

Ado Kukic

Learn why identity is the right component to modernize first in your digital transformation journey.



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-500"></i>
  <strong>Forrester Consulting analysis determines that using Auth0 can yield a 548% ROI and $3.7M in identity-related savings. Read the full report: <a href="https://resources.auth0.com/forrester-tei-research-case-study/">Total Economic Impact of Auth0</a>.</strong>
</div>

---

Digital identity is at the core of any application - invisible yet crucial. We often take identity for granted as most of its magic happens behind the scenes. But identity plays a much larger role beyond the login screen for your applications. At a high level, we can break up identity into four distinct components: authentication, authorization, user profile, and security.

![Authentication](https://images.ctfassets.net/23aumh6u8s0i/67qEWKZ4IrYyWu7msBhHo5/d210fc4edddcd5f832727a3c9b3a9b7c/authentication)

## Authentication

Authentication dictates the way a user logs into your application. While in the past, a simple username and password form did the trick, today it is much more complicated. In addition to providing the traditional means of authentication, social connections through providers like Facebook and Twitter, enterprise federation and single sign on (SSO), and even passwordless authentication are becoming the norm. Implementing all of these various types of authentication methods in your application is a tiresome, repetitive, and expensive task.

![Authorization](https://images.ctfassets.net/23aumh6u8s0i/3xJ0fCozdfmFc3brsLnDE0/ccafe0e415bb88c0a1da51ca7b51e933/authorization)

## Authorization

Authorization is tasked with ensuring the right users have the right access at the right time. Admins of your application should easily be able to make system wide changes, while regular users can only make changes to their accounts for example. From small businesses to large enterprises, access has to be fine tuned to ensure that the right users have access. Multiple departments, complex hierarchies and groups, and users moving throughout the system need up to date access to work effectively. Access is very important to making sure your application operates as intended and getting this aspect of identity right can be quite challenging.

![Security](https://images.ctfassets.net/23aumh6u8s0i/1dMwIvLWqoN21PQ790xNGA/9e44b70c1f7b52f8b167b57c528c1a41/user-profile)

## User Profile
The user profile is concerned with the data that your application has collected on each individual user. The better you know your users the better experience and personalization you can provide. With disparate networks and various sets of data floating all around the web, it can be difficult to get a clear understanding of your users, but companies that can will have an upper hand.

![Security](https://images.ctfassets.net/23aumh6u8s0i/3NyEKlPGMbZxGN1IxxIZHR/73722014fa0c8f2b84a9c1058ebd3a64/security)

## Security

Finally, the security part of the modern identity story ensures that user data is protected both in motion and at rest. Security can be looked at through various lenses. The first, starts when a user attempts to login. Protecting user accounts at time of login with multifactor authentication, anomaly detection, and breached password detection are just some of the quick wins that will make your application more secure and stand out from the crowd. Ensuring data is protected at rest, passwords properly encrypted, and adherence to industry standards and certifications are other aspects of security that must be enforced.

## Application Modernization and Identity

Looking at identity as a constantly evolving and unified view of your user base, rather than a one-and-done requirement, will help you understand the importance of this component in your application. Application modernization is the refactoring, repurposing or consolidation of legacy software to align it more closely with current business needs. Whether you call it application modernization, digital transformation, platform refactoring or re-architecting, the need to have a software that meets the needs of your business is a priority. 

[Read our initial application modernization post](https://auth0.com/blog/getting-a-competitive-edge-with-a-microservices-based-architecture/) to learn more about why application modernization is sweeping the software industry. In today’s post, we will look at how you can kickstart your modernization journey by tackling identity first.

Identity has to be done right, not as an afterthought or side project, making it an ideal candidate for a service that needs to be separated out from the legacy behemoth applications. Identity requires ongoing efforts to secure and maintain but expertise is scarce. Much like how you generally wouldn’t build your own database or email platform, identity is best left to experts whose sole job is to ensure that your platform is as safe and secure as it can be, leaving your developers to focus on your organization's core competencies.

![Modern Identity](https://images.ctfassets.net/23aumh6u8s0i/4EeT5pZAOfFGHHwXx5hsUW/247e8b25051cb9454622ce02e68440af/auth0-identity)

## Modern Identity with Auth0

Auth0 is an Identity as a Service provider that takes a completely new approach to providing a modularized, pluggable identity service by simplifying the most complex identity challenges with a powerful, secure, extensible, and easy to integrate platform. Rather than re-inventing the wheel when it comes to identity, leveraging Auth0, can help you reach your goals faster.

Wherever you are in your digital transformation journey, Auth0 can help. Whether you are re-building your legacy application from scratch altogether or going about a phased restructuring of the legacy system, it’s ideal to offload a the critical part of the application, which not your core competency or expertise, externally as a cloud-based service. With Auth0, you can do just this, and the benefits will be immediate including:

* **Code as an asset** - Stop every line of code from becoming a cost center - for maintenance, audit, upgrade and so on. The more you externalize using services, the lesser you actually pay. Auth0 _provides identity as a service, ensuring your identity remains an asset - always_.
* **Ease of deployment and integration** - Auth0 Identity works with any technology stack, language, and framework. Get your identity system up and running quickly within your existing ecosystem, and get back to modernizing the rest of the app.
* **Easy configuration to meet your needs** - Once Auth0 is integrated into your app, adding additional configuration, like multifactor authentication, anomaly detection, or breached password detection, is as easy as flipping a switch.
* **Support for virtually any identity source** - Username and password, social connection, enterprise federation, and single sign on (SSO). Auth0 allows quick and easy integration with any identity source you choose.
* **Flexible deployment** - Your apps are evolving but you still have legacy systems to work with. Auth0 gives you flexible deployment options - our public cloud, a private cloud controlled by Auth0, or, for AWS users, a private deployment in your own cloud.

Implementing a modern identity solution will present many benefits to your business. Providing your users multiple ways to access your application on their terms will lead to increased conversion rates. Having a better understanding of your users will allow you to provide a more personalized and enhanced user experience, increased user efficiency, and better management. Going above and beyond to protect your user data will build trust and loyalty as well.

Your users are not the only ones that will benefit. You will be able to react to market events faster, gain a deeper understanding of your users, and your developers will be able to focus on building software that makes your product stand out. Over 80% of Auth0 customers were able to go to production within two weeks and with over 42 million login transactions processed daily, Auth0 is ready to serve your users today regardless of where you are in your application modernization journey.

## Summary

The question is no longer “should we or shouldn’t we”, but rather “how do we modernize our platform” for current and future needs. The software industry is going through a radical transformation and legacy monolithic applications are no longer compatible with today’s business needs and user expectations. Application modernization is not something that can be achieved overnight and there are many paths to the end goal, but starting with identity is a surefire win-win for both your organization and your users.


The Role of Identity in Application Modernization

The need for application modernization is sweeping the software industry. It’s a challenge to know where to start, but we’ve got the quick wins that will get you on your way to modernization in no time.



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-500"></i>
  <strong>Forrester Consulting analysis determines that using Auth0 can yield a 548% ROI and $3.7M in identity-related savings. Read the full report: <a href="https://resources.auth0.com/forrester-tei-research-case-study/">Total Economic Impact of Auth0</a>.</strong>
</div>

---

Traditionally, companies have built “monolithic” applications that addressed many business needs and intertwined business logic, user interfaces, and other components all in one. As the business grew, so did this application, adding more and more features, becoming harder and harder to maintain, deploy, test, and secure. These types of applications are commonplace today, however present numerous challenges to organizations looking to respond quickly, reliably, and efficiently to today’s changing business needs.

Monolithic applications slow organizations down. Long development cycles, high infrastructure and licensing costs, often single points of failure, and difficulty scaling are just some of the risks and challenges posed by these applications. Not to mention the difficulty of testing and fixing bugs, addressing vulnerabilities in such complex systems, and challenges integrating new technologies into the mix. In short, legacy architectures and monolithic applications are not compatible with today’s business demands.

Application modernization is the refactoring, repurposing or consolidation of legacy software to align it more closely with current business needs. Whether you call it application modernization, digital transformation, platform refactoring, or re-architecting the need to have software that meets the needs of your business is a priority. Nine out of ten decision makers claim that legacy software is keeping them from achieving their goals.

## Transitioning from Legacy Monoliths to Microservices

To remain competitive, organizations of all sizes are realizing that they need to be nimble, evolve fast, and maintain a healthy balance between customer expectations, business needs, and IT agility. Utilizing a microservices based architecture is a growing trend that helps achieve these goals. In this approach, applications are split into small sets of interconnected services based on business capability where each service has a well-defined boundary.

![Microservices](https://images.ctfassets.net/23aumh6u8s0i/18ttZOWoNAUgdI2sbKFdUP/4a46c78d26216ca770eae04087454988/microservices-example)

A good way to think about microservices is to think of them as individual lego pieces that come together to form something useful - like your ideal software. Each microservice can evolve independently based on the changing needs of the business. An easy way for organizations is to utilize SaaS vendors to fill in the feature and functionality gaps that are not core to the business, allowing the development teams to focus on building business value rather than re-inventing the wheel or so to speak.

The benefits of a microservices based architecture are clear. New features and functionality is much faster to develop, test, and deploy. Services can be deployed independent of each other and no single point of failure exists. Developer productivity and IT agility are increased, and the demands of business can be met head on. The challenge however is, knowing where to start.

## App Modernization Done Smart: Go For Quick Wins

Whether you are re-building your legacy application from scratch altogether or going about a phased restructuring of the legacy system, it’s ideal to offload critical parts of your application, which isn’t your core competency or expertise, externally to a cloud-based service. Using out-of-the box solutions will allow you to quickly implement key functionality. Some of the components that range from complex to almost impossible to build in-house but have various Software as a Service solutions are Payment Processing, Messaging, and Identity.

### Payment Processing
Payment systems have seen major disruptions in recent years and users are adapting fast. Whether it’s offering more payment methods such as cryptocurrency or direct debit payments, or ways to pay through contactless payments like Apple Pay or one-click buy, users are becoming accustomed to a seamless checkout experience. Payment processors like Stripe and Zuora are well known for providing payment platforms and APIs for enabling and managing all aspects of accepting payments via the Internet.

### Messaging

Given the number of communications channels available today, getting a consistent message to your users is harder than ever. Messaging is becoming more and more bi-directional and customers are increasingly engaging with organizations through social media, messaging bots, voice activated AI and more. Twilio is an example of a platform that provides messaging and communications services to handle SMS, voice, and other forms of communications to deliver consistent messaging across all channels.

![Identity](https://images.ctfassets.net/23aumh6u8s0i/4FP9tc3RggO7IwmtRgJlMn/9f722f14acd7c5eb5f2cc9783c58fe40/identity)

### Identity

Digital identity is at the core of any application - invisible yet crucial. An application of any nature requires digital identities, to [represent users and other entities interacting with it](https://auth0.com/user-management). With mobility, BYOD, IoT and smart entities becoming essential parts of the digital ecosystem, the “identity” piece of an application now has even more responsibilities and expectations than before.

Identity is complex. There’s username and password authentication, social connections, single sign on, and these are just ways to login. [Multifactor authentication](https://auth0.com/multifactor-authentication), [breached password detection](https://auth0.com/breached-passwords), anomaly detection, securing sensitive data like passwords, and many other topics comprise identity and having your engineers try to build, manage, and secure all these is like expecting an elephant to win a sprint race. You need to use their expertise at the right place.

Auth0 takes a completely new approach to providing a modularized, pluggable identity service by simplifying the most complex identity challenges with a powerful, secure, extensible, and easy to integrate platform. We will cover how Auth0 can solve your identity challenges in an upcoming article on modernizing your applications.

### Conclusion

Legacy monolithic applications are outdated and incompatible with today’s business needs and demands. Whether you are in the planning or re-architecting stage of your digital transformation, utilizing a microservices based approach alongside SaaS vendors is a sure-fire way to get quick wins and stay one step ahead of the competition.

Today’s blog post focused on introducing you to the quick and easy ways to get started on the  transformation from your legacy systems. In an upcoming post, we will dive deeper into how Auth0, as a Identity as a Service provider, can be a trusted partner in your modernization journey by solving your identity challenges and continuing to evolve as you do.


Getting a Competitive Edge with a Microservices Based Architecture

bruno-krebs

I am passionate about developing highly scalable, resilient applications. I love everything from the database, to microservices (Kubernetes, Docker, etc), to the frontend. I find amazing to think about how all pieces work together to provide a fast and pleasurable experience to end users, mainly because they have no clue how complex that "simple" app is.

R&D Content Architect

Bruno Krebs

Spring Boot can leverage any type of applications, not only microservices. Let's build a JSF application with Spring Boot.

Developing JSF applications with Spring Boot

Learn the basics of dependency management and data sharing for microservices architectures

Intro to Microservices, Part 4: Dependencies and Data Sharing

How the service registry works in a microservice-based architecture



In this post in the microservices series we will talk about *the service registry*. In [part 2](https://auth0.com/blog/2015/09/13/an-introduction-to-microservices-part-2-API-gateway/) we discussed the *API gateway*, where we mentioned that services are **registered in a database**. The gateway dispatches requests according to the information contained in that database. Below we will explore how that database is populated and in which way services, clients and the gateway interact with it.

-----

## The service registry
The service registry is a database populated with information on how to dispatch requests to microservice instances. Interactions between the registry and other components can be divided into two groups, each with two subgroups:

1. Interactions between microservices and the registry (registration)
    1. Self-registration
    2. Third-party registration
2. Interactions between clients and the registry (discovery)
    1. Client-side discovery
    2. Server-side discovery

### Registration
Most microservice-based architectures are in constant evolution. Services go up and down as development teams split, improve, deprecate and do their work. Whenever a service endpoint changes, the **registry needs to know about the change**. This is what *registration* is all about: who publishes or updates the information on how to reach each service.

**Self-registration** forces microservices to interact with the registry by themselves. **When a service goes up, it notifies the registry**. The same thing happens when the service goes down. Whatever additional data is required by the registry must be provided by the **service itself**. If you have been following this series, you know that microservices are all about dealing with a *single concern*, so self-registration might seem like an anti-pattern. However, for simple architectures, self-registration might be the right choice.

![Self-registration](https://images.ctfassets.net/23aumh6u8s0i/793utSBFno7ZnfY2JPkHBW/fc270d61c5b71b09820ffb889cdbfc1d/self-registration-diagram)

**Third-party registration** is normally used in the industry. In this case, there is a **process or service that manages all other services**. This process polls or checks in some way which microservice instances are running and it automatically **updates the service registry**. Additional data might be provided in the form of per-service config files (or policy), which the registration process uses to update the database. Third-party registration is commonplace in architectures that use tools such as [Apache ZooKeeper](http://zookeeper.apache.org/) or [Netflix Eureka](https://github.com/Netflix/eureka) and other service managers.

![Third-party-registration](https://images.ctfassets.net/23aumh6u8s0i/1kXBlTgwxs0IHFqGTfwxXL/46d98df79b3262697685eb4c24bb55f8/third-party-registration-diagram)

Third-party registration also provides other benefits. For instance, what happens when a service goes down? A third-party registration service might be configured to provide safe fallbacks for services that fail. Other policies might be implemented for other cases. For instance, the service registry process might be notified of a high-load condition and automatically add a new endpoint by requesting the instantiation of a new microservice-process or VM. As you can imagine, these possibilities are critical for big architectures.

### Discovery
As you can imagine, discovery is the counterpart to registration from the point of view of clients. When a client wants to access a service, it must find out **where the service is located** (and other relevant information to perform the request).

**Client-side discovery** forces clients to **query a discovery service** before performing the actual requests. As happens with *self-registration*, this requires clients to deal with additional concerns other than their main objective. The discovery service may or may not be located behind the API gateway. If it is not located behind the gateway, balancing, authentication and other cross-cutting concerns may need to be re-implemented for the discovery service. Additionally, each client needs to know the fixed endpoint (or endpoints) to contact the discovery service. These are all disadvantages. The one big advantage is not having to code the necessary logic in the gateway system. Study this carefully when picking your discovery method.

![Client-side discovery](https://images.ctfassets.net/23aumh6u8s0i/2IzcnDuO6qsOYF96uP3ron/bdd6cdc6f18ec352928e19f53287f079/client-side-discovery-diagram)

**Server-side discovery** makes the **API gateway handle the discovery** of the right endpoint (or endpoints) for a request. This is normally used in bigger architectures. As all requests are directly sent to the gateway, all the benefits discussed in relation to it apply (see [part 2](https://auth0.com/blog/2015/09/13/an-introduction-to-microservices-part-2-API-gateway/)). The gateway may also implement discovery caching, so that many requests may have lower latencies. The logic behind cache invalidation is specific to an implementation.

<include src="TweetQuote" quoteText="Server-side discovery makes the API gateway handle the discovery of the right endpoint for a request."/>

![Server-side discovery](https://images.ctfassets.net/23aumh6u8s0i/3FHSwwdLeOmBoLV5PvqNUM/07801774d85e25e330c74f01e5716a01/server-side-discovery-diagram)

## Example: A registry service
In [part 2](https://auth0.com/blog/2015/09/13/an-introduction-to-microservices-part-2-API-gateway/) we worked on a simple API gateway implementation. In that example we implemented dynamic dispatching of requests through queries to a service database. In other words, we implemented **server-side discovery**. For this example, we will extend our microservice architecture by working on the **registration** aspect. We will do so in two ways:

1. By providing a simple registration library that any development team can integrate into their microservice to perform **self-registration**.
2. By providing a sample [systemd unit](http://www.freedesktop.org/software/systemd/man/systemd.unit.html) that registers a service during startup or shutdown (**third-party registration** using systemd as a service manager).

> Why systemd? It has become the de-facto service manager in most Linux installations. There are other alternatives for managing your services but all require installation and configuration. For simplicity, we picked the one that comes preinstalled in most distros, and that is systemd.

### A registration library
Our microservice example from previous posts was developed for *node.js*, so our library will be for it as well. Here is the main logic of our library:

```javascript
module.exports.register = function(service, callback) {    
    if(!validateService(service)) {
        callback(new Error("Invalid service"));
    }

    findExisting(service.name, function(err, found) {
        if(found) {
            callback(new Error("Existing service"));
            return;
        }

        var dbService = new Service({
            name: service.name,
            url: service.url,
            endpoints: service.endpoints,
            authorizedRoles: service.authorizedRoles
        });

        dbService.save(function(err) {
            callback(err);
        });
    });
}

module.exports.unregister = function(name, callback) {
    findExisting(name, function(err, found) {
        if(!found) {
            callback(new Error("Service not found"));
            return;
        }

        found.remove(function(err) {
            callback(err);
        });
    });
}
```

Microservices that perform self-registration need to call these functions during startup or shutdown (including abnormal shutdowns). We have integrated this library into our existing microservice example in the following way (set the SELF_REGISTRY variable to any value to enable this function). Startup code:

```javascript
// Standalone server setup
var port = process.env.PORT || 3001;
http.createServer(app).listen(port, function (err) {
    if (err) {
        logger.error(err);
    } else {  
        logger.info('Listening on http://localhost:' + port);

        if(process.env.SELF_REGISTRY) {
            registry.register({
                name: serviceName,
                url: '/tickets',
                endpoints: [ {
                    type: 'http',
                    url: 'http://127.0.0.1:' + port + '/tickets'
                } ],
                authorizedRoles: ['tickets-query']
            }, function(err) {
                if(err) {
                    logger.error(err);
                    process.exit();
                }
            });
        }
    }
});
```

And shutdown code:

```javascript
function exitHandler() {
    if(process.env.SELF_REGISTRY) {
        registry.unregister(serviceName, function(err) {
            if(err) {
                logger.error(err);
            }
            process.exit();
        });
    } else {
        process.exit();
    }
}

process.on('exit', exitHandler);
process.on('SIGINT', exitHandler);
process.on('SIGTERM', exitHandler);
process.on('uncaughtException', exitHandler);
```

### Third-party registration using systemd
Our gateway example reads service information from a Mongo database. Mongo provides a command-line interface that we can use to register services during startup or shutdown. Here is a sample systemd unit (remember to disable the SELF_REGISTRY environment variable if you are using the sample microservice from this post):

```systemd
[Unit]
Description=Sample tickets query microservice

#Uncomment the following line when not running systemd in user mode
#After=network.target

[Service]
#Uncomment the following line to run the service as a specific user
#User=seba

Environment="MONGO_URL=mongodb://127.0.0.1:27018/test"

ExecStart=/usr/bin/node /home/seba/Projects/Ingadv/Auth0/blog-code/microservices/server.js
ExecStartPost=/usr/bin/mongo --eval 'db.services.insert({"name": "Tickets Query Service", "url": "/tickets", "endpoints": [{"type": "http", "url": "http://127.0.0.1:3001/tickets"}], "authorizedRoles": ["tickets-query"] });' 127.0.0.1:27017/test
ExecStopPost=/usr/bin/mongo --eval 'db.services.remove({"name": "Tickets Query Service"});' 127.0.0.1:27017/test

[Install]
WantedBy=default.target
```

Registration is handled by the *ExecStartPost* and *ExecStopPost* directives by calling the command-line Mongo client (included in all standard MongoDB installations).

Get the [code](https://github.com/auth0/blog-microservices-part3).

## Aside: use Auth0 for your microservices
Auth0 and microservices go hand-in-hand thanks to the magic of [JWT](http://jwt.io/). Check it out:

```javascript
var express = require('express');
var app = express();
var jwt = require('express-jwt');

var jwtCheck = jwt({
  secret: new Buffer('your-auth0-client-secret', 'base64'),
  audience: 'your-auth0-client-id'
});

app.use('/api/path-you-want-to-protect', jwtCheck);

// (...)
```

Your *client id* and *client secret* are available through the Auth0 dashboard. Create a new account and [start hacking](https://auth0.com/docs)!

## Conclusion
The service registry is an essential part of a microservice-based architecture. There are different ways of handling registration and discovery that fit different architectural complexities. Consider the pros and cons described above for each alternative before committing to one. In Part 4 we will study service dependencies in detail and how to manage them efficiently.


An Introduction to Microservices, Part 3: The Service Registry

Learn about API gateways and how they work in a microservice-based architecture



In this post in the microservices series we will talk about API gateways and how they can help us solve some important concerns in a microservice-based architecture. We described these and other issues in our [first post](https://auth0.com/blog/2015/09/04/an-introduction-to-microservices-part-1/) in the series.

-----

## What is an API gateway and why use it?

In all service-based architectures there are several concerns that are shared among all (or most) services. A microservice-based architecture is not an exception. As we said in the first post, microservices are developed almost in isolation. Cross-cutting concerns are dealt with by upper layers in the software stack. The API gateway is one of those layers. Here is a list of common concerns handled by API gateways:

- Authentication
- Transport security
- Load-balancing
- Request dispatching (including fault tolerance and service discovery)
- Dependency resolution
- Transport transformations

### Authentication
Most gateways perform some sort of authentication for **each request** (or series of requests). According to **rules** that are specific to each service, the gateway either routes the request to the requested microservice(s) or returns an error code (or less information). Most gateways add authentication information to the request when passing it to the microservice behind them. This allows microservices to implement **user specific logic** whenever required.

### Security
Many gateways function as a single entry point for a public API. In such cases, the **gateways handle transport security** and then dispatch the requests either by using a different secure channel or by removing security constraints that are not necessary inside the internal network. For instance, for a RESTful HTTP API, a gateway may perform **"SSL termination"**: a secure SSL connection is established between the clients and the gateway, and proxied requests are then sent over non-SSL connections to internal services.

<include src="TweetQuote" quoteText="Many gateways function as a single entry point for a public API."/>

### Load-balancing
Under high-load scenarios, gateways can **distribute requests among microservice-instances** according to custom logic. Each service may have specific scaling limitations. Gateways are designed to balance the load by taking these limitations into account. For instance, some services may scale by having multiple instances running under different internal endpoints. Gateways can dispatch requests to these endpoints (or even request the dynamic instantiation of more endpoints) to handle load.

### Request-dispatching
Even under normal-load scenarios, gateways can provide custom logic for dispatching requests. In big architectures, **internal endpoints are added and removed** as teams work or new microservice instances are spawned (due to topology changes, for instance). Gateways may work in tandem with service registration/discovery processes or databases that describe how to dispatch each request. This provides exceptional **flexibility** to development teams. Additionally, **faulty services** can be routed to backup or generic services that allow the request to complete rather than fail completely.

### Dependency resolution
As microservices deal with very specific concerns, some microservice-based architectures tend to become "chatty": to perform useful work, many requests need to be sent to many different services. For convenience and performance reasons, gateways may provide **facades** ("virtual" endpoints) that internally are **routed to many different microservices**.

### Transport transformations
As we learnt in the first post of this series, microservices are usually developed in isolation and development teams have great flexibility in choosing the development platform. This may result in microservices that return data and use transports that are **not convenient for clients** on the other side of the gateway. The gateway must perform the necessary **transformations** so that clients can still communicate with the microservices behind it.

## An API gateway example
Our example is a simple node.js gateway. It handles HTTP requests and forwards them to the appropriate internal endpoints (performing the necessary transformations in transit). It handles the following concerns:

### Authentication
Authentication using **JWT**. A single endpoint handles initial authentication: /login. User details are stored in a Mongo database and access to endpoints is restricted by roles.

```javascript
/*
 * Simple login: returns a JWT if login data is valid.
 */
function doLogin(req, res) {
    getData(req).then(function(data) {
        try {
            var loginData = JSON.parse(data);
            User.findOne({ username: loginData.username }, function(err, user) {
                if(err) {
                    logger.error(err);
                    send401(res);
                    return;
                }

                if(user.password === loginData.password) {
                    var token = jwt.sign({
                        jti: uuid.v4(),
                        roles: user.roles
                    }, secretKey, {
                        subject: user.username,
                        issuer: issuerStr
                    });

                    res.writeHeader(200, {
                        'Content-Length': token.length,
                        'Content-Type': "text/plain"
                    });
                    res.write(token);
                    res.end();                
                } else {
                    send401(res);
                }
            }, 'users');
        } catch(err) {
            logger.error(err);            
            send401(res);
        }
    }, function(err) {
        logger.error(err);            
        send401(res);
    });
}

/*
 * Authentication validation using JWT. Strategy: find existing user.
 */
function validateAuth(data, callback) {
    if(!data) {
        callback(null);
        return;
    }

    data = data.split(" ");
    if(data[0] !== "Bearer" || !data[1]) {
        callback(null);
        return;
    }

    var token = data[1];    
    try {
        var payload = jwt.verify(token, secretKey);
        //Your custom validation logic goes here.
        if(!payload.jti || revokedTokens[payload.jti]) {
            logger.debug('Revoked token, access denied: ' + payload.jti);
            callback(null);
        } else {        
            callback({jwt: payload});                
        }
    } catch(err) {
        logger.error(err);
        callback(null);
    }
}
```

> Disclaimer: the code shown in this post is not production ready. It is used just to show concepts. Don't copy paste it blindly :)

### Transport security
Transport security is handled through **TLS**: all public requests are received first by a reverse nginx proxy setup with sample certificates.

### Load balancing
Load-balancing is handled by **nginx**. See the sample [config](https://github.com/sebadoom/auth0/blob/master/microservices/gateway/nginx.conf).

### Dynamic dispatching, data aggregation and failures
Requests are **dynamically dispatched** according to a configuration stored in a database. Two types of requests are supported: HTTP and AMQP.

Requests also support the **aggregation strategy** for splitting requests among several microservices: a single public endpoint may aggregate data from many different internal endpoints (microservices). All returned data is in JSON format. See this excellent [post by Netflix](http://techblog.netflix.com/2013/01/optimizing-netflix-api.html) on how this strategy helped them achieve better performance. Also check our [post on Falcor](https://auth0.com/blog/2015/08/28/getting-started-with-falcor/) which allows for easy data fetching from many sources.

![Aggregation strategy](https://images.ctfassets.net/23aumh6u8s0i/5czB8vNeCDzOlE0SO9SYif/83a87ab75bd2bbe0a9a7d353ef33613d/aggregation)

**Failed internal requests** are handled by logging the error and returning less information than requested.

```javascript
/*
 * Parses the request and dispatches multiple concurrent requests to each
 * internal endpoint. Results are aggregated and returned.
 */
function serviceDispatch(req, res) {
    var parsedUrl = url.parse(req.url);

    Service.findOne({ url: parsedUrl.pathname }, function(err, service) {
        if(err) {
            logger.error(err);
            send500(res);
            return;
        }

        var authorized = roleCheck(req.context.authPayload.jwt, service);
        if(!authorized) {
            send401(res);
            return;
        }       

        // Fanout all requests to all related endpoints.
        // Results are aggregated (more complex strategies are possible).
        var promises = [];
        service.endpoints.forEach(function(endpoint) {   
            logger.debug(sprintf('Dispatching request from public endpoint ' +
                '%s to internal endpoint %s (%s)',
                req.url, endpoint.url, endpoint.type));

            switch(endpoint.type) {
                case 'http-get':
                case 'http-post':
                    promises.push(httpPromise(req, endpoint.url,
                        endpoint.type === 'http-get'));
                    break;
                case 'amqp':
                    promises.push(amqpPromise(req, endpoint.url));
                    break;
                default:
                    logger.error('Unknown endpoint type: ' + endpoint.type);
            }            
        });

        //Aggregation strategy for multiple endpoints.
        Q.allSettled(promises).then(function(results) {
            var responseData = {};

            results.forEach(function(result) {
                if(result.state === 'fulfilled') {
                    responseData = _.extend(responseData, result.value);
                } else {
                    logger.error(result.reason.message);
                }
            });

            res.setHeader('Content-Type', 'application/json');
            res.end(JSON.stringify(responseData));
        });
    }, 'services');
}
```

### Role checks
```javascript
var User = userDb.model('User', new mongoose.Schema ({
    username: String,
    password: String,
    roles: [ String ]
}));

var Service = servicesDb.model('Service', new mongoose.Schema ({
    name: String,
    url: String,
    endpoints: [ new mongoose.Schema({
        type: String,
        url: String
    }) ],
    authorizedRoles: [ String ]
}));

function roleCheck(jwt_, service) {
    var intersection = _.intersection(jwt_.roles, service.authorizedRoles);
    return intersection.length === service.authorizedRoles.length;
}
```

### Transport and data transformations
**Transport transformations** are performed to convert between HTTP and AMQP requests.

### Logging
**Logging** is centralized: all logs are published to the console and to an internal message-bus. Other services listening on the message-bus can take action according to these logs.

Get the full [code](https://github.com/sebadoom/auth0/tree/master/microservices/gateway).

## Aside: How webtask and Auth0 implement these patterns?

We told you about [webtasks](https://webtask.io) in our first post in the series. As webtasks *are* microservices they too run behind a gateway. The webtasks gateway handles authentication, dynamic-dispatching and centralized logging so that you don't have too.

* For authentication, [Auth0](https://auth0.com) is the issuer of tokens and webtask will verify those tokens. There is a trust relationship between them so that tokens can be verified.
* For real time logging webtask implemented a stateless resilient [ZeroMQ architecture](http://tomasz.janczuk.org/2015/09/from-kafka-to-zeromq-for-log-aggregation.html) which works across the cluster.
* For dynamic-dispatching, there is a custom-built Node.js proxy which uses [CoreOS etcd](https://github.com/coreos/etcd) as a pub-sub mechanism to route webtasks accordingly.

![Webtask](https://images.ctfassets.net/23aumh6u8s0i/26xA1D0RD9OZNmwuVPCCFw/6395ac83c869db331a701848bfa0e59f/webtask)

## Conclusion
API gateways are an essential part of any microservice-based architecture. Cross-cutting concerns such as authentication, load balancing, dependency resolution, data transformations and dynamic request dispatching can be handled in a convenient and generic way. Microservices can then focus on their specific tasks without code-duplication. This results in easier and faster development of each microservice.


API Gateway. An Introduction to Microservices, Part 2

Learn what are microservices and how they are used in the industry



Everybody is talking about microservices. Industry veterans may remember monolithic or SOA-based solutions being *the way* of doing things. Times have changed. New tools have allowed developers to focus on specific problems without adding excessive complexity to deployment or other administrative tasks that are usually associated with isolated services. It has become increasingly easy to choose to work with the right tool for the right problem.

In this **post series**, we will explore the world of microservices, how it can help solve real world problems, and why the industry is increasingly picking it as the standard way of doing things. In this series, we will attempt to tackle common problems related to this approach, and provide convenient and simple examples. By the end of the series, we should have a skeleton implementation of a full microservice-based architecture. Today, we will focus on what microservices are and how they compare to the alternatives. We will also list the problems we plan to discuss in the following posts.

**Update:** in [part 2](https://auth0.com/blog/2015/09/13/an-introduction-to-microservices-part-2-API-gateway/) we talk about the *API gateway*.

-----

## What is a microservice?
A microservice is an **isolated**, **loosely-coupled** unit of development that works on a **single concern**. This is similar to the old "Unix" way of doing things: do one thing, and do it well. Matters such as how to "combine" whatever is provided by the service are left to higher layers or to policy. This usually means that microservices tend to avoid interdependencies: if one microservice has a hard requirement for other microservices, then you should ask yourself if it makes sense to make them all part of the same unit.

<include src="TweetQuote" quoteText="A microservice is an isolated, loosely-coupled unit of development that works on a single concern."/>

![Typical microservices diagram](https://images.ctfassets.net/23aumh6u8s0i/7m1asvRD6piucFe4KV8F0M/c029abc6718f31599e602fdd133c057d/Microservices2)

What makes microservices particularly attractive to development teams is their **independence**. Teams can work on a problem or group of problems on their own. This creates several attractive qualities favored by many developers:

- **Freedom to pick the right tool**: Is that new library or development platform something you always wanted to use? You can (if it's the right tool for the job).
- **Quick iteration**: Was the first version suboptimal? No problem, version 2 can be out the door in no time. Because microservices tend to be small, changes can be implemented relatively quickly.
- **Rewrites are a possibility**: In contrast with monolithic solutions, since microservices are small, rewrites are a possibility. Was the technology stack the wrong pick? No problem, switch to the right alternative.
- **Code quality and readability**: Isolated development units tend to be of higher quality and new developers can get up to speed with the existing code fairly easily.

## Production-quality microservices
Now that we know what microservices are, here is a list of things we need to keep in mind when designing our microservice-based architecture. Don't worry if this seems too abstract; we will deal with all these concerns in a systematic way throughout this series of posts.

- **Cross-cutting concerns** must be implemented in a way such that microservices need not deal with details regarding problems outside their specific scope. For instance, authentication can be implemented as part of any API gateway or proxy.
- **Data sharing** is hard. Microservices tend to favor per-service or per-group databases that can be updated directly. When doing data modeling for your application, notice whether this way of doing things fits your application. For sharing data between databases, it may be necessary to implement an internal process that handles internal updates and transactions between databases. It is possible to share a single database between many microservices; just keep in mind that this may limit your options when and if you need to scale in the future.
- **Availability**: Microservices, by virtue of being isolated and independent, need to be monitored to detect failures as early as possible. In a big software stack, one service that goes down may go unnoticed for some time. Account for this when picking your software stack for managing services.
- **Evolution**: Microservices tend to evolve fast. When dedicated teams deal with specific concerns, new and better solutions are found quickly. Therefore, it is necessary to account for versioning of services. Old versions are usually available as long as there are clients who need to consume data from them. Newer versions are exposed in an application-specific way. For instance, with an HTTP/REST API, the version of the microservice may be part of a custom header, or be embedded in the returned data. Account for this.
- **Automated deployment**: The whole reason that microservices are so convenient nowadays is that it is so easy to deploy a new service from a completely clean environment. See Heroku, Amazon Web Services, [Webtask.io](https://webtask.io) or other PaaS providers. If you are going for your own in-house approach, keep in mind that the complexity of deploying new services or versions of preexisting services is critical to the success of your solution. If deployment is not handled in a convenient, automated way, you risk eventually reaching a level of complexity that outweighs the benefits originally brought about by the approach.
- **Interdependencies**: Keep them to a minimum. There are different ways of dealing with dependencies between services. We will explore them further later in this blog post series. For now, just keep in mind that dependencies are one of the biggest problems with this approach, so seek ways to keep them to a minimum.
- **Transport and data format**: Microservices are fit for any transport and data format; however, they are usually exposed publicly through a RESTful API over HTTP. Any data format fit for your information works. HTTP + JSON is very popular these days, but there is nothing stopping you from using protocol-buffers over AMQP, for instance.

### Doing things right
All of these concerns can be dealt with in a systematic way. We will explore techniques and patterns in this post series to deal with them. Here is what we will be talking about in future posts:

- **API proxying**
- **Logging**
- **Service discovery and registration**
- **Service dependencies**
- **Data sharing and synchronization**
- **Graceful failure**
- **Automated deployment and instantiation**

## Keeping it real: a sample microservice

Now, this should be easy. If microservices take so much baggage off the development team's mind, writing one should be a piece of cake, right? Yes, in a way. While we could write a simple RESTful HTTP service and call that a microservice, in this post we will do it by taking into account some of the things we have listed above (don't worry: in the following posts, we will expand this example to include solutions for ALL the concerns listed above).

For our example, we will pick the backend code from Sandrino Di Mattia's excellent [post](https://auth0.com/blog/2015/08/25/logging-and-debugging-in-react-with-flux-replaying-your-users-actions/) about using Flux for debugging. In Sandrino's post, a simple express.js app makes the backend for a React.js app. We will take that backend and adapt it. You can see the original backend code [here](https://github.com/auth0/react-flux-debug-actions-sample/blob/master/server.js).

The backend in Sandrino's example handles many different concerns: login, authentication, [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), update operations over tickets, and queries. For our microservice we will focus on one task: querying tickets. Check it out:

```javascript
var express = require('express');
var morgan = require('morgan');
var http = require('http');
var mongo = require('mongodb').MongoClient;
var winston = require('winston');

// Logging
winston.emitErrs = true;
var logger = new winston.Logger({
    transports: [
        new winston.transports.Console({
            timestamp: true,
            level: 'debug',
            handleExceptions: true,
            json: false,
            colorize: true
        })
    ],
    exitOnError: false
});

logger.stream = {
    write: function(message, encoding){
        logger.debug(message.replace(/\n$/, ''));
    }
};

// Express and middlewares
var app = express();
app.use(
    //Log requests
    morgan(':method :url :status :response-time ms - :res[content-length]', {
        stream: logger.stream
    })
);

var db;
if(process.env.MONGO_URL) {
    mongo.connect(process.env.MONGO_URL, null, function(err, db_) {
        if(err) {
            logger.error(err);
        } else {
            db = db_;
        }
    });
}

app.use(function(req, res, next) {    
    if(!db) {
        //Database not connected
        mongo.connect(process.env.MONGO_URL, null, function(err, db_) {
            if(err) {
                logger.error(err);
                res.sendStatus(500);                
            } else {
                db = db_;
                next();
            }
        });
    } else {
        next();
    }    
});

// Actual query
app.get('/tickets', function(req, res, next) {
    var collection = db.collection('tickets');
    collection.find().toArray(function(err, result) {
        if(err) {
            logger.error(err);
            res.sendStatus(500);
            return;
        }
        res.json(result);
    });   
});

// Standalone server setup
var port = process.env.PORT || 3001;
http.createServer(app).listen(port, function (err) {
  if (err) {
    logger.error(err);
  } else {
    logger.info('Listening on http://localhost:' + port);
  }
});
```

- **One thing and one thing only**: Our microservice's single concern is querying for the full list of tickets. Nothing more. Authentication, CORS and other concerns are to be handled by upper layers in our architecture.
- **Logging**: We have kept logging using the 'winston' library. For now we will just log to the console, but in later versions we will push logs in a predefined format to a centralized location for analysis.
- **No dependencies**: Our microservice has no dependencies on other microservices.
- **Easily scaled**: With no dependencies, a separate process, and operating on a single concern our microservice can easily be scaled.
- **Small and readable**: Our microservice is small and readable. New developers can modify or rewrite it in no time.
- **Data sharing**: For now our microservice reads data from its own database. We will explore in future posts what happens when other microservices need to update or create tickets.
- **Registration and failure**: Our microservice stands on its own. In future posts we will explore how to manage service discovery and what you can do in case microservices fail.

Get the [code](https://github.com/sebadoom/auth0/tree/master/microservices/microservice-1).

## Conclusion
Microservices are the new way of doing distributed computing. Advances in deployment and monitoring tools have eased the pain involved in managing many independent services. The benefits are clear: using the right tool for the right problem, and letting teams use their specific know-how to tackle each problem. The hard part is dealing with shared data. Special considerations must be taken into account when dealing with shared data and inter-service dependencies. Data modeling is an essential step in any design, and is even more so in the case of a microservices-based architecture. We will explore other common patterns and practices in detail in the following articles.


"microservices"