DHIS2 Authentication Plugin (v1.0.1)

Developer: HUB4CYBER
Version: 1.0.1
Download Plugin:

The DHIS2 Authentication Plugin integrates a DHIS2 server with WordPress to provide:

• Secure DHIS2-backed user authentication
• Optional automatic WordPress user creation
• Admin-only front-end tools for managing DHIS2 users
• A secure server-side proxy that prevents exposing DHIS2 credentials in the browser

This solution is ideal for organizations running DHIS2 systems (e.g. HIV Prevention Tracker) that want controlled, secure access through WordPress.

Core Purpose

The plugin is designed to:

1. Authenticate users against DHIS2 using the /api/me endpoint
2. Automatically create WordPress users after successful DHIS2 login (optional)
3. Provide admin-only front-end tools to:
   • Search and update DHIS2 users
   • Create new users
   • Reset passwords
   • Deactivate users
4. Keep DHIS2 credentials secure by handling all API requests server-side

Admin Settings

(WP Admin → Settings → DHIS2 Authentication)

1. Settings Tab

These options control how the plugin connects to DHIS2:

DHIS2 Server URL
Base URL of your DHIS2 instance
Example:

https://example.org

Authentication Mode

• User-submitted credentials (default)
  Users log in using their own DHIS2 username and password.
• Admin-configured Basic Auth
  All authentication uses credentials set by the administrator.

Admin Basic Auth Username & Password
Used when the admin-configured mode is selected.

Admin Authorization Header (Optional)
Supports:

Basic xxxxxxxxx

or

Authorization: Basic xxxxxxxxx

If provided, this overrides the username/password fields.

Verify SSL Certificates
Enable or disable TLS certificate verification for DHIS2 requests.

2. Test DHIS2 Connection

A Test Connection button checks:

{DHIS2 Server URL}/api/me

You’ll see:

• ✅ Connected successfully
• ❌ Connection failed (with details in tooltip)

3. Shortcodes Tab

A built-in reference table shows:

• Available shortcodes
• What each shortcode does
• Copy/paste usage examples

4. Settings Page Footer

Displays:

• Plugin name and version
• Developer name (with link)
• “More Details” link

5. Plugins List Shortcut

A Settings link is added to the WordPress Plugins page for quick access.

Secure DHIS2 Proxy (Admin-Only)

The plugin registers a secure REST endpoint:

/wp-json/dhis2-auth/v1/proxy?path=/api/...

What the Proxy Does

• Only allows paths starting with /api/
• Blocks full URLs and directory traversal (..)
• Applies the configured DHIS2 Authorization header
• Disables redirects (prevents HTML login pages)
• Returns JSON responses only
• Handles:
  • 3xx redirects
  • 401 / 403 unauthorized
  • Non-JSON responses

Why This Matters

All DHIS2 API calls happen server-side, so:

• No DHIS2 credentials appear in the browser
• Admin tools remain secure
• JavaScript never exposes sensitive auth data

Front-End Shortcodes

Note: All management tools are admin-only unless stated otherwise.

1. [dhis2_login_form]

Front-End Login Form

Displays a login form labeled:
“HIV Prevention Tracker Login”

On submission:

• Authenticates against DHIS2 /api/me
• Uses:
  • User credentials (default), or
  • Admin-configured credentials
• If successful:
  • Logs user into WordPress
  • Creates a WordPress user if missing (role: subscriber)
  • Copies first & last name from DHIS2

2. [dhis2_user_management]

Admin: User Management Tool

Allows admins to:

• Search users by:
  • Username
  • First name
  • Last name
  • Email
• Select from multiple results
• Update:
  • Organisation Units
  • DataView & TEI Search OUs
  • User Groups
  • User Roles
  • Enabled / Disabled status

Updates are sent using:

PUT /api/users/{id}

3. [dhis2_create_user]

Admin: Create New User

Features:

• All fields required with validation
• Auto-generated:
  • Username:
    First letter of first name + full surname
    Lowercase, no spaces
    Auto-increments if taken
  • Password:
    Prev@123 (read-only)
• Checks if email already exists in DHIS2
• Uses Select2 for multi-select fields
• Enforces limits (e.g. max 5 org units)

4. [dhis2_reset_user_password]

Admin: Reset Password

Workflow:

1. Search by username / name / email
2. Select a user
3. Confirm reset
4. Password resets to:

   Prev@123
   

Restrictions:

• Blocks reset for users in group:

  d4j1I6uTwk2
  

5. [dhis2_deactivate_user]

Admin: Deactivate Account

Allows admins to:

• Search and select a user
• Confirm details
• Disable the account by setting:

  userCredentials.disabled = true
  

Security & Operational Notes

• 🔒 Admin tools require manage_options permission
• 🔐 No DHIS2 credentials are exposed in the browser
• 🗄 Admin credentials are stored in WordPress options
• ⚠ SSL verification can be disabled (less secure)
• 🛡 All DHIS2 requests are proxied securely