Friday Night Wiki
TopicsAbout
Buy me a coffee
WSO2 Complete Guide

Chapter 2: WSO2 Architecture

WSO2 Carbon Platform

The WSO2 Carbon platform is the foundation of all WSO2 products. Understanding Carbon is essential to working effectively with any WSO2 product.

What is Carbon?

Carbon is a component-based, OSGi-powered middleware platform that provides:

  • Modular architecture for building server applications
  • Common runtime for all WSO2 products
  • Hot deployment and hot update capabilities
  • Unified management console
  • Multi-tenancy support
  • Clustering capabilities

OSGi Foundation

WSO2 Carbon is built on Apache Felix, an OSGi framework implementation.

OSGi Benefits:

  • Dynamic module system for Java
  • Components can be installed/uninstalled at runtime
  • Version management for dependencies
  • Isolation between components
  • Lifecycle management

OSGi Layers:

┌─────────────────────────────────┐
│    Applications/Services         │
├─────────────────────────────────┤
│    OSGi Service Layer           │
├─────────────────────────────────┤
│    OSGi Module Layer (Bundles)  │
├─────────────────────────────────┤
│    OSGi Execution Environment   │
└─────────────────────────────────┘

Core Architecture Components

1. Carbon Kernel

The base layer that provides:

  • OSGi runtime
  • Server startup/shutdown
  • User management
  • Logging framework
  • Registry and repository
  • Transports (HTTP/HTTPS)

2. Carbon Features

Features are logical groupings of OSGi bundles that provide specific functionality.

Types of Features:

  • Server Features: Core server capabilities
  • UI Features: Management console components
  • Tool Features: Development and administration tools

Feature Installation:

<!-- In features.xml or via Feature Manager -->
<feature>
    <id>org.wso2.carbon.apimgt.feature.group</id>
    <version>4.2.0</version>
</feature>

3. Carbon Registry

Centralized configuration and metadata storage.

Registry Types:

  • Local Registry: File-based, specific to instance
  • Remote Registry: Database-backed, shared across cluster
  • Configuration Registry: System configurations
  • Governance Registry: API metadata, policies

Registry Structure:

/_system
  ├── config/         # Configuration data
  ├── governance/     # Governance artifacts
  └── local/          # Local instance data

4. User Management

User Store Types:

  • JDBC user store (database)
  • LDAP/Active Directory
  • Read-only LDAP
  • Custom user stores

Configuration Example (user-mgt.xml):

<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
    <Property name="TenantManager">org.wso2.carbon.user.core.tenant.JDBCTenantManager</Property>
    <Property name="ReadOnly">false</Property>
    <Property name="MaxUserNameListLength">100</Property>
</UserStoreManager>

WSO2 API Manager Architecture

High-Level Architecture

┌────────────────────────────────────────────────────────┐
│                    Developer Portal                     │
│              (API discovery and subscription)           │
└─────────────────────┬──────────────────────────────────┘
                      │
┌─────────────────────┴──────────────────────────────────┐
│                  Publisher Portal                       │
│         (API creation, publishing, lifecycle)           │
└─────────────────────┬──────────────────────────────────┘
                      │
┌─────────────────────┴──────────────────────────────────┐
│                    API Gateway                          │
│    (Request routing, security, rate limiting)          │
└─────────────────────┬──────────────────────────────────┘
                      │
┌─────────────────────┴──────────────────────────────────┐
│                   Key Manager                           │
│         (OAuth2, token generation, validation)          │
└─────────────────────┬──────────────────────────────────┘
                      │
┌─────────────────────┴──────────────────────────────────┐
│                  Traffic Manager                        │
│           (Rate limiting, throttling policies)          │
└────────────────────────────────────────────────────────┘

Components Explained

1. Publisher Portal

Purpose: API design and lifecycle management

Key Functions:

  • Create APIs (REST, SOAP, GraphQL, WebSocket)
  • Define resources and operations
  • Configure security policies
  • Manage API lifecycle (Create → Publish → Deprecate → Retire)
  • Version management
  • API documentation

