Skip to main content

​
Overview

MCPHub provides flexible authentication mechanisms to secure your MCP server management platform. The system supports multiple authentication methods and role-based access control.

​
Authentication Methods

​
Environment-based Authentication

Configure basic authentication using environment variables: 
# Basic auth credentials
AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password

# JWT settings
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=24h

​
Database Authentication

For production deployments, enable database-backed user management: 
{
  "auth": {
    "provider": "database",
    "database": {
      "url": "postgresql://user:pass@localhost:5432/mcphub",
      "userTable": "users"
    }
  }
}

​
User Management

​
Creating Users

Create users via the admin interface or API: 
# Via API
curl -X POST http://localhost:3000/api/auth/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "securepassword",
    "role": "user"
  }'

​
User Roles

MCPHub supports role-based access control:
  • Admin: Full system access, user management, server configuration
  • Manager: Server management, group management, monitoring
  • User: Basic server access within assigned groups
  • Viewer: Read-only access to assigned resources

​
Group-based Access Control

​
Assigning Users to Groups

# Add user to group
curl -X POST http://localhost:3000/api/groups/{groupId}/users \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"userId": "user123"}'

​
Group Permissions

Configure group-level permissions: 
{
  "groupId": "dev-team",
  "permissions": {
    "servers": ["read", "write", "execute"],
    "tools": ["read", "execute"],
    "logs": ["read"],
    "config": ["read"]
  }
}

​
API Authentication

​
JWT Token Authentication

// Login to get token
const response = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'your-username',
    password: 'your-password',
  }),
});

const { token } = await response.json();

// Use token for authenticated requests
const serversResponse = await fetch('/api/servers', {
  headers: { Authorization: `Bearer ${token}` },
});

​
API Key Authentication

For service-to-service communication: 
# Generate API key
curl -X POST http://localhost:3000/api/auth/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "name": "my-service",
    "permissions": ["servers:read", "tools:execute"]
  }'

# Use API key
curl -H "X-API-Key: your-api-key" \
  http://localhost:3000/api/servers

​
Security Configuration

​
HTTPS Setup

Configure HTTPS for production: 
# docker-compose.yml
services:
  mcphub:
    environment:
      - HTTPS_ENABLED=true
      - SSL_CERT_PATH=/certs/cert.pem
      - SSL_KEY_PATH=/certs/key.pem
    volumes:
      - ./certs:/certs:ro

​
CORS Configuration

Configure CORS for web applications: 
{
  "cors": {
    "origin": ["https://your-frontend.com"],
    "credentials": true,
    "methods": ["GET", "POST", "PUT", "DELETE"]
  }
}

​
Rate Limiting

Protect against abuse with rate limiting: 
{
  "rateLimit": {
    "windowMs": 900000,
    "max": 100,
    "message": "Too many requests from this IP"
  }
}

​
Session Management

​
Session Configuration

{
  "session": {
    "secret": "your-session-secret",
    "cookie": {
      "secure": true,
      "httpOnly": true,
      "maxAge": 86400000
    },
    "store": "redis",
    "redis": {
      "host": "localhost",
      "port": 6379
    }
  }
}

​
Logout and Session Cleanup

// Logout endpoint
app.post('/api/auth/logout', (req, res) => {
  req.session.destroy();
  res.json({ message: 'Logged out successfully' });
});

​
Security Best Practices

​
Password Security

  • Use strong password requirements
  • Implement password hashing with bcrypt
  • Support password reset functionality
  • Enable two-factor authentication (2FA)

​
Token Security

  • Use secure JWT secrets
  • Implement token rotation
  • Set appropriate expiration times
  • Store tokens securely in httpOnly cookies

​
Network Security

  • Use HTTPS in production
  • Implement proper CORS policies
  • Enable request validation
  • Use security headers (helmet.js)

​
Monitoring Security Events

// Log security events
const auditLog = {
  event: 'login_attempt',
  user: username,
  ip: req.ip,
  userAgent: req.headers['user-agent'],
  success: true,
  timestamp: new Date(),
};

​
Troubleshooting

​
Common Authentication Issues

Invalid Credentials 
# Check user exists and password is correct
curl -X POST http://localhost:3000/api/auth/verify \
  -d '{"username": "user", "password": "pass"}'
Token Expiration 
// Handle token refresh
if (response.status === 401) {
  const newToken = await refreshToken();
  // Retry request with new token
}
Permission Denied 
# Check user permissions
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/auth/permissions

​
Debug Authentication

Enable authentication debugging: 
DEBUG=mcphub:auth npm start

​
Integration Examples

​
Frontend Integration

// React authentication hook
const useAuth = () => {
  const [user, setUser] = useState(null);

  const login = async (credentials) => {
    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(credentials),
    });

    if (response.ok) {
      const userData = await response.json();
      setUser(userData.user);
      return true;
    }
    return false;
  };

  return { user, login };
};

​
Middleware Integration

// Express middleware
const authMiddleware = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];

  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};
⌘I