NethVoice: Use module agent credentials for users-admin

[Amygos]

Problem

NethVoice currently accesses users-admin through a dedicated ${MODULE_ID}-adm domain administrator created and managed by the module. This keeps a long-lived privileged credential in module configuration and lifecycle flows, duplicates authentication already provided by the NS8 module agent, and does not consistently follow core provider ordering when users-admin moves between nodes.

Proposed solution

Authenticate NethVoice users-admin operations with core-managed module-agent credentials. Resolve the users-admin/http provider for the selected account domain using NS8 provider ordering, keep the public route and FreePBX endpoint aligned with the selected provider, and remove legacy administrator management from setup, settings, and lifecycle operations.

Challenges

• Keep agent credentials confined to core-managed secret state and out of module configuration, the UI, and logs.
• Handle provider changes and temporary unavailability without stale routing or unnecessary service restarts.
• Migrate upgrades, restores, and clones that contain legacy administrator credentials.
• Preserve predictable multi-node provider failover.

How the challenges are addressed

• Use the first core-ordered provider and clear the cached endpoint and public route when no provider is available.
• Persist only the selected endpoint and node, restarting dependent services only when that selection changes.
• Authenticate direct users-admin API calls with credentials supplied through the core-managed agent environment.
• Remove deprecated setup and settings inputs and clean up legacy account state during module lifecycle operations.
• Require NS8 core 3.21.0 or newer, including its ordered provider selection behavior.

References

• Implementation: Replace legacy portal auth with agent creds nethesis/ns8-nethvoice#805
• Dependency: feat(agent): add sortby to list_service_providers ns8-core#1233

[Amygos]

Manual QA suite

Prerequisites

• NethServer core 3.21.0 or newer.

• A three-node cluster for provider-ordering tests.

• Install NethVoice on a worker node, distinct from the leader.

• A disposable internal user domain with one provider on each node.

• A normal test user already present in the domain.

• Working DNS names for NethVoice and NethVoice CTI.

• Unused extension numbers available.

• Administrative UI and SSH access.

• Record these placeholders:

  • <NV_ID>: NethVoice module ID, for example nethvoice1
  • <DOMAIN>: selected user domain
  • <NV_NODE>: node hosting NethVoice
  • <LEADER_NODE>: current leader
  • <OTHER_NODE>: the remaining worker

Provider-selection checkpoint

Use this checkpoint wherever the cases below say “verify the selected provider.”

1. In the cluster UI, open Domains and users.
2. Open <DOMAIN>.
3. Locate the Providers section.
4. Record each provider’s module, node, and displayed address.
5. SSH to the current leader.
6. Run:

redis-cli --raw hget module/<NV_ID>/environment NETHVOICE_USER_PORTAL_URL
redis-cli --raw hget module/<NV_ID>/environment NETHVOICE_USER_PORTAL_NODE

7. Match the returned node with the corresponding provider card.
8. Match the host in the URL with the address shown by that provider.

Pass criteria:

• The URL and node identify the expected provider.

MT-01 — Fresh installation and configuration

1. Open Software center and install the build under test on <NV_NODE>, or from the PR if the current PR is not merged.

2. Start the first-configuration wizard.

3. Choose the existing <DOMAIN>.

4. Continue to the NethVoice configuration page.

5. Fill in the NethVoice and CTI hostnames, timezone, certificate preference, and NethVoice administrator password.

6. Complete configuration and wait for the task to succeed.

7. Open NethVoice Settings.

8. Confirm that:

   • <DOMAIN> is selected.
   • The normal NethVoice administrator-password form is still present.

9. Run the provider-selection checkpoint.

Expected provider: the provider on <NV_NODE>.

10. Open the NethVoice UI and go to Extensions.
11. Confirm that the existing domain test user appears.
12. Open the User portal link and verify that its login page loads.
13. Sign in with the normal test user and then sign out.

Pass criteria:

• Configuration succeeds without legacy portal credentials.
• The local provider is selected.
• User listing and the public user portal work.

MT-02 — User listing, CSV import, and removal

1. In Domains and users, open <DOMAIN> and its Users page.
2. Add a user such as qa_manual_user with a valid password.
3. Open NethVoice Extensions.
4. Wait for synchronization and refresh the page.
5. Confirm that qa_manual_user appears.
6. Assign it an unused extension.
7. Export the users CSV from the Extensions page.
8. Open the downloaded file locally and confirm that qa_manual_user is included.
9. Create a second CSV file with one unique user and unused extension, for example:

qa_csv_user,QA CSV User,2999,QaManual!123456

10. In NethVoice Extensions, select Import and upload the file.
11. Confirm the import and wait until progress reaches 100%.
12. Verify that qa_csv_user appears with extension 2999.
13. Return to Domains and users and confirm that qa_csv_user was created in <DOMAIN>.
14. Open the user portal and sign in as qa_csv_user.
15. Delete both QA users from the domain UI.
16. Refresh NethVoice Extensions until both users disappear.

Pass criteria:

• Existing users can be listed.
• CSV export works.
• CSV import creates the domain user and extension.
• The imported user can authenticate.
• Deleted users disappear after synchronization.

MT-03 — Provider ordering and topology changes

Keep only one NethVoice instance. The multiple instances in this case are account-provider replicas.

At every row below:

1. Wait for the UI task to complete.
2. Refresh the domain’s provider cards.
3. Run the provider-selection checkpoint.
4. Open NethVoice Extensions and confirm the permanent test user remains visible.

Action	Expected selected provider
Start with a provider on every node	Provider on <NV_NODE>
Delete the provider on <NV_NODE> from the domain’s provider menu	Provider on <LEADER_NODE>
From Nodes, promote <OTHER_NODE> to leader	Provider on the newly promoted leader
Delete the provider on the new leader	Remaining provider on the other worker
Add a provider back to the current leader	Provider on the current leader
Add a provider back to <NV_NODE>	Provider on <NV_NODE>
Promote the original leader back, if required	Provider remains on <NV_NODE>

When promoting a node:

1. Open Nodes.
2. Open the target node’s actions menu.
3. Select Promote to leader.
4. Complete the confirmation requested by the UI.
5. Wait for cluster reconnection.
6. Reconnect SSH to the new leader before running Redis checks.

After provider deletion and leader promotion, also open the NethVoice Phonebook and Reports pages. Confirm they load without stale-LDAP or authentication errors.

Pass criteria:

• Selection follows local node → leader → other worker ordering.
• Provider deletion and leader changes update Redis automatically.
• Re-adding a better provider selects it automatically.
• Extensions, Phonebook, Reports, and the user-portal route remain operational.

MT-05 — Upgrade and legacy-user cleanup

Use a cluster with one NethVoice instance running a previous release that creates the legacy administrator.

1. Install the previous release from Software center.
2. Configure it against a disposable user domain.
3. Record its module ID.
4. In the domain’s user list, confirm that <NV_ID>-adm exists.
5. Create a normal baseline user and assign it an extension.
6. Make the build under test available through the normal software repository.
7. Update NethVoice from the UI.
8. Wait for the update task to complete successfully.
9. Return to the domain’s user list.
10. Confirm that <NV_ID>-adm was removed.
11. Confirm that the normal baseline user remains.
12. Open NethVoice Settings and verify that legacy portal fields are absent.
13. Run the provider-selection checkpoint.
14. Open Extensions and verify the baseline user.
15. Perform one small CSV import and remove the imported user through the domain UI.

Pass criteria:

• Upgrade succeeds.
• The legacy administrator is removed.
• Normal domain users remain.
• Provider selection is populated during the upgrade.
• User operations continue working.

MT-06 — Clone

1. Start with one configured and working NethVoice instance.
2. From Applications, open its actions menu and select Clone.
3. Choose a target node and complete the clone operation.
4. Record the clone’s module ID as <CLONE_ID>.
5. Configure the clone with unique NethVoice and CTI hostnames.
6. Select the same <DOMAIN> if requested.
7. Confirm that no legacy portal credentials or provider replica selector is shown.
8. On the leader, run:

redis-cli --raw hget module/<CLONE_ID>/environment NETHVOICE_USER_PORTAL_URL
redis-cli --raw hget module/<CLONE_ID>/environment NETHVOICE_USER_PORTAL_NODE

9. Compare the result with the provider cards for <DOMAIN>.
10. Verify that the clone selected the provider appropriate to its own node topology, rather than retaining the source instance’s endpoint.
11. Repeat the check for the original <NV_ID> and confirm its selection did not change.
12. Open both NethVoice UIs and verify that Extensions loads.
13. Open each instance’s user-portal link.
14. Remove the clone through the UI after collecting evidence.

Pass criteria:

• The clone receives a freshly selected URL and node.
• The original instance remains unchanged.
• Both instances work while the clone exists.
• After cleanup, the cluster returns to one NethVoice instance.