Port: 9443 (default HTTPS)

2. Developer Portal (Store)

Purpose: API discovery and consumption

Key Functions:

  • Browse available APIs
  • Subscribe to APIs
  • Generate access tokens
  • View API documentation
  • Test APIs (Try it out)
  • Manage subscriptions

Port: 9443 (default HTTPS)

3. Gateway

Purpose: Runtime API traffic handling

Key Functions:

  • Request routing to backend
  • Authentication and authorization
  • Rate limiting and throttling
  • Request/response transformation
  • Caching
  • Analytics data collection
  • Protocol mediation

Ports:

  • 8243 (HTTPS)
  • 8280 (HTTP)

Gateway Types:

  • Regular Gateway: Full-featured gateway
  • Micro Gateway: Lightweight, immutable gateway for microservices

4. Key Manager

Purpose: Security token management

Key Functions:

  • OAuth2 token generation
  • Token validation
  • Scope management
  • Application key management
  • Integration with identity providers

Can be replaced with: WSO2 Identity Server or third-party OAuth servers

5. Traffic Manager

Purpose: Rate limiting and throttling

Key Functions:

  • Policy evaluation
  • Quota management
  • Burst control
  • Dynamic throttling
  • Analytics event processing

WSO2 Enterprise Integrator Architecture

EI Components

┌─────────────────────────────────────────────┐
│         Micro Integrator (MI)               │
│    Lightweight integration runtime          │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│         Streaming Integrator (SI)           │
│    Real-time event processing               │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│         Integration Studio                  │
│    Development tool (IDE)                   │
└─────────────────────────────────────────────┘

Micro Integrator Runtime

Architecture:

┌──────────────────────────────────────────┐
│      Management API                      │
├──────────────────────────────────────────┤
│      Mediation Engine                    │
├──────────────────────────────────────────┤
│  Synapse  │  Message Flows │ Connectors  │
├──────────────────────────────────────────┤
│      Transports (HTTP, JMS, etc.)        │
└──────────────────────────────────────────┘

Key Features:

  • No management UI (CLI and API-based management)
  • Optimized for containers
  • Fast startup (< 5 seconds)
  • Low memory footprint (< 512 MB)
  • Externalized configuration

WSO2 Identity Server Architecture

IS Component Architecture

┌─────────────────────────────────────────────┐
│          User Portal / Console              │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│        Authentication Framework             │
│  (Local, Federated, Multi-factor)           │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│        Authorization Framework              │
│         (XACML, Role-based)                 │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│           User Store Manager                │
│    (JDBC, LDAP, Active Directory)           │
└─────────────────────────────────────────────┘

Authentication Flow

User → IS → Authentication → User Store
               │
               ├→ Local Authentication
               ├→ Federated Authentication (Google, Facebook)
               └→ Multi-factor (TOTP, SMS, Email)

Common Architectural Patterns

1. Single Node Deployment

Simplest deployment for development/testing.

┌──────────────────────────┐
│    WSO2 Product          │
│   (All components)       │
└────────┬─────────────────┘
         │
┌────────┴─────────────────┐
│      Database            │
└──────────────────────────┘

2. Distributed Deployment

Production-ready architecture with separated components.

API Manager Example:

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Publisher   │  │  Developer   │  │   Gateway    │
│   Portal     │  │   Portal     │  │   (Cluster)  │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┴─────────────────┘
                         │
              ┌──────────┴──────────┐
              │    Shared DB        │
              │  Control Plane DB   │
              └─────────────────────┘

3. Clustered Deployment

High availability and load distribution.

       Load Balancer
             │
    ┌────────┴────────┐
    │                 │
┌───┴────┐      ┌────┴───┐
│ Node 1 │      │ Node 2 │
└───┬────┘      └────┬───┘
    │                │
    └────────┬───────┘
             │
      Shared Database

Data Flow Architecture

Request Processing Flow (API Manager)

1. Client Request
   │
   ↓
2. Gateway (Authentication, Rate Limiting)
   │
   ↓
