BEBuzen ESB Docs
Platform Security

Security and Policies

Buzen ESB secures management APIs with token-based auth, role-based authorization, and policy enforcement at platform, app, and route scopes. This page details defaults and production hardening steps.

1. Authentication model

  • Login endpoint: POST /api/v1/auth/login
  • Credentials may be provided via JSON body or HTTP Basic credentials header.
  • Successful login returns bearer accessToken and expiry timestamp.
  • Token TTL default: 12h.
  • Max active tokens per user default: 1 (new logins can revoke older tokens).
curl -ksS -X POST https://<esb-host>:8443/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' | jq .

2. Authorization roles

Canonical roles: ADMIN, OPERATOR, VIEWER.

RoleIntended use
ADMINFull access, including system and user management
OPERATORRoute/app/connectors/policies/logs/traces operations
VIEWERRead-focused dashboard and metrics workflows

Security filters enforce endpoint-level role checks before management action handlers execute.

3. Ingress boundaries and reserved paths

Ingress path controls are split between Spring Security and route-level internal API protection:

  • buzen.esb.security.ingress.permit-all-paths: inbound route permit list
  • buzen.esb.security.internal-api.reserved-paths: extra blocked internal prefixes

Reserved prefixes include:

/api/v1
/actuator
/console
/ws
/api-docs
/swagger-ui
/v3/api-docs
Avoid broad /** ingress permits in production. Define only explicit partner-facing prefixes.

4. TLS and transport security

PropertyPurpose
buzen.esb.security.tls.enabledEnable HTTPS listener
buzen.esb.security.tls.keystore-pathKeystore file/classpath location
buzen.esb.security.tls.keystore-passwordKeystore password
buzen.esb.security.tls.keystore-typeUsually PKCS12
buzen.esb.security.tls.redirect-httpRedirect HTTP to HTTPS
buzen.esb.security.tls.require-client-certEnable mTLS requirement
 
BUZEN_ESB_SECURITY_TLS_ENABLED=true \
BUZEN_ESB_SECURITY_TLS_KEYSTORE_PATH=file:/absolute/path/to/buzen-esb.p12 \
BUZEN_ESB_SECURITY_TLS_KEYSTORE_PASSWORD=changeit \
BUZEN_ESB_ENCRYPTION_KEY=$(openssl rand -base64 32) \
java -jar buzen-runtime/target/buzen-esb.jar

5. Policy framework

Policy scopes:

  • PLATFORM
  • APP
  • ROUTE

Policy types:

  • IP_ALLOWLIST
  • MTLS
  • BASIC_AUTH
  • JWT_VALIDATION
  • RATE_LIMIT

Management API supports CRUD/toggle at each scope and effective policy resolution views.

# List policy types
curl -ksS https://<esb-host>:8443/api/v1/policies/types \
  -H "Authorization: Bearer ${TOKEN}" | jq .

6. Secrets and variable handling

  • Use environment variables or external secret stores for sensitive settings.
  • Set BUZEN_ESB_ENCRYPTION_KEY for encryption services.
  • Avoid storing credentials in route YAML and manifest properties.
  • Use data source references and global variables through management endpoints.

7. Production hardening checklist

  • Disable default development users unless explicitly required.
  • Use strong bootstrap admin password and rotate credentials.
  • Constrain ingress paths and reserve internal prefixes.
  • Enable TLS with production certificates.
  • Tune token TTL and max tokens per user for your risk model.
  • Configure request limits (max-request-bytes, JSON depth, upload caps).
  • Review policy coverage at platform, app, and route scope.
For endpoint-level details see Management API Guide.