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
accountserver accountserver
============= =============
L'*accountserver* è il servizio che fa da interfaccia tra il database The *accountserver* is the main interface used to manage the database
utenti e gli altri servizi ed applicazioni interne. Disaccoppia la of user accounts. Other internal services use it to query and modify
struttura dei dati nel database dal concetto di *utente* ed *account*, user account information (settings, credentials, etc). It implements
ed implementa la *business logic* relativa alle operazioni di alto all the validation and business logic related to accounts.
livello di gestione degli account.
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 * the necessity for a high-level API on top of the database layer
amministratore, come *accounts*) operano su astrazioni differenti (*accounts* and *resources*, instead of nested LDAP objects or SQL
rispetto a quanto implementato a basso livello nello schema LDAP tables), isolating applications from the database structure;
(utenti ed account, anziché oggetti LDAP gerarchici); inoltre, il * the desire to have a single authoritative implementation of the data
codice di traduzione è duplicato. 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 The service is implemented as an RPC service, without any user
ogni volta che scriviamo automazione che opera su utenti o account. 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 / * information on accounts and resources might be aggregated from
disabilitare un account, o cambiare una password, è spezzata multiple backends (an LDAP database, Redis, MySQL for Noblogs, etc)
arbitrariamente tra le applicazioni front-end (come il pannello, o and we'd like to limit the proliferation of network flows;
accounts) e back-end (il vecchio accountserver), il che ne rende * privilege separation: only the accountserver needs write credentials
difficile la verifica e la comprensione. 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 ## Data model
backend (LDAP, redis per dati temporanei, MySQL per noblogs, etc),
si vuole evitare una moltiplicazione dei flussi di connettività.
* Separazione dei privilegi: se tutte le operazioni di scrittura sul The [data model](DATAMODEL.md) offered by *accountserver* is quite
database utenti sono effettuate da un unico servizio, le simple: the top-level object is the *user* (an *account*). Each user
applicazioni front-end possono operare con credenziali di sola owns a number of *resources*, which can be of different
lettura (o nessuna). 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
database).
* Se tutte le operazioni privilegiate sugli account vengono eseguite This data model is meant to work with our legacy user database, but it
da un unico processo, è più facile implementare un buon is slightly overkill for the simplest cases: for instance a simple
auditing e verificarne la copertura. 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 [API.md](API.md).
# Testing
Per testare questo attrezzo purtroppo serve Java (basta un JRE, il ## Extending the service
runtime environment). Questo perché non è affatto facile implementare
un server LDAP per i test, quindi si è scelto di usarne uno esistente: The business logic (account creation, validation, and all the
in particolare un'implementazione Java... su un sistema Debian: 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
[CONTRIBUTING.md](CONTRIBUTING.md).
## 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 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](https://git.autistici.org/id/usermetadb) 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
(password)
* `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 { ...@@ -27,7 +27,7 @@ type Config struct {
UserMetaDB *clientutil.BackendConfig `yaml:"user_meta_server"` UserMetaDB *clientutil.BackendConfig `yaml:"user_meta_server"`
EnableOpportunisticEncryption bool `yaml:"enable_opportunistic_encryption"` EnableOpportunisticEncryption bool `yaml:"auto_enable_encryption"`
} }
func (c *Config) compile() error { 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