Enterprise Service Bus (ESB)

The Manager includes an integrated Enterprise Service Bus (ESB) for secure API integration, enabling external systems to call backend services through the Manager with authentication, transformation, and audit logging.

Overview

The ESB provides:

• Machine User Authentication - Secure access control via Bearer token authentication
• Message Transformation - Go template-based request/response transformation
• Multi-Auth Support - Forward requests with Basic, Bearer, or no authentication
• Audit Logging - Configurable logging levels (None, Basic, Full)
• Endpoint-based Routing - Route requests based on application ID and endpoint path

Quick Start

1. Create an Endpoint

Navigate to your application and create an endpoint:

• Name: Descriptive name (e.g., "Webhook Receiver")
• Consume URL: Path that triggers this endpoint (e.g., /api/webhook)
• URL: Target backend URL (e.g., https://backend.example.com/webhook)
• Enabled: Toggle to enable the endpoint
• Auth Type: Authentication method for backend (None, Bearer, Basic)
• Transformation Template: Optional Go template for message transformation
• Log Level: Audit logging verbosity (None, Basic, Full)

2. Create and Configure Machine User

Create a machine user and grant it access to the endpoint through the Machine User Access tab.

3. Call the ESB Endpoint

curl -X POST https://manager.example.com/esb/{appId}/api/webhook \
  -H "Authorization: Bearer {machine-user-token}" \
  -H "Content-Type: application/json" \
  -d '{"event": "user.signup", "userId": 12345}'

API Endpoint

Endpoint Pattern: /esb/{applicationId}/{endpointPath}

• Method: Any HTTP method (GET, POST, PUT, DELETE, etc.)
• Authentication: Machine user Bearer token via Authorization header
• Path Parameters:
  • applicationId - UUID of the application
  • endpointPath - The consume URL path configured in the endpoint

Message Transformation

Endpoints can define Go templates to transform request bodies before forwarding.

Template Context

Templates have access to a rich context with the following variables:

.Data - The parsed request body (JSON object, XML, or string)

.Application - Application information:

• .Application.ID - Application UUID
• .Application.Name - Application name
• .Application.Slug - Application slug
• .Application.Description - Application description

.Endpoint - Endpoint information:

• .Endpoint.ID - Endpoint UUID
• .Endpoint.Name - Endpoint name
• .Endpoint.ConsumeURL - Target URL
• .Endpoint.URL - Internal URL
• .Endpoint.Description - Endpoint description

.User - Machine user information:

• .User.ID - Machine user UUID
• .User.Username - Machine user username
• .User.Name - Machine user display name

.Meta - Request metadata:

• .Meta.Timestamp - ISO 8601 timestamp
• .Meta.RequestTime - Go time.Time object

.Env - Safe environment variables (PRODUCTIFY_ENV, APP_ENV, etc.)

Template Example

{
  "event": "{{ .Data.Event }}",
  "timestamp": "{{ .Meta.Timestamp }}",
  "application": {
    "name": "{{ .Application.Name }}",
    "slug": "{{ .Application.Slug }}"
  },
  "user": "{{ .User.Username }}",
  "data": {{ .Data.Payload | toJson }},
  "source": "{{ .Data.Source | toUpper }}"
}

Available Template Functions

• toJson - Convert value to JSON string
• toString - Convert value to string
• toUpper - Convert string to uppercase
• toLower - Convert string to lowercase
• now - Get current timestamp in RFC3339 format
• env - Get environment variable by key

Input/Output Message Types

Configure how the ESB processes messages:

• JSON - Parse/output as JSON (default)
• XML - Parse/output as XML
• SOAP - Parse/output as SOAP XML with appropriate content type

Backend Authentication

When forwarding to backend services, the ESB can apply authentication:

None

No authentication header added.

Bearer Token

Authorization: Bearer {configured-token}

Basic Authentication

Authorization: Basic {base64(username:password)}

Audit Logging

The ESB supports three audit logging levels:

NONE

No audit logs are created. Use this for high-volume, low-security endpoints to save database space.

BASIC (Default)

Logs metadata only:

• Timestamp and duration
• Source IP address
• Request method and path
• Response status code
• Error messages (if any)
• Whether transformation was applied

Does NOT log: Request/response headers or bodies

FULL

Logs everything including:

• All BASIC level data
• Request headers and body
• Response headers and body

Database Impact

FULL logging can significantly increase database size. Use only for debugging or compliance requirements.

Processing Flow

1. Client sends request to /esb/{appId}/{endpointPath}
   └─> Authorization: Bearer {token}

2. Machine user authentication middleware validates token
   └─> Checks if token is valid and machine user is enabled

3. ESB handler finds endpoint by application ID and consume URL
   └─> Verifies endpoint is enabled
   └─> Checks machine user has access to endpoint

4. Transform request (if template configured)
   └─> Parse input based on input_message_type
   └─> Apply Go template transformation
   └─> Set output content type

5. Forward to backend service
   └─> Apply endpoint authentication (Bearer/Basic/None)
   └─> Preserve original headers (except Authorization)
   └─> Execute HTTP request

6. Return response to client
   └─> Copy response headers
   └─> Return response body and status code

7. Audit log transaction (based on log_level)
   └─> Store in esb_audit_logs table
   └─> Include timing, errors, transformation status
   └─> Include bodies/headers if log_level is FULL

Error Responses

The ESB returns appropriate HTTP status codes:

• 400 Bad Request - Invalid application ID or malformed request
• 401 Unauthorized - Invalid or missing machine user credentials
• 403 Forbidden - Machine user doesn't have access to endpoint
• 404 Not Found - Endpoint not found or disabled
• 500 Internal Server Error - Transformation failed
• 502 Bad Gateway - Failed to forward request to backend

All errors are logged to the audit database (if logging is enabled).

Security Considerations

1. Machine User Credentials - Use strong, unique tokens
2. HTTPS Only - Always use TLS in production
3. Endpoint Access Control - Carefully manage machine user permissions
4. Audit Logs - Monitor for suspicious activity
5. Sensitive Data - Consider using BASIC logging to avoid storing sensitive data

Configuration Example

GraphQL Mutation

mutation {
  createEndpoint(
    input: {
      name: "API Gateway"
      description: "Forwards API requests to backend"
      applicationID: "123e4567-e89b-12d3-a456-426614174000"
      consumeUrl: "/api/data"
      url: "https://backend.service.com/api/data"
      enabled: true
      inputMessageType: JSON
      outputMessageType: JSON
      authType: Bearer
      authToken: "backend-token-xyz"
      logLevel: BASIC
      transformationTemplate: "{\"event\": \"{{ .type }}\", \"data\": {{ .payload | toJson }}}"
    }
  ) {
    id
    name
  }
}

Best Practices

Performance

• Use BASIC logging for production endpoints
• Use NONE logging for high-volume, non-critical endpoints
• Keep transformation templates simple
• Configure appropriate timeout values

Security

• Rotate machine user tokens regularly
• Limit machine user access to required endpoints only
• Use HTTPS for all backend URLs
• Review audit logs regularly

Debugging

• Use FULL logging temporarily when debugging issues
• Switch back to BASIC after resolving issues
• Monitor database size when using FULL logging

Related Documentation

• Endpoints
• Machine Users
• Backend Integration