NowConnect & Hybrid Connectivity

📋Learning Objectives

• Understand the hybrid connectivity challenge and NowConnect's solution
• Learn the outbound-only tunneling architecture
• Understand identity-anchored sessions with JWT/JWKS
• Configure connectors for LDAP, AD, databases, and REST APIs
• Understand WebSocket multiplexing for multiple targets
• Learn PDP authorization for connector access

🌐The Hybrid Connectivity Challenge

Organizations face a difficult choice: cloud benefits vs. on-premises security requirements.

🏗️NowConnect Architecture

Key Components

🔗Identity-Anchored Session Flow

Protocol Messages

🔀WebSocket Multiplexing

A single WSS connection supports multiple concurrent channels to different targets, with full isolation between them.

Benefits of Multiplexing

• Single Firewall Egress: Only one outbound connection to manage
• Resource Efficient: No connection per target; share one tunnel
• Channel Isolation: Each channel has independent flow control
• Automatic Reconnect: Agent reconnects on disconnect; channels resume

🛡️Security Controls

⚙️Connector Configuration

Agent Environment Variables

# Agent identity
NC_TOKEN_FILE=/run/secrets/agent-token    # JWT for authentication
NC_AGENT_ID=datacenter-west-01            # Must match JWT claim

# Cloud Hub connection
NC_HUB_URL=wss://nowconnect.self.empowernow.ai/tunnel

# Connector definitions
NC_CONNECTORS=ldap-corp,sql-erp,api-hr

# Per-connector targets
NC_TARGET_ldap_corp=ldap://ad.corp.internal:389
NC_TARGET_sql_erp=tcp://erp-db.corp.internal:1433
NC_TARGET_api_hr=tcp://hr-api.corp.internal:8080

# Optional: Corporate proxy and CA
NC_TRUST_ENV=true                         # Honor HTTP_PROXY, HTTPS_PROXY
NC_CA_BUNDLE=/etc/ssl/corp-ca.pem         # Trust corporate CA

# Health check
NC_HEALTH_HOST=0.0.0.0
NC_HEALTH_PORT=8080

Cloud Hub Configuration

# config/nowconnect.yaml
server:
  host: 0.0.0.0
  tunnel_port: 8443
  
  # TCP listeners exposed to cloud services
  listeners:
    - port: 389
      connector: ldap-corp
    - port: 636
      connector: ldaps-corp
    - port: 1433
      connector: sql-erp
    - port: 8080
      connector: api-hr

security:
  jwks_url: https://idp.self.empowernow.ai/.well-known/jwks.json
  audience: nowconnect
  require_connector_scopes: true   # JWT must include connector claims

pdp:
  url: https://pdp.self.empowernow.ai/access/v1/evaluation
  cache_ttl_sec: 60
  timeout_ms: 500
  fail_open: false                 # Deny if PDP unreachable

Supported Protocols

📡Wire Protocol

NowConnect uses JSON frames over WebSocket text messages (binary header in V1.1).

Protocol Frames

// Agent → Hub: Initial handshake
{ "t": "HELLO", "agent_id": "premise-01", "connectors": ["addomain", "devdomain1"], "ver": "1.5" }

// Hub → Agent: Acknowledge registration
{ "t": "HELLO_ACK" }

// Hub → Agent: Open connection to a target
{ "t": "OPEN", "cid": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "connector": "addomain" }

// Bidirectional: Data relay (base64-encoded)
{ "t": "DATA", "cid": "f47ac10b-...", "seq": 123, "b64": "TERBUCBxdWVyeS4uLg==" }

// Bidirectional: Half-close (c2a = client→agent, a2c = agent→client)
{ "t": "FIN", "cid": "f47ac10b-...", "dir": "c2a" }

// Error: Connection failed or broken
{ "t": "RST", "cid": "f47ac10b-...", "err": "connect_failed" }

Frame Fields

Connection Lifecycle

🔄High Availability

For production deployments, NowConnect supports high availability with multiple Cloud Hub instances.

HA Components

Reconnection Behavior

• Agent-side: Automatic reconnect with exponential backoff (2s, 4s, 8s...)
• Channel resume: Open channels are re-established after reconnect
• Graceful drain: Hub waits for active channels before shutdown

📊Observability

Key Metrics (Prometheus)

Structured Logging

# Cloud Hub JSON log format
{
  "ts": "2026-01-21T14:30:00Z",
  "level": "info",
  "event": "channel_opened",
  "agent_id": "premise-01",
  "connector": "ldap-corp",
  "cid": "f47ac10b-...",
  "pdp_decision": "permit",
  "duration_ms": 45
}

🔍Troubleshooting

Agent Can't Connect to Hub

Symptom: Agent logs show connection refused or timeout

Debug:

# Test outbound connectivity
curl -v https://nowconnect.self.empowernow.ai/healthz

# Check if proxy is needed
export HTTPS_PROXY=http://proxy.corp:8080
export NC_TRUST_ENV=true

# Verify CA bundle
openssl s_client -connect nowconnect.self.empowernow.ai:443 \
  -CAfile /etc/ssl/corp-ca.pem

JWT Validation Failed

Symptom: Hub rejects WebSocket upgrade with 401

Causes:

• Token expired — check exp claim
• Wrong audience — token aud must match Hub's security.audience
• JWKS unreachable — Hub can't fetch IdP's JWKS

OPEN Rejected by PDP

Symptom: Connection refused with 403, logs show "PDP denied"

Debug:

# Check PDP evaluation
curl -X POST https://pdp.self.empowernow.ai/access/v1/evaluation \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "agent", "id": "datacenter-west-01" },
    "action": { "name": "connect" },
    "resource": { "type": "connector", "id": "ldap-corp" },
    "context": { "reason_admin": true }
  }'

Target Unreachable

Symptom: OPEN succeeds but DATA fails, agent logs show connection refused

Fix: Verify target hostname:port is reachable from the agent's network. Check DNS resolution and firewall rules within the on-prem network.

❓Knowledge Check

📝Day 24 Checkpoint

• Understand the hybrid connectivity challenge
• Know NowConnect's outbound-only architecture
• Understand identity-anchored sessions (JWT/JWKS)
• Know the session flow (HELLO, OPEN, DATA, FIN)
• Understand WebSocket multiplexing
• Can configure connectors for various protocols
• Understand PDP authorization for connector access