Cohesive Zuul API Gateway

A Spring Cloud Zuul API Gateway with integrated Spring Security and EHCache for authentication and authorization in the GenPat platform.

Overview

Cohesive Zuul acts as a reverse proxy and authentication gateway, providing:

• API Gateway: Routes requests to backend services
• Authentication: Cookie-based authentication with CMDBuild
• Authorization: Role-based access control
• Caching: EHCache for performance optimization of authentication tokens and user data
• Security: Spring Security integration for secure access management

Features

• Zuul Routing: Intelligent request routing to multiple backend services
• Spring Security: Pre-authentication with session cookies
• Token Caching: Configurable TTL-based caching for authentication tokens
• User Caching: Caching of user details for improved performance
• PostgreSQL Integration: User and role management via CMDBuild database
• Docker Support: Ready for containerized deployment

Architecture

Client Request
      ↓
[Zuul Gateway] ← Cookie Auth (CMDBuild-Authorization)
      ↓
[Spring Security Filter] ← Pre-authentication
      ↓
[EHCache] ← Token & User caching
      ↓
[Backend Services]
  - /work/** → Pipelines service
  - /downloads/** → Download service
  - /res/** → Resources service

Prerequisites

• Java 8 or higher
• Maven 3.x
• PostgreSQL database (CMDBuild instance)
• Backend services to proxy

Installation

1. Clone this repository:

   git clone https://github.com/genpat-it/cohesive-zuul.git
   cd cohesive-zuul

2. Build the WAR file:

   mvn clean package

   The WAR file will be generated at: target/biz.war

Configuration

Application Configuration

Edit src/main/resources/application.yml:

zuul:
  routes:
    pipelines:
      path: /work/**
      url: http://your-pipeline-service
      stripPrefix: false
    download:
      path: /downloads/**
      url: http://your-download-service
      stripPrefix: false
    resources:
      path: /res/**
      url: http://your-resources-service
      stripPrefix: false

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/cmdbuild
    username: postgres
    password: your-database-password

app:
  security:
    session-key: CMDBuild-Authorization
  cache:
    ttl-seconds: 300
    max-entries: 1000
    token:
      ttl-seconds: 30
      max-entries: 1000

Docker Configuration

For Docker deployments, create /conf/biz.yml with production settings:

zuul:
  routes:
    pipelines:
      url: http://apache:80
    download:
      url: http://apache:80
    resources:
      url: http://apache:80

spring:
  datasource:
    url: jdbc:postgresql://db:5432/cmdbuild
    password: your-production-password

Usage

Running Locally

java -jar target/biz.war

The gateway will start on the default port (usually 8080).

Deploying as WAR

Deploy biz.war to any servlet container (Tomcat, Jetty, etc.).

Docker Deployment

Use the application-docker.yml profile:

java -jar biz.war --spring.profiles.active=docker

Routes

The gateway provides the following routes:

• /work/** → Pipeline execution and management
• /downloads/** → File download service
• /res/** → Static resources

All routes require authentication via the CMDBuild-Authorization cookie.

Cache Configuration

User Cache

• TTL: 300 seconds (5 minutes)
• Max Entries: 1000 users

Token Cache

• TTL: 30 seconds
• Max Entries: 1000 tokens

Adjust these values in application.yml based on your needs.

Security

Authentication Flow

1. Client sends request with CMDBuild-Authorization cookie
2. PreAuthTokenCookieFilter extracts the session token
3. Token is validated against cached data (if available)
4. User details are loaded from CMDBuild database
5. Spring Security authorizes the request
6. Request is proxied to the backend service

Security Notes

• Database credentials should be stored in external configuration files
• Never commit configuration files with credentials to version control
• Use environment variables or secure vaults for production deployments
• The session key can be customized via app.security.session-key

Dependencies

• Spring Boot 2.3.12
• Spring Cloud Netflix Zuul 2.2.10
• Spring Security
• Spring Data JDBC
• PostgreSQL Driver
• EHCache 3.x
• Lombok
• Commons IO

Project Structure

zuul/
├── src/
│   └── main/
│       ├── java/
│       │   └── it/izs/bioinfo/zuul/
│       │       ├── ZuulApplication.java
│       │       ├── config/
│       │       │   ├── Constants.java
│       │       │   ├── FilterConfiguration.java
│       │       │   ├── ZuulConfig.java
│       │       │   ├── cache/
│       │       │   │   ├── CacheConfig.java
│       │       │   │   ├── EHCacheAuthTokenConfiguration.java
│       │       │   │   └── EHCacheEntityConfiguration.java
│       │       │   └── security/
│       │       │       ├── WebSecurityConfig.java
│       │       │       ├── PreAuthTokenCookieFilter.java
│       │       │       ├── AuthenticationUserDetailsServiceImpl.java
│       │       │       └── CmdbuildUser.java
│       │       └── user/
│       │           └── UserRepository.java
│       └── resources/
│           ├── application.yml
│           └── application-docker.yml
├── pom.xml
├── LICENSE
└── README.md

References

• Spring Security Documentation
• Spring Cloud Zuul
• EHCache Configuration

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Contact

For questions or support, please contact: cohesive@izs.it