The JHipster API Gateway

JHipster can generate API gateways. A gateway is a normal JHipster application, so you can use the usual JHipster options and development workflows on that project, but it also acts as the entrance to your microservices. More specifically, it provides HTTP routing and load balancing, quality of service, security and API documentation for all microservices.

Architecture diagram

Diagram

HTTP requests routing using the gateway

When the gateways and the microservices are launched, they will register themselves in the registry (using the eureka.client.serviceUrl.defaultZone key in the src/main/resources/config/application.yml file).

The gateway will automatically proxy all requests to the microservices, using their application name: for example, when microservices app1 is registered, it is available on the gateway on the /app1 URL.

For example, if your gateway is running on localhost:8080, you could point to http://localhost:8080/app1/rest/foos to get the foos resource served by microservice app1. If you’re trying to do this with your Web browser, don’t forget REST resources are secured by default in JHipster, so you need to send the correct JWT header (see the point on security below), or remove the security on those URLs in the microservice’s MicroserviceSecurityConfiguration class.

If there are several instances of the same service running, the gateway will get those instances from the JHipster Registry, and will:

Load balance HTTP requests using Netflix Ribbon.
Provide a circuit breaker using Netflix Hystrix, so that failed instances are quickly and safely removed.

Each gateway has a specific “admin > gateway” menu, where opened HTTP routes and microservices instances can be monitored.

Security

JWT (JSON Web Token)

JWT (JSON Web Token) is an industry standard, easy-to-use method for securing applications in a microservices architecture.

JHipster uses the JJWT library, provided by Okta, for implementing JWT.

Tokens are generated by the gateway, and sent to the underlying microservices: as they share a common secret key, microservices are able to validate the token, and authenticate users using that token.

Those tokens are self-sufficient: they have both authentication and authorization information, so microservices do not need to query a database or an external system. This is important in order to ensure a scalable architecture.

For security to work, a JWT secret token must be shared between all applications.

For each application the default token is unique, and generated by JHipster. It is stored in the .yo-rc.json file.
Tokens are configured with the jhipster.security.authentication.jwt.secret key in the src/main/resources/config/application.yml file.
To share this key between all your applications, copy the key from your gateway to all the microservices, or share it using the JHipster Registry’s Spring Config Server.
A good practice is to have a different key in development and production.

OAuth2

This feature is currently in BETA and thus its documentation is not yet complete.

JHipster provides the option to generate a “UAA” (User Account and Authentication) server, based on Spring Security. This server provides OAuth2 tokens for securing the gateway.

You will find all UAA-related information on our specific Using UAA for Microservice Security documentation page.

Then, the gateway uses Spring Security’s JWT implementation to send JWT tokens to the microservices.

Automatic documentation

The gateway exposes the Swagger API definitions of the services it proxifies so you can benefit from all useful tools like Swagger UI and swagger-codegen.

The “admin > API” menu of a gateway has a specific drop-down list, showing the gateway’s API and all the APIs from the registered microservices.

Using this drop-down list, all microservices APIs are automatically documented, and testable from the gateway.

When using a secured API, security tokens are automatically added to the Swagger UI interface, so all requests work out-of-the-box.

Rate limiting

This is an advanced feature that uses Bucket4j and Hazelcast to provide quality of service on microservices.

Gateways provide rate-limiting features, so the number of REST requests can be limited:

by IP address (for anonymous users)
by user login (for logged-in users)

JHipster will then use Bucket4j and Hazelcast to calculate request counts, and will send HTTP 429 (too many requests) errors when the limit is exceeded. The default limit per user is 100,000 API calls per hour.

This is an important feature, to protect a microservice architecture from being flooded by a specific user’s requests.

As the gateway secures the REST endpoints, it has full access to the user’s security information, so it can be easily extended to provide specific rate limits depending on the user’s security roles.

To enable rate limiting, open up the application-dev.yml or application-prod.yml file and set enabled to true:

jhipster:
    gateway:
        rate-limiting:
            enabled: true

Data is stored in Hazelcast, so it is possible to scale gateways as long as the Hazelcast distributed cache is configured, which should work out-of-the-box:

All gateways have Hazelcast configured by default
If you use the JHipster Registry, all instances of a gateway should automatically register themselves in a distributed cache

If you want to add more rules, or modify the existing rules, you need to code them in the RateLimitingFilter class. Examples of modifications could be:

Lowering the limit of HTTP calls
Adding limits per minute or per day
Removing all limits for “admin” users

Access control policy

By default all registered microservices are available through the gateway. If you want to exclude a specific API from being exposed through the gateway, you can use the gateway’s specific access control policy filter. It is configurable using the jhipster.gateway.authorized-microservices-endpoints key in the application-*.yml files:

jhipster:
    gateway:
        authorized-microservices-endpoints: # Access Control Policy, if left empty for a route, all endpoints will be accessible
            app1: /api,/v2/api-docs # recommended dev configuration

For example, if you only want the /api/foo endpoint of microservice bar to be available:

jhipster:
    gateway:
        authorized-microservices-endpoints:
            bar: /api/foo