REMOTE USER Authentication

From VoIPmonitor.org

Overview

VoIPmonitor GUI can integrate with external authentication systems via the REMOTE_USER server variable. This allows you to use any Apache authentication module that performs user authentication and passes the authenticated username to the application.

Important: The GUI does not implement authentication protocols like Shibboleth, SAML, or OpenID Connect directly. Instead, your web server (Apache) handles all authentication, and the GUI simply reads the resulting username from the REMOTE_USER variable.

Component Role
Apache module Handles authentication (redirects, token validation, session management)
REMOTE_USER variable Contains authenticated username after successful login
VoIPmonitor GUI Reads REMOTE_USER and maps it to GUI user for permissions

Supported Apache Modules

Any Apache module that sets the REMOTE_USER variable can be used:

Module Protocol Use Case
mod_shib Shibboleth/SAML 2.0 Enterprise/academic SSO federations
mod_auth_openidc OpenID Connect OAuth 2.0/OIDC identity providers (Keycloak, Okta, etc.)
mod_auth_mellon SAML 2.0 SAML-based identity providers
mod_auth_basic HTTP Basic Auth Testing and simple setups
mod_auth_kerb Kerberos Active Directory/Windows domain authentication

How It Works

The authentication flow:

  1. User accesses VoIPmonitor GUI URL
  2. Apache module intercepts request and redirects to identity provider (if not authenticated)
  3. User authenticates with identity provider
  4. Identity provider returns success to Apache module
  5. Apache module sets REMOTE_USER server variable with username
  6. VoIPmonitor GUI reads REMOTE_USER and uses it as login name
  7. GUI looks up user in its database for permissions
  8. If user not found, GUI uses the default REMOTE_USER account (if configured)

Prerequisites

  • Web server with authentication module installed and configured (Apache with mod_shib, mod_auth_openidc, etc.)
  • Authentication module configured to protect the GUI directory/location
  • Authentication module configured to pass username via REMOTE_USER
  • GUI users created for each authenticated user, OR a default REMOTE_USER account configured

Note: Full configuration of the authentication module itself is largely beyond the scope of this documentation — see the example configurations below and refer to your specific module's documentation:

Web Server Configuration Examples

These minimal examples show how to protect the VoIPmonitor GUI location and have the web server populate the REMOTE_USER variable. They are starting points only — consult each module's documentation for a production setup.

Apache with Shibboleth (mod_shib)

<Location /voipmonitor>
    AuthType shibboleth
    ShibRequestSetting requireSession 1
    Require valid-user
</Location>

Apache with Kerberos (mod_auth_kerb)

<Location /voipmonitor>
    AuthType Kerberos
    AuthName "VoIPmonitor SSO"
    KrbAuthRealms EXAMPLE.COM
    KrbServiceName HTTP/voipmonitor.example.com@EXAMPLE.COM
    Krb5Keytab /etc/httpd/http.keytab
    KrbMethodNegotiate on
    KrbMethodK5Passwd off
    Require valid-user
</Location>

ℹ️ Note: On Apache 2.4.13+ you may need CGIPassAuth On inside the protected <Location> so REMOTE_USER is passed through to PHP. For Nginx with PHP-FPM, forward it with fastcgi_param REMOTE_USER $remote_user;.

Configuration

Step 1: Enable REMOTE_USER Authentication

  1. Navigate to GUI > Settings > System Configuration
  2. Find the option Use Shibboleth/REMOTE_USER for auth
  3. Enable the checkbox

Step 2: Configure Default User (Optional)

If you want users who don't have a matching GUI account to still be able to log in:

  1. Navigate to GUI > Users & Audit > Users
  2. Select or create a user to be the default for REMOTE_USER logins
  3. Enable the checkbox Default Shibboleth/REMOTE_USER account

When REMOTE_USER provides a username that doesn't exist in GUI, this default user's permissions will be used.

Usage

After Apache authentication completes successfully:

  1. The VoIPmonitor GUI login page shows a Shibboleth/REMOTE_USER button (alongside Google and Microsoft buttons if configured)
  2. Clicking this button uses the REMOTE_USER value as the login name
  3. If the username matches a GUI user, that user's permissions apply
  4. If no match is found, the default REMOTE_USER account is used (if configured)
  5. Login completes automatically

Logout

The logout URL is constructed automatically:

  1. GUI checks for Shib-Handler HTTP header
  2. If present: logout URL = Shib-Handler value + /Logout
  3. If not present: logout URL = HTTP_HOST + /Shibboleth.sso/Logout

Custom Logout URL

