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.
When the gateways and the microservices are launched, they will register themselves in the registry (using the
eureka.client.serviceUrl.defaultZone key in the
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
For example, if your gateway is running on
localhost:8080, you could point to http://localhost:8080/app1/rest/foos to
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
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.
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
- Tokens are configured with the
jhipster.security.authentication.jwt.secretkey in the
- 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.
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.
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.
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-prod.yml file and set
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
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
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