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 | Default |
|---|---|---|---|
| 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'],