proxmox/docs/04-configuration/OMADA_CONNECTION_GUIDE.md

Omada Controller Connection Guide

Last Updated: 2025-01-20
Status: Connection Troubleshooting

---

Current Status

✅ Controller Reachable: https://192.168.11.8:8043 (HTTP 200 response)
❌ API Authentication: Failing - Invalid credentials
⚠️ Issue: API_KEY/API_SECRET cannot be used for /api/v2/login endpoint

---

Connection Options

Option 1: Web Interface Access (Recommended for Initial Setup)

Access the Omada Controller web interface directly:

URL: https://192.168.11.8:8043

Note: You'll need to accept the self-signed SSL certificate if using a browser.

From the web interface, you can:

• View all devices (routers, switches, APs)
• Check device adoption status
• View VLAN configurations
• Configure network settings
• Export configurations

Option 2: API Access with Admin Credentials

The /api/v2/login endpoint requires admin username and password, not OAuth credentials.

Update ~/.env with admin credentials:

# Omada Controller Configuration - Admin Credentials
OMADA_CONTROLLER_URL=https://192.168.11.8:8043
OMADA_ADMIN_USERNAME=your-admin-username
OMADA_ADMIN_PASSWORD=your-admin-password
OMADA_SITE_ID=090862bebcb1997bb263eea9364957fe
OMADA_VERIFY_SSL=false

Then test connection:

cd /home/intlc/projects/proxmox
node test-omada-direct.js

Option 3: OAuth Token Endpoint (If Available)

If your Omada Controller supports OAuth token endpoint:

1. Check OAuth Configuration:

   • Access Omada Controller web interface
   • Navigate to: Settings → Platform Integration → Open API
   • Check if OAuth application supports "Client Credentials" mode

2. If Client Credentials Mode Available:

   • Change OAuth app from "Authorization Code" to "Client Credentials"
   • Use Client ID/Secret with OAuth token endpoint
   • Update authentication code to use OAuth endpoint

3. Find OAuth Token Endpoint:

   • Check Omada Controller API documentation
   • Typically: /api/v2/oauth/token or similar

---

Testing Connection

Test Scripts Available

1. Direct Connection Test (uses Node.js https module):

   node test-omada-direct.js
   

   • Uses admin username/password from ~/.env
   • Better SSL handling
   • Lists devices and VLANs on success

2. API Library Test (uses omada-api library):

   node test-omada-connection.js
   

   • Currently failing due to fetch SSL issues
   • Should work once authentication is fixed

Manual API Test (curl)

# Test login endpoint
curl -k -X POST https://192.168.11.8:8043/api/v2/login \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_ADMIN_USERNAME","password":"YOUR_ADMIN_PASSWORD"}'

Expected Response:

{
  "errorCode": 0,
  "result": {
    "token": "your-token-here",
    "expiresIn": 3600
  }
}

---

Current Configuration

Environment Variables (Current)

OMADA_CONTROLLER_URL=https://192.168.11.8:8043
OMADA_API_KEY=273615420c01452a8a2fd2e00a177eda
OMADA_API_SECRET=8d3dc336675e4b04ad9c1614a5b939cc
OMADA_SITE_ID=090862bebcb1997bb263eea9364957fe
OMADA_VERIFY_SSL=false

Note: OMADA_API_KEY and OMADA_API_SECRET are OAuth credentials, not admin credentials.

Controller Information

• URL: https://192.168.11.8:8043
• Site ID: 090862bebcb1997bb263eea9364957fe
• Status: Controller is reachable (HTTP 200)
• SSL: Self-signed certificate (verification disabled)

---

Next Steps

Immediate Actions

1. Access Web Interface:

   • Open https://192.168.11.8:8043 in browser
   • Accept SSL certificate warning
   • Log in with admin credentials
   • Verify device inventory

2. Update Credentials:

   • Add OMADA_ADMIN_USERNAME and OMADA_ADMIN_PASSWORD to ~/.env
   • Or update existing OMADA_API_KEY/OMADA_API_SECRET if they are actually admin credentials

3. Test API Connection:

   node test-omada-direct.js
   

Verify Device Inventory

Once connected, verify:

• Routers: ER605-A, ER605-B (if deployed)
• Switches: ES216G-1, ES216G-2, ES216G-3
• Device Status: Online/Offline
• Adoption Status: Adopted/Pending
• Firmware Versions: Current versions

Verify Configuration

• VLANs: List all configured VLANs
• Network Settings: Current network configuration
• Device IPs: Actual IP addresses of devices

---

Troubleshooting

Connection Issues

Problem: Cannot connect to controller

Solutions:

• Verify controller IP: ping 192.168.11.8
• Check firewall: Ensure port 8043 is accessible
• Test HTTPS: curl -k -I https://192.168.11.8:8043
• Verify controller service is running

Authentication Issues

Problem: "Invalid username or password"

Solutions:

• Verify admin credentials are correct
• Check if account is locked or disabled
• Try logging in via web interface first
• Reset admin password if needed

Problem: "OAuth authentication failed"

Solutions:

• Use admin credentials instead of OAuth credentials
• Check OAuth application configuration in controller
• Verify Client Credentials mode is enabled (if using OAuth)

SSL Certificate Issues

Problem: SSL certificate errors

Solutions:

• For testing: Set OMADA_VERIFY_SSL=false in ~/.env
• For production: Install valid SSL certificate on controller
• Accept certificate in browser when accessing web interface

---

API Endpoints Reference

Authentication

• POST /api/v2/login
  • Body: {"username": "admin", "password": "password"}
  • Returns: {"errorCode": 0, "result": {"token": "...", "expiresIn": 3600}}

Sites

• GET /api/v2/sites
  • Headers: Authorization: Bearer <token>
  • Returns: List of sites

Devices

• GET /api/v2/sites/{siteId}/devices
  • Headers: Authorization: Bearer <token>
  • Returns: List of devices (routers, switches, APs)

VLANs

• GET /api/v2/sites/{siteId}/vlans
  • Headers: Authorization: Bearer <token>
  • Returns: List of VLANs

---

Related Documentation

• OMADA_HARDWARE_CONFIGURATION_REVIEW.md - Hardware and configuration review
• OMADA_API_SETUP.md - API integration setup
• ER605_ROUTER_CONFIGURATION.md - Router configuration guide
• OMADA_AUTH_NOTE.md - Authentication notes

---

Document Status: Active
Maintained By: Infrastructure Team
Last Updated: 2025-01-20