LIGHT

  • News
  • Docs
  • Community
  • Reddit
  • GitHub
Star

API Key

For some legacy applications to migrate from a monolithic gateway to the light-gateway without changing any code on the consumer application, we need to support the API Key authentication/authorization on the light-gateway(LG) or client-proxy(LCP). The consumer application sends the API key in a header to authenticate/authorize itself on the light-gateway. Then the light-gateway will retrieve a JWT token to access the downstream API.

Only specific paths will have API Key set up, and the header name for each application might be different. To support all use cases, we add a list of maps to the configuration apikey.yml to pathPrefixAuths property.

Each config item will have pathPrefix, headerName and apiKey. The handler will try to match the path prefix first and then get the input API Key from the header. After comparing with the configured API Key, the handler will return either ERR10057 API_KEY_MISMATCH or pass the control to the next handler in the chain.

Configuration

Here is the built-in configuration template.

# ApiKey Authentication Security Configuration for light-4j
# Enable ApiKey Authentication Handler, default is false.
enabled: ${apikey.enabled:false}
# path prefix to the api key mapping. It is a list of map between the path prefix and the api key
# for apikey authentication. In the handler, it loops through the list and find the matching path
# prefix. Once found, it will check if the apikey is equal to allow the access or return an error.
# The map object has three properties: pathPrefix, headerName and apiKey. Take a look at the test
# resources/config folder for configuration examples.
pathPrefixAuths: ${apikey.pathPrefixAuths:}

By default, this handle is disabled. So you can safely include it in the default request/response chain. It can only be turned on when you add the following property to your values.yml file.

# apikey.yml
apikey.enabled: true

Even if you have this handler enabled, this handler might not be invoked to check the API Key for your request. Your request path must be in the configuration pathPrefixAuths list to ensure that this handler checks API Key. The server will skip this handler if there is no definition for the pathPrefixAuths in the values.yml file.

Here is one way to define the property in YAML format in values.yml file.

apikey.pathPrefixAuths:
  - pathPrefix: /test1
    headerName: x-gateway-apikey
    apiKey: abcdefg
  - pathPrefix: /test2
    headerName: x-apikey
    apiKey: CRYPT:08eXg9TmK604+w06RaBlsPQbplU1F1Ez5pkBO/hNr8w=

Here is the way to define the pathPrefix, headerName and apiKey mapping in JSON format in values.yml file. It is suitable for the config server as the entire object can be constructed as a string.

apikey.pathPrefixAuths: [{"pathPrefix":"/test1","headerName":"x-gateway-apikey","apiKey":"abcdefg"},{"pathPrefix":"/test2","headerName":"x-apikey","apiKey":"CRYPT:08eXg9TmK604+w06RaBlsPQbplU1F1Ez5pkBO/hNr8w="}]

Most services will have multiple consumers, and each consumer might have its own API key for authentication. In this case, we can have multiple entries of the same path prefix in the pathPrefixAuths.

apikey.pathPrefixAuths:
  - pathPrefix: /test1
    headerName: x-gateway-apikey
    apiKey: abcdefg
  # The same prefix has another apikey header and value.
  - pathPrefix: /test1
    headerName: authorization
    apiKey: xyz
  - pathPrefix: /test2
    headerName: x-apikey
    apiKey: CRYPT:3ddd6c8b9bf2afc24d1c94af1dffd518:1bf0cafb19c53e61ddeae626f8906d43

With the above configuration in the values.yml on the gateway, the service with path prefix /test1 has two consumers and two different API keys from different headers.

Error Response

This handler only returns an error response ERR10075 if the pathPrefix and the header are matching and the apiKey is not equal between the configured value and the header value.

Here is the error message defined in the status.yml config file.

ERR10075:
  statusCode: 401
  code: ERR10075
  message: API_KEY_MISMATCH
  description: APIKEY from header %s is not matched for request path prefix %s.

To prevent leaking sensitive information, the apiKey from the config file is not revealed in the error message.

Usage

Once you configure this handler in the values.yml file, you need to add it to the request/response chain to allow it to work.

In the handler.yml or the values.yml if you have externalized the handlers definition and default chain.

handler.handlers:
  .
  .
  .
  - [email protected]

handler.chains.default:
  .
  .
  .
  - apikey
  .
  .
  .

This is the PR on how we add the apikey handler to the chain in the light-gateway values.yml file.

Unified Security

When light-gateway is used for multiple consumers and providers, chances are API Key, Basic, JWT, and SWT security will be used by different services. And one service might use several security handlers simultaneously to allow different consumers to authenticate and authorize themselves. In this case, the API Key handler can join the UnifiedSecurityHandler for a unified security solution.

  • About Light
    • Overview
    • Testimonials
    • What is Light
    • Features
    • Principles
    • Benefits
    • Roadmap
    • Community
    • Articles
    • Videos
    • License
    • Why Light Platform
  • 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
“API Key” was last updated: March 28, 2023: fixes #373 update basic auth document and apikey doc (45a9eb7)
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