From fc796660aaefeb56b0d32a5928800753b0ff8191 Mon Sep 17 00:00:00 2001 From: Davide Principi Date: Mon, 30 Oct 2023 15:30:17 +0100 Subject: [PATCH] docs. Add user portal section to README --- README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/README.md b/README.md index f5293d4e..da1211ca 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,39 @@ Create a new user and assign it to the `developers` group } EOF +## User management web portal + +The `samba` module provides a public web portal where AD users can +authenticate and change their passwords. + +The module registers a Traefik path route, with the domain name as suffix. +For instance: + + https:///users-admin/domain.test/ + +The backend endpoint is advertised as `users-admin` service and can be +discovered in the usual ways, as documented in [Service +discovery](https://nethserver.github.io/ns8-core/modules/service_providers/#service-discovery). +For instance: + + api-cli run module/mymodule1/list-service-providers --data '{"service":"users-admin", "filter":{"domain":"dp.nethserver.net","node":"1"}}' + +The event `service-users-admin-changed` is raised when the serivice +becomes available or is changed. + +The backend of the module runs under the `api-moduled.service` Systemd +unit supervision. Refer also to `api-moduled` documentation, provided by +`ns8-core` repository. + +API implementation code is under `imageroot/api-moduled/handlers/`, which +is mapped to an URL like + + https:///users-admin/domain.test/api/ + +The `.json` files define the API input/output syntax validation, using the +JSON schema language. As such they can give an idea of request/response +payload structure. + ## File server If Samba binds to the **internal VPN interface** (see `ipaddress`