User Management: Difference between revisions

From VoIPmonitor.org
No edit summary
(Fix audit logging menu path, add can_transcribe permission, clarify transcription audit logging)
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:User Management and Permissions}}
{{DISPLAYTITLE:User Management}}
[[Category:GUI manual]]
[[Category:Administration]]


'''This guide provides a comprehensive overview of how to create and manage user accounts, permissions, and access restrictions within the VoIPmonitor web GUI.'''
= User Management =


== Introduction to User Management ==
This page covers user account administration in VoIPmonitor GUI, including creating users, assigning permissions, and configuring access controls.
VoIPmonitor allows you to create multiple user accounts, each with a specific set of permissions and data access restrictions. This is essential for providing secure, role-based access to your call data.


'''Important Default Behavior:'''
'''Navigate to:''' '''Users & Audit > Users''' to manage user accounts.
*A fresh VoIPmonitor installation starts with a single default user: '''admin''' with the password '''admin'''.*
*The moment you create your '''first new user''', this default `admin/admin` account is '''automatically deleted'''.
*'''Golden Rule:''' Your very first action should be to create a new, personal administrator account with a strong password. If you create a non-admin user first and log out, you will lose administrative access to the GUI.


== How to Create or Edit a User ==
== User Authentication Types ==
All user management is done by navigating to '''Settings -> Users'''.
*To create a new user, click the '''New user''' button.
*To edit an existing user, click the pencil icon next to their username in the list.


Changes made to a user's permissions will only take effect after that user logs out and logs back in.
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart LR
    U[User Login] --> L{Auth Type?}
    L -->|Local| DB[(VoIPmonitor DB)]
    L -->|External| CS[custom_login.php]
    CS --> LDAP[LDAP/AD]
    CS --> OTHER[Other Systems]
    DB --> GUI[GUI Access]
    LDAP --> GUI
    OTHER --> GUI
</kroki>


