Commit 26bddda8 authored by ale's avatar ale

Translate README to English for consistency

Add a section on configuration.
parent 89944f5e
Pipeline #2839 passed with stages
in 4 minutes and 40 seconds
L'*accountserver* è il servizio che fa da interfaccia tra il database
utenti e gli altri servizi ed applicazioni interne. Disaccoppia la
struttura dei dati nel database dal concetto di *utente* ed *account*,
ed implementa la *business logic* relativa alle operazioni di alto
livello di gestione degli account.
The *accountserver* is the main interface used to manage the database
of user accounts. Other internal services use it to query and modify
user account information (settings, credentials, etc). It implements
all the validation and business logic related to accounts.
Le motivazioni per la creazione di questo servizio includono:
Motivations for this service stem from our experience with previous
account management strategies:
* La constatazione che le applicazioni lato utente (e lato
amministratore, come *accounts*) operano su astrazioni differenti
rispetto a quanto implementato a basso livello nello schema LDAP
(utenti ed account, anziché oggetti LDAP gerarchici); inoltre, il
codice di traduzione è duplicato.
* the necessity for a high-level API on top of the database layer
(*accounts* and *resources*, instead of nested LDAP objects or SQL
tables), isolating applications from the database structure;
* the desire to have a single authoritative implementation of the data
validation logic, and to have every change to the database go
through it;
* a wish for a cleaner separation between the business logic of
complex operations ("disable a resource", "move an account between
hosts", etc) and their UI. In our ideal model, user interfaces (web
panels, admin tools) are simply thin clients focused on presentation
and interaction, and the logic is implemented in RPC servers.
* I dettagli dell'implementazione di basso livello (LDAP) filtrano
ogni volta che scriviamo automazione che opera su utenti o account.
The service is implemented as an RPC service, without any user
interface. This approach has been preferred over others (like a
library for clients to embed) for a few reasons:
* La business logic delle operazioni di alto livello, come abilitare /
disabilitare un account, o cambiare una password, è spezzata
arbitrariamente tra le applicazioni front-end (come il pannello, o
accounts) e back-end (il vecchio accountserver), il che ne rende
difficile la verifica e la comprensione.
* information on accounts and resources might be aggregated from
multiple backends (an LDAP database, Redis, MySQL for Noblogs, etc)
and we'd like to limit the proliferation of network flows;
* privilege separation: only the accountserver needs write credentials
for the backends;
* a single centralized service offers a simpler target for
logging and monitoring.
Si è preferito un servizio RPC anziché una libreria per alcuni
importanti motivi:
* Le informazioni su utenti ed account vanno aggregate da diversi
backend (LDAP, redis per dati temporanei, MySQL per noblogs, etc),
si vuole evitare una moltiplicazione dei flussi di connettività.
## Data model
* Separazione dei privilegi: se tutte le operazioni di scrittura sul
database utenti sono effettuate da un unico servizio, le
applicazioni front-end possono operare con credenziali di sola
lettura (o nessuna).
The [data model]( offered by *accountserver* is quite
simple: the top-level object is the *user* (an *account*). Each user
owns a number of *resources*, which can be of different
types. Resources have a loose hierarchical structure, and might
themselves contain sub-resources, expressing an association of some
kind (as for instance between a website and the associated MySQL
* Se tutte le operazioni privilegiate sugli account vengono eseguite
da un unico processo, è più facile implementare un buon
auditing e verificarne la copertura.
This data model is meant to work with our legacy user database, but it
is slightly overkill for the simplest cases: for instance a simple
email service might consider users and their email accounts to be the
same thing, while this model would present them as a *user* object
containing an *email* resource with the same name. It is however at
least easily adaptable to most use cases.
# Modello dati
The schema is explicitly defined in [types.go](types.go).
Il modello dati offerto da *accountserver* è piuttosto semplice:
l'oggetto di più alto livello è l'*utente*. Un utente possiede in modo
univoco un certo numero di *risorse*, che possono essere di diversi
*tipi*. Le risorse possono a loro volta avere sotto-risorse,
esprimendo una relazione di associazione di qualche tipo (come ad
esempio tra siti web e database MySQL).
Lo schema è definito esplicitamente in [types.go](types.go).
## API
The service API is documented in [](
# Testing
Per testare questo attrezzo purtroppo serve Java (basta un JRE, il
runtime environment). Questo perché non è affatto facile implementare
un server LDAP per i test, quindi si è scelto di usarne uno esistente:
in particolare un'implementazione Java... su un sistema Debian:
## Extending the service
The business logic (account creation, validation, and all the
high-level operations defined on them) is currently implemented as Go
code within the accountserver itself, in the *actions_\*.go* and
*validators.go* files.
There are specific notes on how to add and modify functionality in
## Testing
Running the integration tests requires, beyond a working Go
development environment, a JRE: we start a test LDAP server locally
(which is written in Java) in order to test the LDAP backend.
On a Debian system this should be enough:
sudo apt install default-jre-headless
dovrebbe bastare (oltre a *golang-go* ovviamente) per poter eseguire i
test con successo.
# Usage
The *accountserver* daemon simply listens on a port for HTTP(S)
requests. Specify the address to listen on with the *--addr*
command-line option.
## Configuration
The configuration is stored in a YAML file, by default
*/etc/accountserver/config.yml*. Known variables include:
* `shards`: map of shards by service, for sharded (partitioned) services
* `available`: map of available shards by service name,
e.g. `{"web": ["1", "2"]}`. Used in resource creation.
* `allowed`: map of allowed shards by service name
* `sso`:
* `public_key`: path to file with SSO public key
* `domain`: SSO domain
* `service`: SSO service for the accountserver
* `groups`: list of allowed groups
* `admin_group`: a specific group that will be granted *admin* privileges
(the ability to read/write data about different users than oneself)
* `user_meta_server`: connection parameters for
the [user-meta-server]( backend
used to store user audit logs
* `url`: URL for the user-meta-server service
* `sharded`: if true, requests to the service will be
partitioned according to the user's *shard* attribute
* `tls_config`: client TLS configuration
* `cert`: path to the client certificate
* `key`: path to the private key
* `ca`: path to the CA used to validate the server
* `auto_enable_encryption`: if true, automatically enable user-level
encryption when a user changes their primary authentication
* `forbidden_usernames` / `forbidden_usernames_file`: list (or file)
containing forbidden usernames
* `forbidden_passwords` / `forbidden_passwords_file`: list (or file)
containing forbidden passwords
* `available_domains`: list of available domains for email resources
* `website_root_dir`: root directory of user websites
* `min_password_len`: minimum length of passwords (default 8)
* `max_password_len`: maximum length of passwords (default 128)
* `min_username_len`: minimum username length (default 3)
* `max_username_len`: maximum username length (default 64)
* `min_backend_uid`: minimum auto-assigned UID (default 1000)
* `max_backend_uid`: maximum auto-assigned UID (default 0, disabled)
* `http_server`: specifies standard parameters for the HTTP server
* `tls`: server-side TLS configuration
* `cert`: path to the server certificate
* `key`: path to the server's private key
* `ca`: path to the CA used to validate clients
* `acl`: TLS-based access controls, a list of entries with the
following attributes:
* `path` is a regular expression to match the request URL path
* `cn` is a regular expression that must match the CommonName
part of the subject of the client certificate
* `max_inflight_requests`: maximum number of in-flight requests to
allow before server-side throttling kicks in
......@@ -27,7 +27,7 @@ type Config struct {
UserMetaDB *clientutil.BackendConfig `yaml:"user_meta_server"`
EnableOpportunisticEncryption bool `yaml:"enable_opportunistic_encryption"`
EnableOpportunisticEncryption bool `yaml:"auto_enable_encryption"`
func (c *Config) compile() error {
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment