Custom Authentication Configuration

The Custom Authentication Configuration file allows system administrators to implement advanced security and authentication controls that are not available through the standard web interface. These settings control IP-based access restrictions, account masquerading for troubleshooting, and XML API access.

Advanced Configuration

This feature requires direct file system access and PHP knowledge. Incorrect configuration can lock you out of the application. Always test changes in a development environment first and maintain backups.

Location and Setup

The custom authentication configuration is managed through a PHP file located in your installation:

~/admin/com/custom/authentication.php

Initial Setup

1. Navigate to the custom directory:

   cd ~/admin/com/custom/

2. Copy the example file to create your configuration:

   cp authentication.example.php authentication.php

3. Edit the file with your preferred text editor:

   nano authentication.php

4. Set appropriate file permissions:

   chmod 640 authentication.php

Note

The application automatically detects and loads authentication.php when present. If the file doesn’t exist, all custom authentication features are disabled and the system uses default authentication behavior.

Configuration Structure

The configuration file uses a PHP array structure with predefined keys:

<?php
$custom = [
    'admin_allow_ip' => [],
    'admin_allow_ip_enabled' => false,
    'regularuser_allow_ip' => [],
    'regularuser_allow_ip_enabled' => false,
    'enable_masquerade' => true,
    'masquerade_token_separator' => '::',
    'enable_xmlapi' => false,
    'xmlapi_admin_only' => true
];

Important

• Do NOT change the variable name $custom
• Do NOT change the array keys (e.g., admin_allow_ip, enable_masquerade)
• The file must contain valid PHP syntax or the application will fail to load

IP Restriction for System Administrators

Restrict System Administrator login to specific IP addresses for enhanced security.

Configuration Options

admin_allow_ip

An array of IP addresses allowed to login as System Administrator.

Example:

'admin_allow_ip' => [
    '127.0.0.1',                                    // Localhost
    '192.168.1.100',                                 // Static office IP
    '10.0.0.0/8',                                    // Private network range
    gethostbyname('vpn.yourcompany.com')            // Dynamic hostname
],

Supported formats:

• Single IP addresses: '192.168.1.100'
• CIDR notation: '10.0.0.0/8' (if supported by your implementation)
• Dynamic IPs via DNS: gethostbyname('hostname.com')

admin_allow_ip_enabled

Boolean flag to enable/disable IP restrictions for System Administrators.

Values:

• true - Enable IP restrictions (only IPs in admin_allow_ip can login as admin)
• false - Disable IP restrictions (default behavior)

Example Configuration

// Restrict admin login to office and VPN IPs only
'admin_allow_ip' => [
    '203.0.113.50',                              // Office static IP
    '203.0.113.51',                              // Backup office IP
    gethostbyname('vpn.example.com')             // VPN gateway
],
'admin_allow_ip_enabled' => true,

Critical Warning

If you enable admin_allow_ip_enabled with an empty admin_allow_ip array, NO ONE will be able to login as System Administrator, including you. You will be completely locked out of administrative functions.

Before enabling, ensure:

1. Your current IP is in the allowed list
2. You have an alternative access method (VPN, backup IP)
3. You can access the server file system to disable the feature if needed

Use Cases

Scenario 1: Office-only admin access

'admin_allow_ip' => ['203.0.113.50'],
'admin_allow_ip_enabled' => true,

Scenario 2: Multiple offices and VPN

'admin_allow_ip' => [
    '203.0.113.50',                              // New York office
    '198.51.100.25',                             // London office
    gethostbyname('vpn.company.com')             // Corporate VPN
],
'admin_allow_ip_enabled' => true,

IP Restriction for Regular Users

Similar to admin restrictions, but applies to all non-administrator user accounts.

Configuration Options

regularuser_allow_ip

An array of IP addresses allowed for regular user login.

regularuser_allow_ip_enabled

Boolean flag to enable/disable IP restrictions for regular users.

Example Configuration

// Restrict all regular users to company network only
'regularuser_allow_ip' => [
    '10.0.0.0/8',                                // Internal network
    gethostbyname('vpn.company.com')             // VPN access
],
'regularuser_allow_ip_enabled' => true,

Caution

If enabled with an empty array, regular users cannot login at all. This is useful for creating an admin-only emergency access mode.

Account Masquerading Debug Feature

Account masquerading lets a System Administrator sign in as another user for troubleshooting without knowing that user’s password. Because it bypasses user passwords, it should be disabled in production unless it is actively needed (see Security Considerations).

How It Works

When enabled, an authenticated System Administrator can act as another user through a special login format configured below. The system first verifies the administrator’s own credentials and System Administrator privileges, then switches the session to the target user; all subsequent actions run as that user.

Configuration Options

enable_masquerade

Enable or disable the masquerading feature.

Values:

• true - Enable masquerading (default)
• false - Disable masquerading

masquerade_token_separator

The character sequence that separates admin username from target username.

Default: ::

Custom example:

'masquerade_token_separator' => '##',

Security Considerations

Security Warning

Masquerading is a powerful debugging tool that bypasses user passwords. Consider these security implications:

Risks:

• Admin can access any user’s account without their knowledge
• Actions are attributed to the target user, so external audit logging is required to keep masquerade sessions traceable to the administrator
• Sensitive data access without consent
• Potential regulatory compliance issues (GDPR, HIPAA, etc.)

Recommendations:

• Only enable when actively troubleshooting
• Disable in production environments when not needed
• Implement external audit logging if masquerading is used regularly
• Document all masquerade sessions for compliance
• Consider disabling if not required: 'enable_masquerade' => false

Disabling Masquerading

For production environments where this feature is not needed:

'enable_masquerade' => false,

XML API Access Control

Control whether the XML API authentication is available system-wide.

Configuration Option

enable_xmlapi

Global enable/disable switch for XML API authentication.

Values:

• true - XML API authentication enabled
• false - XML API authentication disabled system-wide (default)

xmlapi_admin_only

Restricts XML API access to administrator accounts only, even when a non-admin user has a valid XML token.

Values:

• true - Only admin users can access the XML API (default)
• false - Non-admin users with a valid XML token can also access the XML API

Example Configuration

Disable XML API completely:

'enable_xmlapi' => false,

Enable XML API for admin users only (default behavior):

'enable_xmlapi' => true,
'xmlapi_admin_only' => true,

Enable XML API for all users with valid tokens:

'enable_xmlapi' => true,
'xmlapi_admin_only' => false,

Note

XML API access requires all three conditions to be met:

1. enable_xmlapi must be true
2. xmlapi_admin_only must be false (or the user must be an admin)
3. The user account must have XML API enabled in their user settings

Complete Configuration Examples

Maximum Security Configuration

<?php
/**
 * High-security configuration for production environment
 * - Admin access restricted to office IP only
 * - Regular users restricted to internal network
 * - Masquerading disabled
 * - XML API disabled
 */
$custom = [
    'admin_allow_ip' => [
        '203.0.113.50',  // Office static IP
    ],
    'admin_allow_ip_enabled' => true,

    'regularuser_allow_ip' => [
        '10.0.0.0/8',    // Internal network
    ],
    'regularuser_allow_ip_enabled' => true,

    'enable_masquerade' => false,

    'masquerade_token_separator' => '::',

    'enable_xmlapi' => false,

    'xmlapi_admin_only' => true
];

Development/Staging Configuration

<?php
/**
 * Flexible configuration for development environment
 * - No IP restrictions
 * - Masquerading enabled for testing
 * - XML API enabled for all users
 */
$custom = [
    'admin_allow_ip' => [],
    'admin_allow_ip_enabled' => false,

    'regularuser_allow_ip' => [],
    'regularuser_allow_ip_enabled' => false,

    'enable_masquerade' => true,

    'masquerade_token_separator' => '::',

    'enable_xmlapi' => true,

    'xmlapi_admin_only' => false
];

Remote Work Configuration

<?php
/**
 * Configuration for distributed team with VPN
 * - Admin access from VPN only
 * - Regular users from anywhere (MFA required separately)
 * - Masquerading disabled
 * - XML API enabled for admins only
 */
$custom = [
    'admin_allow_ip' => [
        gethostbyname('vpn.company.com'),
    ],
    'admin_allow_ip_enabled' => true,

    'regularuser_allow_ip' => [],
    'regularuser_allow_ip_enabled' => false,

    'enable_masquerade' => false,

    'masquerade_token_separator' => '::',

    'enable_xmlapi' => true,

    'xmlapi_admin_only' => true
];

Troubleshooting

Problem: Locked Out of Admin Account

Symptom: Cannot login as System Administrator

Cause: admin_allow_ip_enabled is true but your IP is not in admin_allow_ip

Solution:

1. Access server via SSH or file manager
2. Edit ~/admin/com/custom/authentication.php
3. Set 'admin_allow_ip_enabled' => false,
4. Or add your IP to admin_allow_ip array
5. Save and try logging in again

Problem: All Users Locked Out

Symptom: No one can login (admin or regular users)

Cause: Both IP restriction features enabled with empty arrays

Solution:

1. Temporarily rename the file:

   mv ~/admin/com/custom/authentication.php ~/admin/com/custom/authentication.php.disabled

2. Login normally
3. Fix the configuration
4. Rename back:

   mv ~/admin/com/custom/authentication.php.disabled ~/admin/com/custom/authentication.php

Problem: Masquerading Not Working

Symptom: Login fails when using admin::user format

Possible causes and solutions:

1. Masquerading is disabled

   • Check: 'enable_masquerade' => true

2. Wrong separator

   • Check the masquerade_token_separator value
   • Use the correct separator (default is ::)

3. Not a System Administrator

   • Masquerading only works for users with admintype = 'a'
   • Regular admins cannot masquerade

4. Target user doesn’t exist

   • Verify the target username is correct and active

Problem: XML API Not Working

Symptom: XML API requests fail with authentication error

Possible causes:

1. Global XML API disabled

   • Check: 'enable_xmlapi' => true

2. Admin-only mode is enabled

   • Check: 'xmlapi_admin_only' => true blocks non-admin users even with a valid token
   • Set to false to allow non-admin users

3. User doesn’t have XML API permission

   • Enable in user account settings separately

4. IP restrictions blocking request

   • Check if request IP is in allowed list

Related Settings

For additional security configurations, see:

• Security Settings - Session timeout, two-factor authentication, and login failure handling
• User Accounts - Individual user XML API and permission settings
• Configuration File Settings - Proxy headers and other advanced config.php settings

Best Practices

1. Always maintain a backup before modifying authentication settings
2. Test in development first before applying to production
3. Document your IP addresses with comments in the file
4. Use version control to track changes to authentication.php
5. Review access logs regularly when using IP restrictions
6. Disable masquerading in production unless actively needed
7. Consider using VPN instead of static IP lists for remote access
8. Audit masquerade usage if enabled in production environments

File Permissions

Ensure proper file permissions for security:

# Recommended permissions (read-write for owner, read for group, none for others)
chmod 640 ~/admin/com/custom/authentication.php

# Ensure proper ownership
chown www-data:www-data ~/admin/com/custom/authentication.php

Note

Adjust www-data to match your web server user (may be apache, nginx, httpd, or similar depending on your system).