LIGHT

  • News
  • Docs
  • Community
  • Reddit
  • GitHub
Star

IP Whitelist

API security is very crucial, and it is an essential part of the cross-cutting concerns provided by Light. For business API endpoints, we should use the OAuth 2.0 JWT token to secure them. For some other functional endpoints that cannot be secured by OAuth 2.0, Basic Authentication is an option. For example, one of the users is using Basic Authentication to secure their API deployed on an IoT device.

In release 1.5.18, we provided a new feature that allows multiple chains to be defined in a single API instance. Naturally, the /server/info and /health endpoints are separated from the business endpoints so that they can use different middleware handler chains. It has been asked by our customers for a long time to bypass the OAuth 2.0 security check for a health check endpoint so that the orchestration layer can access it without providing a token. In most deployments, Consul is used for service registry, and discovery and the /health is periodically accessed from Consul to ensure the service is up and running. It is not very convenient to use JWT or even Basic Authentication in this use case. Since most Consul servers are deployed in physical machines or VMs with fixed IP addresses. It would be great if we can support the IP whitelist for the /health endpoint. After several hours of hard work, the ip-whitelist middleware handler was born.

Requirements

  • The IP whitelist must be defined per endpoint which is the path and method combination.
  • Both IPv4 and IPv6 should be supported.
  • Need to support the different format of IP addresses. For example, exact, wildcard, slash.
  • Users can specify if access is allowed for the endpoints without IP whitelist defined.

Implementation

The implementation is a middleware handler and it can be plugged into any API with whitelist.yml and handler.yml configuration files.

The majority of the logic is in the WhitelistConfig class which is responsible for loading the configuration and parsing the rules into an object that can be leveraged during the runtime.

Since we are supporting both IPv4 and IPv6, the address must be parsed with a pattern to differentiate the format. When checking the ACLs in the handler, both IPv4 rules and IPv6 rules will be iterated.

Configuration

Here is an exmaple for the whitelist.yml file. The default config in the module has enabled set as false. So you have to externalize it in order to use it in your own application.

# IP Whitelist configuration
---
# Indicate if this handler is enabled or not
enabled: true

defaultAllow: true

paths:
  # For a particular endpoint([email protected]), there are three IPs can access
  '/health/[email protected]':
  # IPv4 Exact
  - '127.0.0.1'
  # IPv4 Wildcard
  - '10.10.*.*'
  # IPv4 Slash
  - '127.0.0.48/30'

  # For a path, the following IP can access regardless the method
  '/[email protected]':
  # IPv6 Exact
  - 'FE45:00:00:000:0:AAA:FFFF:0045'
  # IPv6 Prefix
  - 'FE45:00:00:000:0:AAA:FFFF:*'
  # IPv6 Slash
  - 'FE45:00:00:000:0:AAA:FFFF:01F4/127'

  # For a particular endpoint([email protected]), there are three IPs can access
  '/[email protected]':
  # IPv4 Exact
  - '127.0.0.2'
  # IPv4 Wildcard
  - '10.10.*.*'
  # IPv4 Slash
  - '127.0.0.48/30'

Error Messages

If the whitelist ACL is allowed, then the next handler will be called. Otherwise, an error status will be returned to the caller.

ERR10049:
  statusCode: 403
  code: ERR10049
  message: INVALID_IP_FOR_PATH
  description: Peer IP %s is not in the whitelist for the endpoint %s

  • About Light
    • Overview
    • Testimonials
    • What is Light
    • Features
    • Principles
    • Benefits
    • Roadmap
    • Community
    • Articles
    • Videos
    • License
  • Getting Started
    • Get Started Overview
    • Environment
    • Light Codegen Tool
    • Light Rest 4j
    • Light Tram 4j
    • Light Graphql 4j
    • Light Hybrid 4j
    • Light Eventuate 4j
    • Light Oauth2
    • Light Portal Service
    • Light Proxy Server
    • Light Router Server
    • Light Config Server
    • Light Saga 4j
    • Light Session 4j
    • Webserver
    • Websocket
    • Spring Boot Servlet
  • Architecture
    • Architecture Overview
    • API Category
    • API Gateway
    • Architecture Patterns
    • CQRS
    • Eco System
    • Event Sourcing
    • Fail Fast vs Fail Slow
    • Integration Patterns
    • JavaEE declining
    • Key Distribution
    • Microservices Architecture
    • Microservices Monitoring
    • Microservices Security
    • Microservices Traceability
    • Modular Monolith
    • Platform Ecosystem
    • Plugin Architecture
    • Scalability and Performance
    • Serverless
    • Service Collaboration
    • Service Mesh
    • SOA
    • Spring is bloated
    • Stages of API Adoption
    • Transaction Management
    • Microservices Cross-cutting Concerns Options
    • Service Mesh Plus
    • Service Discovery
  • Design
    • Design Overview
    • Design First vs Code First
    • Desgin Pattern
    • Service Evolution
    • Consumer Contract and Consumer Driven Contract
    • Handling Partial Failure
    • Idempotency
    • Server Life Cycle
    • Environment Segregation
    • Database
    • Decomposition Patterns
    • Http2
    • Test Driven
    • Multi-Tenancy
    • Why check token expiration
    • WebServices to Microservices
  • Cross-Cutting Concerns
    • Concerns Overview
  • API Styles
    • Light-4j for absolute performance
    • Style Overview
    • Distributed session on IMDG
    • Hybrid Serverless Modularized Monolithic
    • Kafka - Event Sourcing and CQRS
    • REST - Representational state transfer
    • Web Server with Light
    • Websocket with Light
    • Spring Boot Integration
    • Single Page Application
    • GraphQL - A query language for your API
    • Light IBM MQ
    • Light AWS Lambda
    • Chaos Monkey
  • Infrastructure Services
    • Service Overview
    • Light Proxy
    • Light Mesh
    • Light Router
    • Light Portal
    • Messaging Infrastructure
    • Centralized Logging
    • COVID-19
    • Light OAuth2
    • Metrics and Alerts
    • Config Server
    • Tokenization
    • Light Controller
  • Tool Chain
    • Tool Chain Overview
  • Utility Library
  • Service Consumer
    • Service Consumer
  • Development
    • Development Overview
  • Deployment
    • Deployment Overview
    • Frontend Backend
    • Linux Service
    • Windows Service
    • Install Eventuate on Windows
    • Secure API
    • Client vs light-router
    • Memory Limit
    • Deploy to Kubernetes
  • Benchmark
    • Benchmark Overview
  • Tutorial
    • Tutorial Overview
  • Troubleshooting
    • Troubleshoot
  • FAQ
    • FAQ Overview
  • Milestones
  • Contribute
    • Contribute to Light
    • Development
    • Documentation
    • Example
    • Tutorial
“IP Whitelist” was last updated: April 5, 2021: Issue246 (#256) (50b1c10)
Improve this page
  • News
  • Docs
  • Community
  • Reddit
  • GitHub
  • About Light
  • Getting Started
  • Architecture
  • Design
  • Cross-Cutting Concerns
  • API Styles
  • Infrastructure Services
  • Tool Chain
  • Utility Library
  • Service Consumer
  • Development
  • Deployment
  • Benchmark
  • Tutorial
  • Troubleshooting
  • FAQ
  • Milestones
  • Contribute