[[File:userform.png|The New/Edit User form where all permissions and restrictions are configured.]]
{| class="wikitable"
|-
! Type !! Description !! Configuration
|-
| '''Local''' || Default authentication using VoIPmonitor's internal database. Passwords stored as hashes. || Manage directly in GUI.
|-
| '''External (LDAP/Custom)''' || Integrate with LDAP/Active Directory via custom login script. || See [[WEB_API#Custom_Login|Custom Login (LDAP)]].
|-
| '''Google SSO''' || OAuth authentication with Google accounts. || See [[Google_Sign_in_usage|Google Sign-In]].
|-
| '''Microsoft SSO''' || OAuth authentication with Microsoft Entra ID (Azure AD). ''Currently in development.'' || See [[Microsoft_Sign_in_usage|Microsoft Sign-In]].
|}


== Understanding User Permissions ==
{{Note|1=For external authentication, the <code>custom_login</code> function '''must''' return a unique numeric <code>id</code> for each user. Shared IDs cause users to share settings.}}
User permissions are divided into two main levels, controlled by a single checkbox.


=== Administrator vs. Standard User ===
== Creating a New User ==
;<code>Is administrator</code>
:This is the most important permission.
:*'''Checked (Admin):''' The user has full, unrestricted access to all GUI features, including creating other users, configuring sensors, and viewing all call data.
:*'''Unchecked (Standard User):''' The user has limited access. They cannot see the "Settings" menu, and their view of call data can be restricted based on the settings below.


=== Feature and Data Access Permissions ===
# Go to '''Users & Audit > Users'''.
These checkboxes control a user's access to specific features and data types.
# Click '''Add user'''.
# Fill in required fields:
#* '''Username''' - Login name (must be unique).
#* '''Password''' - Strong password recommended.
#* '''Email''' - For alerts and password recovery.
#* '''Group''' - Assign to a permission group.
# Configure permissions (see below).
# Click '''Save'''.


==== Core Data Access ====
== Permissions ==
;<code>Can download PCAP</code>
:Allows the user to download the full network packet capture for a call.
;<code>Can listen</code>
:Allows the user to play or download the audio recording (WAV/OGG) of a call.
;<code>Remove RTP from PCAP</code>
:A security feature. If a user with this permission downloads a PCAP, the audio portion (RTP stream) will be automatically stripped from the file, leaving only the signaling data (SIP).


==== GUI Feature Access ====
Permissions control what users can access and modify. Set via:
;<code>Simple CDR</code>
*  '''User-level:''' Direct assignment on individual user.
:Hides advanced QoS and network metrics from the CDR view. This is ideal for users (e.g., in a call center) who only need to see basic call information and listen to recordings.
*  '''Group-level:''' Inherited from assigned group (recommended for easier management).
;<code>Enable capture rules</code>
:Allows the user to view and manage call recording rules.
;<code>Enable alerts</code>
:Allows the user to create, edit, and view alerts in the reporting section.
;<code>Enable audit</code>
:Grants access to the Audit Log, which tracks actions taken by other users.
;''And others:'' Permissions like `Enable active calls`, `Enable register`, and `Enable live sniffer` grant access to their respective sections in the GUI.


==== Sharing Permissions ====
=== Permission Flags ===
;<code>Enable local share CDR</code>
:Allows the user to generate a shareable link for a specific call that can be viewed by others within your organization.
;<code>Enable share.voipmonitor.org</code>
:Allows the user to share a call publicly via the voipmonitor.org sharing service.


== Restricting User Access to Call Data ==
{| class="wikitable"
For standard (non-admin) users, it is crucial to restrict which calls they are allowed to see. This is done using three primary methods on the user's edit page.
|-
! Permission !! Description
|-
| <code>is_admin</code> || Full administrative access (includes upgrade permissions)
|-
| <code>can_cdr</code> || View CDR records and filter form (required for Call-ID search)
|-
| <code>can_play_audio</code> || Play call recordings in GUI
|-
| <code>can_download_audio</code> || Download audio files
|-
| <code>can_listen_active_call</code> || Live call monitoring (ChunkPlayer)
|-
| <code>can_pcap</code> || Download PCAP files
|-
| <code>can_messages</code> || View SIP messages
|-
| <code>can_graphs</code> || Access graphs and charts
|-
| <code>can_livesniffer</code> || Live sniffer functionality
|-
| <code>can_capture_rules</code> || Manage capture rules
|-
| <code>can_reports_edit</code> || Create/edit reports
|-
| <code>can_alerts_edit</code> || Create/edit alerts
|-
| <code>can_dashboard</code> || View dashboards
|-
| <code>can_ipacc</code> || IP accounting features
|-
| <code>can_audit</code> || View audit logs
|-
| <code>can_sensors_operations</code> || Sensor management
|-
| <code>can_transcribe</code> || Use on-demand transcription (Whisper) on call recordings
|}


=== 1. Restriction by IP Address ===
{{Tip|1=Set <code>is_admin</code> to <code>false</code> and use group permissions for granular access control.}}
The '''IP addresses''' text box allows you to limit a user to seeing only calls that involve specific IP addresses or subnets.
*Enter one IP address or CIDR network per line (e.g., `192.168.1.10` or `10.0.0.0/8`).
*The user will only see calls where either the source or destination IP address matches an entry in this list.


=== 2. Restriction by Telephone Number ===
=== Upgrade Permissions ===
The '''Tel. Numbers''' text box limits a user based on the caller or called number.
*Enter one number or prefix per line.
*You can use the `%` character as a wildcard. For example, `4420%` will allow the user to see all calls to or from numbers starting with `4420`.


=== 3. Restriction by Sensor ===
Only users with <code>is_admin</code> role can perform:
By default, all users can see calls from all sensors. In a multi-sensor deployment, you can restrict a user to data from specific sensors.
*   '''GUI upgrades''' via Settings > System > Upgrade
*Click the '''Sensors''' tab on the user's edit page.
*  '''Sensor upgrades''' via Settings > Sensors
*Check the boxes next to the only sensors this user should be able to see data from.
*   '''Auto-upgrade controls'''


[[File:Usersensors.png|The Sensors tab allows you to assign specific data sources to a user.]]
{{Warning|There is no option to hide the upgrade menu for admin users. To restrict upgrades, control access to admin accounts or use CLI: <code>php php/run.php upgrade -f</code>.}}


== Emergency: Recovering a Lost Admin Password ==
== Access Restrictions ==
If you have lost access to all administrator accounts, you cannot reset passwords through the GUI. You must perform an emergency reset directly in the database.


'''Warning:''' These commands directly modify your database. Proceed with caution.
=== Sensor Restrictions ===


=== Option A: Delete All Users (Clean Slate) ===
Restrict users to specific sensors:
This command will delete '''all''' user accounts, resetting the GUI to its initial state where the `admin/admin` user is active.
# Edit user > '''Basic data''' tab.
<pre>
# In '''Enable sensors''', select allowed sensor IDs.
echo "DELETE FROM users;" | mysql voipmonitor
# Users will only see CDR from permitted sensors.
</pre>
 
You can then log in with `admin/admin` and recreate your user accounts.
=== IP-Based Login Restrictions ===
 
Restrict login to specific IP addresses:
# Edit user > '''Secure users''' tab.
# Enable '''Enable remote addresses'''.
# Add allowed IP addresses/ranges.
 
{{Warning|If you lock yourself out, you must access the database directly to remove IP restrictions.}}
 
=== CDR Data Restrictions ===
 
Restrict which CDR data users can view based on phone numbers, IP addresses, or domains:
 
# Edit user or group > '''restrictions''' tab.
# Add filter criteria.
# Configure boolean logic (see below).
 
{{Note|The '''restrictions''' tab filters CDR query results. The '''Secure users''' tab controls login IP addresses. These are different functions.}}
 
==== AND vs OR Logic ====
 
By default, '''AND logic''' is used: CDR must match ALL conditions.
 
To enable '''OR logic''' (match ANY condition):
# In the '''restrictions''' tab, scroll to bottom.
# Check '''OR condition''' checkbox.
# Save changes.
 
== User Groups ==
 
Manage groups in '''Users & Audit > Groups''':
*  Define permission templates for multiple users.
*  Assign users to groups for consistent access control.
*  Changes to group permissions apply to all members.
 
== Audit Logging ==
 
Track user actions for compliance (GDPR, HIPAA). All sensitive GUI actions are logged, including on-demand transcription requests.
 
{| class="wikitable"
|-
! Method !! Configuration
|-
| '''GUI Audit''' || Enabled by default. View logs in '''Users & Audit > Audit'''. Configure per-user settings in '''Users & Audit > Users/Groups'''.
|-
| '''File-based Audit''' || Set <code>AUDIT_LOG_FILE</code> in <code>configuration.php</code>.
|-
| '''Per-user Audit''' || Set '''Enable audit''' to ''auto'' or ''yes'' on individual users.
|}
 
== Troubleshooting ==
 
=== User Cannot Log In ===
 
*  Check IP restrictions in '''Secure users''' tab.
*  Verify username/password (case-sensitive).
*  Check if account is disabled.
*  For LDAP: Test with <code>php scripts/custom_login.php</code>.
 
=== Permission Changes Not Taking Effect ===
 
*  User must log out and log back in.
*  Clear browser cache if issues persist.
*  Verify group membership if using group permissions.
 
=== Empty Dashboard Graphs for Restricted Users ===
 
'''Symptom:''' User sees empty graphs while admin sees data correctly.
 
'''Cause:''' Group IP restrictions filter out required data sources.
 
'''Solution:'''
# Navigate to '''Users & Audit > Groups'''.
# Edit the affected group > '''restrictions''' tab.
# Adjust or remove IP restrictions.
# User must refresh browser.
 
{{Tip|To verify: temporarily clear all group restrictions. If graphs appear, restrictions were blocking data.}}
 
=== Cannot Search by Call ID ===
 
'''Cause:''' Missing <code>can_cdr</code> permission.
 
'''Solution:''' Enable '''Allow to view CDR''' checkbox on user profile, then have user re-login.
 
=== Forgot Admin Password ===
 
Reset via database:
 
<syntaxhighlight lang="sql">
UPDATE users SET password = MD5('newpassword') WHERE username = 'admin';
</syntaxhighlight>
 
{{Warning|Log in immediately and change password through GUI for better security.}}
 
=== Different Search Results Between Users ===
 
Even with identical permissions, users may see different results due to:
 
# '''Timezone setting:''' Compare timezone selector (top right of CDR view) between users.
# '''User restrictions:''' Check '''restrictions''' tab for IP/number filters.
# '''Sensor restrictions:''' Check '''Basic data''' > '''Enable sensors'''.
# '''Group restrictions:''' Verify group settings in '''Users & Audit > Groups'''.
 
== Advanced: Database-Level Operations ==
 
User restriction filters are stored in the <code>users</code> table, <code>number</code> column.
 
<syntaxhighlight lang="sql">
-- View all user restrictions
SELECT username, number FROM users;
 
-- Find restrictions with specific pattern (escape backslashes)
SELECT username, number FROM users WHERE number LIKE '%\\\\*%';
 
-- Update restrictions
UPDATE users SET number = '<filter>' WHERE username = 'username';
</syntaxhighlight>
 
{{Warning|Direct database changes bypass GUI validation. Test in non-production first. Users must re-login after changes.}}
 
== See Also ==
 
* [[WEB_API#Custom_Login|Custom Login (LDAP)]]
* [[Google_Sign_in_usage|Google Sign-In Integration]]
* [[Microsoft_Sign_in_usage|Microsoft Sign-In Integration]]
* [[Call_Detail_Record_-_CDR|CDR View Documentation]]


=== Option B: Add a Temporary Admin User ===
This command inserts a new, temporary user named '''test''' with the password '''testtest''' and full administrator rights.
<pre>
echo "INSERT INTO users SET username='test', name='test', password=MD5('testtest'), is_admin=1;" | mysql voipmonitor
</pre>
After running this, log in as `test/testtest`, reset the password of your original admin account, and then '''immediately delete the temporary `test` user''' from within the GUI.


== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' This guide provides a comprehensive overview of user management in the VoIPmonitor GUI. It begins by explaining the default `admin/admin` account and the critical rule that it is deleted upon the creation of the first new user. The guide details the process of creating and editing users under "Settings -> Users" and explains the key permission fields, distinguishing between an "Is administrator" account and a standard user. It covers permissions for data access (PCAP, audio), feature access (simple CDR, alerts, audit log), and sharing. A major section is dedicated to restricting user access to specific calls, detailing how to filter a user's view by IP address, telephone number prefix, and by specific sensors in a multi-sensor deployment. Finally, it provides two emergency command-line procedures for recovering lost admin access by directly modifying the database: one to delete all users and reset to default, and another to insert a temporary admin account.
 
'''Keywords:''' user management, users, permissions, rights, access control, administrator, admin, standard user, restrict, filter, IP address, telephone number, sensor, password reset, lost password, `DELETE FROM users`
'''Summary:''' Guide to VoIPmonitor user management covering local users and LDAP/custom authentication (requires unique numeric ID per user), permission flags (can_cdr, can_play_audio, can_pcap, is_admin, etc.), upgrade permissions (only is_admin role users can perform GUI/sensor upgrades via web interface, no option to hide upgrade menu for admin users), sensor access restrictions (Basic data tab), IP-based login control (Secure users tab), CDR data restrictions (restrictions tab with AND/OR logic), Google and Microsoft SSO integration, audit logging, and user groups. Troubleshooting covers login issues, empty dashboard graphs for restricted groups, can_cdr permission for Call ID search, different search results between users (timezone, restrictions), and admin password reset via database.
 
'''Keywords:''' user management, permissions, access control, LDAP, custom login, sensor restrictions, IP restrictions, CDR restrictions, restrictions tab, OR condition, AND logic, audit log, user groups, password reset, Google Sign-In, Microsoft Sign-In, SSO, can_cdr, is_admin, empty dashboard graphs, group restrictions, users table, Call ID search, upgrade permissions, admin upgrade, GUI upgrade, sensor upgrade, timezone
 
'''Key Questions:'''
'''Key Questions:'''
* How do I create a new user in VoIPmonitor?
* How do I create a new user in VoIPmonitor?
* What is the difference between an admin and a standard user?
* How do I restrict a user to specific sensors?
* How can I restrict a user to only see calls from a specific customer or IP range?
* How do I configure LDAP authentication for VoIPmonitor?
* How can I limit a user's access to only certain sensors?
* What permissions are available for VoIPmonitor users?
* What do the permissions like "Simple CDR" or "Can download PCAP" do?
* How do I reset the admin password in VoIPmonitor?
* I lost my admin password, how can I get back into the GUI?
* How do I restrict user login by IP address?
* What is the default username and password for VoIPmonitor?
* How do I set up user groups with shared permissions?
* Why are dashboard graphs empty for a restricted group user?
* How do I configure OR logic between user restrictions?
* Why can't a user search by Call ID in the CDR view?
* What permission is required for CDR view access?
* Who can perform upgrades in the VoIPmonitor GUI?
* Why do two users with same permissions see different search results?

Latest revision as of 16:35, 13 January 2026


User Management

This page covers user account administration in VoIPmonitor GUI, including creating users, assigning permissions, and configuring access controls.

Navigate to: Users & Audit > Users to manage user accounts.

User Authentication Types

Type Description Configuration
Local Default authentication using VoIPmonitor's internal database. Passwords stored as hashes. Manage directly in GUI.
External (LDAP/Custom) Integrate with LDAP/Active Directory via custom login script. See Custom Login (LDAP).
Google SSO OAuth authentication with Google accounts. See Google Sign-In.
Microsoft SSO OAuth authentication with Microsoft Entra ID (Azure AD). Currently in development. See Microsoft Sign-In.

ℹ️ Note: For external authentication, the custom_login function must return a unique numeric id for each user. Shared IDs cause users to share settings.

Creating a New User

  1. Go to Users & Audit > Users.
  2. Click Add user.
  3. Fill in required fields:
    • Username - Login name (must be unique).
    • Password - Strong password recommended.
    • Email - For alerts and password recovery.
    • Group - Assign to a permission group.
  4. Configure permissions (see below).
  5. Click Save.

Permissions

Permissions control what users can access and modify. Set via:

  • User-level: Direct assignment on individual user.
  • Group-level: Inherited from assigned group (recommended for easier management).

Permission Flags

Permission Description
is_admin Full administrative access (includes upgrade permissions)
can_cdr View CDR records and filter form (required for Call-ID search)
can_play_audio Play call recordings in GUI
can_download_audio Download audio files
can_listen_active_call Live call monitoring (ChunkPlayer)
can_pcap Download PCAP files
can_messages View SIP messages
can_graphs Access graphs and charts
can_livesniffer Live sniffer functionality
can_capture_rules Manage capture rules
can_reports_edit Create/edit reports
can_alerts_edit Create/edit alerts
can_dashboard View dashboards
can_ipacc IP accounting features
can_audit View audit logs
can_sensors_operations Sensor management
can_transcribe Use on-demand transcription (Whisper) on call recordings

💡 Tip: Set is_admin to false and use group permissions for granular access control.

Upgrade Permissions

Only users with is_admin role can perform:

  • GUI upgrades via Settings > System > Upgrade
  • Sensor upgrades via Settings > Sensors
  • Auto-upgrade controls

⚠️ Warning: There is no option to hide the upgrade menu for admin users. To restrict upgrades, control access to admin accounts or use CLI: php php/run.php upgrade -f.

Access Restrictions

Sensor Restrictions

Restrict users to specific sensors:

  1. Edit user > Basic data tab.
  2. In Enable sensors, select allowed sensor IDs.
  3. Users will only see CDR from permitted sensors.

IP-Based Login Restrictions

Restrict login to specific IP addresses:

  1. Edit user > Secure users tab.
  2. Enable Enable remote addresses.
  3. Add allowed IP addresses/ranges.

⚠️ Warning: If you lock yourself out, you must access the database directly to remove IP restrictions.

CDR Data Restrictions

Restrict which CDR data users can view based on phone numbers, IP addresses, or domains:

  1. Edit user or group > restrictions tab.
  2. Add filter criteria.
  3. Configure boolean logic (see below).

ℹ️ Note: The restrictions tab filters CDR query results. The Secure users tab controls login IP addresses. These are different functions.

AND vs OR Logic

By default, AND logic is used: CDR must match ALL conditions.

To enable OR logic (match ANY condition):

  1. In the restrictions tab, scroll to bottom.
  2. Check OR condition checkbox.
  3. Save changes.

User Groups

Manage groups in Users & Audit > Groups:

  • Define permission templates for multiple users.
  • Assign users to groups for consistent access control.
  • Changes to group permissions apply to all members.

Audit Logging

Track user actions for compliance (GDPR, HIPAA). All sensitive GUI actions are logged, including on-demand transcription requests.

Method Configuration
GUI Audit Enabled by default. View logs in Users & Audit > Audit. Configure per-user settings in Users & Audit > Users/Groups.
File-based Audit Set AUDIT_LOG_FILE in configuration.php.
Per-user Audit Set Enable audit to auto or yes on individual users.

Troubleshooting

User Cannot Log In

  • Check IP restrictions in Secure users tab.
  • Verify username/password (case-sensitive).
  • Check if account is disabled.
  • For LDAP: Test with php scripts/custom_login.php.

Permission Changes Not Taking Effect

  • User must log out and log back in.
  • Clear browser cache if issues persist.
  • Verify group membership if using group permissions.

Empty Dashboard Graphs for Restricted Users

Symptom: User sees empty graphs while admin sees data correctly.

Cause: Group IP restrictions filter out required data sources.

Solution:

  1. Navigate to Users & Audit > Groups.
  2. Edit the affected group > restrictions tab.
  3. Adjust or remove IP restrictions.
  4. User must refresh browser.

💡 Tip: To verify: temporarily clear all group restrictions. If graphs appear, restrictions were blocking data.

Cannot Search by Call ID

Cause: Missing can_cdr permission.

Solution: Enable Allow to view CDR checkbox on user profile, then have user re-login.

Forgot Admin Password

Reset via database:

UPDATE users SET password = MD5('newpassword') WHERE username = 'admin';

⚠️ Warning: Log in immediately and change password through GUI for better security.

Different Search Results Between Users

Even with identical permissions, users may see different results due to:

  1. Timezone setting: Compare timezone selector (top right of CDR view) between users.
  2. User restrictions: Check restrictions tab for IP/number filters.
  3. Sensor restrictions: Check Basic data > Enable sensors.
  4. Group restrictions: Verify group settings in Users & Audit > Groups.

Advanced: Database-Level Operations

User restriction filters are stored in the users table, number column.

-- View all user restrictions
SELECT username, number FROM users;

-- Find restrictions with specific pattern (escape backslashes)
SELECT username, number FROM users WHERE number LIKE '%\\\\*%';

-- Update restrictions
UPDATE users SET number = '<filter>' WHERE username = 'username';

⚠️ Warning: Direct database changes bypass GUI validation. Test in non-production first. Users must re-login after changes.

See Also


AI Summary for RAG

Summary: Guide to VoIPmonitor user management covering local users and LDAP/custom authentication (requires unique numeric ID per user), permission flags (can_cdr, can_play_audio, can_pcap, is_admin, etc.), upgrade permissions (only is_admin role users can perform GUI/sensor upgrades via web interface, no option to hide upgrade menu for admin users), sensor access restrictions (Basic data tab), IP-based login control (Secure users tab), CDR data restrictions (restrictions tab with AND/OR logic), Google and Microsoft SSO integration, audit logging, and user groups. Troubleshooting covers login issues, empty dashboard graphs for restricted groups, can_cdr permission for Call ID search, different search results between users (timezone, restrictions), and admin password reset via database.

Keywords: user management, permissions, access control, LDAP, custom login, sensor restrictions, IP restrictions, CDR restrictions, restrictions tab, OR condition, AND logic, audit log, user groups, password reset, Google Sign-In, Microsoft Sign-In, SSO, can_cdr, is_admin, empty dashboard graphs, group restrictions, users table, Call ID search, upgrade permissions, admin upgrade, GUI upgrade, sensor upgrade, timezone

Key Questions:

  • How do I create a new user in VoIPmonitor?
  • How do I restrict a user to specific sensors?
  • How do I configure LDAP authentication for VoIPmonitor?
  • What permissions are available for VoIPmonitor users?
  • How do I reset the admin password in VoIPmonitor?
  • How do I restrict user login by IP address?
  • How do I set up user groups with shared permissions?
  • Why are dashboard graphs empty for a restricted group user?
  • How do I configure OR logic between user restrictions?
  • Why can't a user search by Call ID in the CDR view?
  • What permission is required for CDR view access?
  • Who can perform upgrades in the VoIPmonitor GUI?
  • Why do two users with same permissions see different search results?