REMOTE USER Authentication

From VoIPmonitor.org
Revision as of 20:59, 6 January 2026 by Admin (talk | contribs) (Explicitly mention Azure AD as supported OIDC provider)

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 (Azure AD/Entra ID, Keycloak, Okta, Google, 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: Configuring the Apache authentication module itself is beyond the scope of this documentation. Refer to your specific module's documentation:

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 Apache module is setting REMOTE_USER (check with phpinfo() or similar)
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

See Also

AI Summary for RAG

Summary: VoIPmonitor GUI supports REMOTE_USER authentication for integration with external web server authentication modules. Apache handles all authentication (Shibboleth, OpenID Connect, SAML, Kerberos) and passes the authenticated username via REMOTE_USER variable. GUI reads this variable and maps it to internal users for permissions. A default user can be configured for unmatched usernames. The login window can be disabled completely for automatic REMOTE_USER authentication.

Keywords: REMOTE_USER, Shibboleth, SSO, single sign-on, Apache authentication, mod_shib, mod_auth_openidc, mod_auth_mellon, SAML, OpenID Connect, OIDC, Kerberos, external authentication, web server authentication, enterprise SSO, federation, identity provider

Key Questions:

  • How do I integrate VoIPmonitor with Shibboleth?
  • How do I use REMOTE_USER authentication with VoIPmonitor?
  • Can I use OpenID Connect with VoIPmonitor?
  • How do I configure SAML authentication for VoIPmonitor?
  • What Apache modules work with VoIPmonitor for SSO?
  • 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=9559"