For non-Shibboleth modules or custom setups:

  1. Navigate to GUI > Settings > System Configuration
  2. Set Logout URL for Shibboleth/REMOTE_USER to your identity provider's logout endpoint

Disable Login Window Completely

For environments where REMOTE_USER is the only authentication method:

  1. Navigate to GUI > Settings > System Configuration
  2. Enable Disable login window completely

With this option:

  • No login dialog is shown
  • REMOTE_USER authentication happens automatically
  • Users are logged in immediately based on REMOTE_USER value

User Language Setting

When the login window is disabled, users cannot select their language at login. Instead:

  1. Navigate to GUI > Users & Audit > Users
  2. Select the user
  3. Set their preferred language in user settings

Integration with Custom Login Script

REMOTE_USER authentication is compatible with custom login scripts:

  • The REMOTE_USER value is passed to the custom script
  • The script must return the standard structure as documented in WEB_API#Custom_Login
  • Note: Internal GUI users take precedence over custom login users

Troubleshooting

Problem Solution
REMOTE_USER button not visible Verify the Apache module is setting REMOTE_USER (check with phpinfo() or the debug script below)
REMOTE_USER is empty in PHP Web server auth is not reaching PHP. On Apache 2.4.13+ add CGIPassAuth On inside the protected location; behind a reverse proxy forward it explicitly (see below)
REMOTE_USER lost behind a reverse proxy The proxy strips the variable. Forward it, e.g. Apache RequestHeader set REMOTE_USER %{REMOTE_USER}e or Nginx fastcgi_param REMOTE_USER $remote_user;
Login fails with "User not found" Create matching user in GUI OR configure default REMOTE_USER account
Logout doesn't work Configure custom logout URL in System Configuration
Wrong permissions applied Check that the correct user is matched or verify default account permissions

Debugging REMOTE_USER

To verify the web server actually passes REMOTE_USER to PHP, drop a temporary script into the GUI directory and open it in your browser: 

<?php
// test_remote_user.php - DELETE after testing!
echo "REMOTE_USER: " . ($_SERVER['REMOTE_USER'] ?? 'NOT SET') . "\n";
echo "Auth-related server variables:\n";
foreach ($_SERVER as $key => $value) {
    if (strpos($key, 'AUTH') !== false || strpos($key, 'REMOTE') !== false) {
        echo "  $key: $value\n";
    }
}

If it prints NOT SET, the problem is in the web server or proxy layer (see the table above), not in VoIPmonitor.

See Also

AI Summary for RAG

Summary: VoIPmonitor GUI supports REMOTE_USER authentication for integration with external web server authentication modules. Apache (or Nginx) handles all authentication — Shibboleth, OpenID Connect, SAML, Kerberos — and passes the authenticated username via the REMOTE_USER variable. REMOTE_USER auth is a built-in GUI feature enabled with the "Use Shibboleth/REMOTE_USER for auth" checkbox; no custom_login.php script is required. The GUI maps REMOTE_USER to an internal user for permissions, and a default user can be configured for unmatched usernames. The login window can be disabled completely for automatic login. Example Apache (mod_shib, mod_auth_kerb) and Nginx PHP-FPM configurations are included; if REMOTE_USER is empty, enable CGIPassAuth On (Apache 2.4.13+) or forward the variable through the reverse proxy (RequestHeader / fastcgi_param).

Keywords: REMOTE_USER, Shibboleth, SSO, single sign-on, Apache authentication, mod_shib, mod_auth_openidc, mod_auth_mellon, mod_auth_kerb, SAML, OpenID Connect, OIDC, Kerberos, keytab, external authentication, web server authentication, enterprise SSO, federation, identity provider, built-in REMOTE_USER, no custom_login.php, CGIPassAuth, RequestHeader, reverse proxy, Nginx PHP-FPM, fastcgi_param, REMOTE_USER empty, debug REMOTE_USER

Key Questions:

  • How do I integrate VoIPmonitor with Shibboleth?
  • How do I use REMOTE_USER authentication with VoIPmonitor?
  • Do I need a custom_login.php script for REMOTE_USER? (No — it is a built-in GUI checkbox)
  • Can I use OpenID Connect with VoIPmonitor?
  • How do I configure SAML authentication for VoIPmonitor?
  • What Apache modules work with VoIPmonitor for SSO?
  • Why is REMOTE_USER empty / not set in PHP?
  • How do I pass REMOTE_USER through an Apache or Nginx reverse proxy?
  • How do I disable the login window and use automatic authentication?
  • What is the third login button in VoIPmonitor (not Google or Microsoft)?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=REMOTE_USER_Authentication&oldid=11488"