3. Key Manager (Token Validation)
   │
   ↓
4. Traffic Manager (Throttle Check)
   │
   ↓
5. Backend Service
   │
   ↓
6. Response Transformation
   │
   ↓
7. Client Response

Message Mediation Flow (Integrator)

1. Message Received (Proxy Service/API)
   │
   ↓
2. In Sequence (Request Processing)
   │
   ├→ Log
   ├→ Transform
   ├→ Enrich
   └→ Filter
   │
   ↓
3. Endpoint (Backend Service)
   │
   ↓
4. Out Sequence (Response Processing)
   │
   ├→ Log
   ├→ Transform
   └→ Respond
   │
   ↓
5. Response to Client

Database Architecture

Tables Organization

API Manager Databases:

  1. WSO2AM_DB: API Manager specific data (APIs, subscriptions, applications)
  2. WSO2SHARED_DB: User data, registry, user management
  3. WSO2_MB_STORE_DB: Message broker data (if using built-in broker)

Key Tables:

  • AM_API: API definitions
  • AM_SUBSCRIPTION: API subscriptions
  • AM_APPLICATION: Consumer applications
  • IDN_OAUTH2_ACCESS_TOKEN: OAuth tokens
  • REG_RESOURCE: Registry resources

Database Configuration

# deployment.toml
[database.apim_db]
type = "mysql"
url = "jdbc:mysql://localhost:3306/apim_db"
username = "wso2carbon"
password = "wso2carbon"
driver = "com.mysql.jdbc.Driver"

Performance Considerations

Key Performance Factors

  1. JVM Tuning

    • Heap size allocation
    • Garbage collection strategy
    • Thread pool sizing

  2. Database Performance

    • Connection pooling
    • Query optimization
    • Index management

  3. Network

    • Latency between components
    • Bandwidth availability
    • Firewall rules

  4. Caching

    • Response caching
    • OAuth token caching
    • Registry caching

JVM Memory (for production):

-Xms2048m -Xmx2048m
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200

Connection Pool:

[database.apim_db.pool_options]
maxActive = 100
maxWait = 60000
minIdle = 5
testOnBorrow = true
validationInterval = 30000

Security Architecture

Multi-Layer Security

┌─────────────────────────────────────┐
│   Transport Security (TLS/mTLS)    │
├─────────────────────────────────────┤
│   Authentication (OAuth2, JWT)     │
├─────────────────────────────────────┤
│   Authorization (Scopes, RBAC)     │
├─────────────────────────────────────┤
│   Message Security (Encryption)    │
└─────────────────────────────────────┘

Security Components

  1. Transport Security

    • TLS 1.2/1.3
    • Mutual TLS (mTLS)
    • Certificate management

  2. Authentication

    • OAuth 2.0
    • JWT tokens
    • API keys
    • Basic Auth

  3. Authorization

    • Scope-based
    • Role-based (RBAC)
    • Attribute-based (ABAC)

Extensibility Points

Custom Components

  1. Custom Handlers: Intercept and modify requests/responses
  2. Custom Mediators: Create reusable mediation logic
  3. Custom User Stores: Integrate with custom authentication systems
  4. Custom Throttling: Implement custom rate limiting logic

Example: Custom Handler

public class CustomHandler extends AbstractHandler {
    public boolean handleRequest(MessageContext messageContext) {
        // Custom logic here
        return true;
    }
    
    public boolean handleResponse(MessageContext messageContext) {
        // Custom response logic
        return true;
    }
}

Key Takeaways

  • WSO2 products are built on the modular Carbon platform
  • OSGi provides dynamic component management
  • API Manager has five main components: Publisher, Developer Portal, Gateway, Key Manager, Traffic Manager
  • Architecture supports multiple deployment patterns: single node, distributed, clustered
  • Understanding component interaction is key to effective troubleshooting
  • Security is implemented at multiple layers
  • Performance depends on JVM tuning, database optimization, and proper configuration

Next Steps

Continue to Chapter 3: WSO2 API Manager to learn about API lifecycle management in detail.