Skip to content

Latest commit

 

History

History
260 lines (184 loc) · 7.49 KB

README.md

File metadata and controls

260 lines (184 loc) · 7.49 KB

Custom Backend Server

A secure, non-egress compliant backend service for monitoring external health check endpoints and reporting their status to Atlassian Forge applications.

Overview

This custom backend server enables health monitoring of external services while maintaining compliance with Atlassian's "Runs on Atlassian" policy. It acts as a bridge between external services and your Forge application, handling health checks and secure communication.

Architecture

Key Components

  • Health Check Service: Monitors external service endpoints
  • Tenant Management: Secure multi-tenant data storage
  • Cryptographic Security: Ed25519 key-based authentication
  • Scheduled Monitoring: Automated periodic health checks
  • Forge Integration: Secure communication with Forge triggers

Security Model

Tenant-Based Key Management

The backend uses a sophisticated tenant-based security model:

  1. Key Generation: Each tenant (cloudId) gets a unique Ed25519 key pair
  2. Public Key Registration: During service registration, the public key is sent to Forge
  3. Signature Verification: All subsequent requests are cryptographically signed
  4. Forge Validation: Forge validates signatures using the stored public key

Authentication Flow

1. Service Registration:
   - Backend generates Ed25519 key pair for tenant
   - Public key sent to Forge during REGISTER action
   - Forge stores public key for tenant

2. Health Check Updates:
   - Backend signs data with private key
   - Forge validates signature using stored public key
   - Only valid signatures are processed

Features

🔍 Health Monitoring

  • Periodic Checks: Automatic health checks every 5 minutes
  • Real-time Status: Live status updates sent to Forge
  • Error Handling: Comprehensive error logging and recovery

🔐 Security

  • Ed25519 Cryptography: Industry-standard digital signatures
  • Tenant Isolation: Separate keys and data per tenant
  • Non-egress Compliance: All data processing within Atlassian infrastructure

🚀 Performance

  • Efficient Monitoring: Optimized health check scheduling
  • Scalable Architecture: Handles multiple tenants and services
  • Graceful Shutdown: Proper cleanup on service termination

API Endpoints

GET /register

Serves the service registration page for users to add new health check endpoints.

POST /addedMonitorService

Registers a new health check service:

  • Validates input data
  • Performs initial health check
  • Stores tenant information
  • Sends registration data to Forge

Configuration

Environment Variables

  • PORT: Server port (default: 8080)
  • BACKEND_URL: Public URL for the backend service

Forge Variables

Set the backend URL in your Forge app:

forge variables set BACKEND_URL https://your-backend-service.com

Important Notes

HTTPS Requirement

⚠️ Critical: Forge applications can only communicate with HTTPS endpoints. This means:

  • Your backend server must be accessible via HTTPS
  • Local development requires a tunnel service (ngrok, etc.)
  • The tunnel URL must be set as the BACKEND_URL Forge variable
  • Without HTTPS, the Forge app will show "Backend URL Not Configured" error

Tunnel Service Considerations

  • ngrok: Most popular, stable, free tier available
  • Cloudflare Tunnel: More reliable for production use
  • LocalTunnel: Simple but less stable
  • URL Changes: Free tunnel services often change URLs on restart

Installation & Setup

Prerequisites

  • Node.js 18+
  • ngrok or similar HTTPS tunnel service
  • Forge CLI installed and configured

Quick Start

  1. Install Dependencies

    npm install

  2. Start the Backend Server

    npm run start

  3. Set up HTTPS Tunnel (Required)

    Since Forge applications require HTTPS, you need to expose your local server using a tunnel service:

    # Install ngrok (if not already installed)
npm install -g ngrok

# Start ngrok tunnel on port 8080
ngrok http 8080

    This will give you a public HTTPS URL like: https://d69055ad7ba7.ngrok.app

  4. Configure Forge Variables

    Navigate to your Forge app directory and set the backend URL:

    cd ..
forge variables set BACKEND_URL https://d69055ad7ba7.ngrok.app

    Replace https://d69055ad7ba7.ngrok.app with your actual ngrok URL.

Alternative Tunnel Services

If you prefer other tunnel services:

  • Cloudflare Tunnel: cloudflared tunnel --url http://localhost:8080
  • LocalTunnel: npx localtunnel --port 8080
  • Serveo: ssh -R 80:localhost:8080 serveo.net

Development Mode

For development with hot reload:

npm run dev

Production Build

npm run build
npm run start:prod

Complete Setup Example

Here's a complete step-by-step example of setting up the application:

# 1. Install dependencies
npm install

# 2. Start the backend server
npm run start
# Server will start on http://localhost:8080

# 3. In a new terminal, start ngrok tunnel
ngrok http 8080
# This will output something like:
# Forwarding https://d69055ad7ba7.ngrok.app -> http://localhost:8080

# 4. Navigate to your Forge app directory
cd ..

# 5. Set the backend URL variable
forge variables set BACKEND_URL https://d69055ad7ba7.ngrok.app

# 6. Deploy your Forge app (if not already deployed)
forge deploy

# 7. Install your Forge app
forge install

After completing these steps, your Forge app should be able to communicate with the backend server through the HTTPS tunnel.

Project Structure

src/
├── middleware/         # Express middleware
├── routes/            # API endpoints
├── services/          # Business logic
├── utils/             # Helper functions
├── types.ts           # TypeScript definitions
├── constants.ts       # Configuration
└── server.ts          # Main server file

Security Considerations

Why Tenant Keys Are Essential

  1. Authorization: Keys serve as the primary authentication mechanism for Forge web triggers
  2. Data Integrity: Cryptographic signatures ensure data hasn't been tampered with
  3. Tenant Isolation: Each tenant has separate keys, preventing cross-tenant access
  4. Non-repudiation: Digital signatures provide proof of data origin

Key Lifecycle

  • Generation: New Ed25519 key pair created per tenant
  • Registration: Public key sent to Forge during first service registration
  • Validation: Forge validates all subsequent requests using the public key
  • Rotation: Keys can be regenerated if needed (requires re-registration)

Compliance

This backend is designed to be fully compliant with Atlassian's "Runs on Atlassian" policy:

  • ✅ No data egress from Atlassian infrastructure
  • ✅ All processing within approved boundaries
  • ✅ Secure communication with Forge applications
  • ✅ Proper tenant data isolation

Monitoring & Logging

  • Health Check Results: Detailed logging of all health check attempts
  • Error Tracking: Comprehensive error logging with context
  • Performance Metrics: Monitoring of response times and success rates
  • Security Events: Logging of authentication and authorization events

Development

Prerequisites

  • Node.js 18+
  • TypeScript 5+
  • Forge CLI

Scripts

  • npm run start - Start production server
  • npm run dev - Start development server with hot reload
  • npm run build - Compile TypeScript
  • npm run start:prod - Start compiled server

License

MIT License - see LICENSE file for details.