dhis2_configure_cors_allowlist
Configure Cross-Origin Resource Sharing (CORS) allowlist for DHIS2 health systems by specifying allowed origins and generating setup instructions to enable secure access from external applications.
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-1163 (handler)Handler for the dhis2_configure_cors_allowlist tool. Extracts arguments and calls generateCORSConfiguration to produce CORS configuration guide.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-307 (helper)Core implementation function that generates comprehensive markdown guide for DHIS2 CORS allowlist configuration based on input arguments.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)Permission registration mapping the tool to 'canDebugApplications' permission check.['dhis2_configure_cors_allowlist', 'canDebugApplications'],
- src/index.ts:37-39 (helper)Import of the generateCORSConfiguration helper function used by the tool handler.diagnoseCORSIssues, generateCORSConfiguration, debugAuthentication,