dhis2_configure_cors_allowlist

Configure CORS allowlist settings for DHIS2 to enable secure cross-origin resource sharing with specified domains.

Instructions

Generate instructions and configuration for DHIS2 CORS allowlist setup

Input Schema

TableJSON Schema

Name	Required	Description
`allowedOrigins`	Yes	URLs to add to CORS allowlist (e.g., ["http://localhost:3000", "https://myapp.example.com"])
`dhis2Version`	No	DHIS2 version (e.g., "2.40.4")
`includeSteps`	No	Include step-by-step configuration instructions

Implementation Reference

src/index.ts:1152-1162 (handler)

The primary handler for the 'dhis2_configure_cors_allowlist' tool. It receives arguments, calls generateCORSConfiguration from debugging-helpers.ts, and returns the generated Markdown guide as tool response content.

case 'dhis2_configure_cors_allowlist':
  const corsAllowlistArgs = args as any;
  const corsConfig = generateCORSConfiguration(corsAllowlistArgs);
  return {
    content: [
      {
        type: 'text',
        text: corsConfig,
      },
    ],
  };

src/debugging-helpers.ts:151-308 (helper)

Core helper function that generates comprehensive Markdown documentation for configuring DHIS2 CORS allowlist. Includes step-by-step GUI instructions, system properties config, environment-specific examples, validation curl commands, troubleshooting, and security best practices.

export function generateCORSConfiguration(args: any): string {
  const { allowedOrigins, dhis2Version = '2.40.4', includeSteps = true } = args;

  return `# DHIS2 CORS Configuration Guide

## System Settings Configuration

${includeSteps ? `
### Step-by-Step Instructions
1. **Login to DHIS2** as a user with system administration privileges
2. **Navigate to System Settings**
   - Click on the Apps icon (grid icon)
   - Search for "System Settings"
   - Click on the System Settings app
3. **Configure CORS**
   - In the left sidebar, click "Access"
   - Scroll down to find "CORS allowlist"
   - Add your development URLs
4. **Save Changes**
   - Click "Save" at the bottom of the page
   - Wait for confirmation message
` : ''}

## CORS Allowlist Configuration

### URLs to Add
${allowedOrigins.map((url: string) => `- ${url}`).join('\n')}

### Configuration Format
\`\`\`
${allowedOrigins.join('\n')}
\`\`\`

## Advanced CORS Configuration (System Properties)

For system administrators, you can also configure CORS via system properties:

### dhis.conf Configuration
\`\`\`properties
# CORS Configuration
cors.allowedOrigins=${allowedOrigins.join(',')}
cors.allowCredentials=true
cors.allowedMethods=GET,POST,PUT,DELETE,OPTIONS,PATCH
cors.allowedHeaders=Accept,Content-Type,Origin,X-Requested-With,Authorization
cors.maxAge=3600
\`\`\`

## Environment-Specific Configurations

### Development Environment
\`\`\`
# Local development
http://localhost:3000
http://localhost:3001
http://127.0.0.1:3000

# Common development ports
http://localhost:8080
http://localhost:9000
\`\`\`

### Staging Environment  
\`\`\`
https://staging-app.yourdomain.com
https://test-app.yourdomain.com
\`\`\`

### Production Environment
\`\`\`
https://app.yourdomain.com
https://health-dashboard.yourdomain.com
\`\`\`

## Validation Commands

### Test CORS Configuration
\`\`\`bash
# Test basic CORS
curl -H "Origin: ${allowedOrigins[0]}" \\
     ${dhis2Version ? `https://your-dhis2-instance.com/api/system/info` : 'https://your-dhis2-instance.com/api/system/info'}

# Test with authentication
curl -H "Origin: ${allowedOrigins[0]}" \\
     -H "Authorization: Basic $(echo -n 'username:password' | base64)" \\
     https://your-dhis2-instance.com/api/me

# Test preflight request
curl -H "Origin: ${allowedOrigins[0]}" \\
     -H "Access-Control-Request-Method: POST" \\
     -H "Access-Control-Request-Headers: Content-Type" \\
     -X OPTIONS \\
     https://your-dhis2-instance.com/api/dataElements
\`\`\`

### Expected Response Headers
\`\`\`
Access-Control-Allow-Origin: ${allowedOrigins[0]}
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
Access-Control-Allow-Headers: Accept, Content-Type, Origin, X-Requested-With, Authorization
Access-Control-Max-Age: 3600
\`\`\`

## Troubleshooting Common Issues

### Issue: "CORS allowlist not found"
**Solution**: Update to DHIS2 2.35+ (older versions use different settings)

### Issue: "Changes not taking effect"
**Solutions**:
1. Clear browser cache completely
2. Restart DHIS2 server (if self-hosted)
3. Wait 5-10 minutes for changes to propagate
4. Check if nginx/reverse proxy needs updating

### Issue: "Still getting CORS errors"
**Checklist**:
- [ ] URLs match exactly (including protocol)
- [ ] No trailing slashes mismatch
- [ ] Case sensitivity check
- [ ] Wildcard not used (DHIS2 doesn't support wildcards)
- [ ] Browser cache cleared

## Security Best Practices

### Development
- Only add localhost URLs for development
- Use specific ports, not wildcards
- Remove development URLs before production

### Production
- Only add your production domain(s)
- Use HTTPS URLs only
- Regularly audit allowed origins
- Document all entries with purpose

### Monitoring
\`\`\`bash
# Check current CORS settings via API
curl -u admin:password \\
  https://your-dhis2-instance.com/api/systemSettings/keyJsCorallowlist
\`\`\`

## Version-Specific Notes

${dhis2Version >= '2.38' ? `
### DHIS2 ${dhis2Version}+
- Full CORS support available
- GUI configuration available
- API endpoint for configuration
` : `
### DHIS2 ${dhis2Version}
- Limited CORS support
- May require manual configuration
- Check documentation for version-specific settings
`}
`;
}

src/permission-system.ts:146-146 (registration)
Tool permission registration in TOOL_PERMISSIONS Map. Associates 'dhis2_configure_cors_allowlist' with 'canDebugApplications' permission, enabling permission-based filtering of available tools.
```
['dhis2_configure_cors_allowlist', 'canDebugApplications'],
```

DHIS2 MCP Server