From 5f3653655466d2caa14cee3c30bb8fe5eebd4180 Mon Sep 17 00:00:00 2001 From: Philippe Pittoli Date: Wed, 11 Dec 2024 13:25:08 +0100 Subject: [PATCH] README update (and split). --- API.md | 34 +++++++++++++++ DESIGN-CHOICES.md | 12 +++++ README.md | 92 +++++++++++++++++---------------------- TODO.md | 5 --- configuration-example.yml | 50 +++++++++++++++++++++ man/authctl.1 | 4 +- 6 files changed, 139 insertions(+), 58 deletions(-) create mode 100644 API.md create mode 100644 DESIGN-CHOICES.md create mode 100644 configuration-example.yml diff --git a/API.md b/API.md new file mode 100644 index 0000000..090521d --- /dev/null +++ b/API.md @@ -0,0 +1,34 @@ +> This file is still very much a WIP. + +### Protocol + +authd’s protocol is still subject to change. + +> TODO: document messages. + +### Libraries + +> TODO: document basic functions in the `AuthD::Client` class to exchange messages with `authd`. + +A `AuthD::Client` Crystal class is available to build synchronous clients in Crystal. + +### Authorization rules + +Logged users can: +- retrieve public data of any user **individually** +- change their own data: password, email address, profile entries (except the read-only ones) +- delete their account +- check their own permissions + +Admins with 'Read' permission on the '*' resource can: +- list users +- check permissions of other users + +Admins with 'Edit' permission on the '*' resource can: +- change data of another user + +Admins with 'Admin' permission on the '*' resource (or the 'admin' boolean) can: +- change read-only profile entries +- change permissions +- delete a user +- uprank and downrank admins diff --git a/DESIGN-CHOICES.md b/DESIGN-CHOICES.md new file mode 100644 index 0000000..392345a --- /dev/null +++ b/DESIGN-CHOICES.md @@ -0,0 +1,12 @@ +> This file is still very much a WIP. + +An user has a number, a login, an email address, a profile (`Hash(String, JSON::Any)`) and permissions. +An `admin` boolean also tells weither or not the user is an administrator. + +**Requests work mostly on current user**. +Some take a *UserID* to identify another user (its number or its login, both are valid), which often implies admin permissions. + +**Permissions** are: None, Read, Edit, Admin. +Plus, the `admin` boolean value in the `AuthD::User` class. + +> TODO: continue explaining design choices. diff --git a/README.md b/README.md index d117637..414dabe 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ # authd -`authd` is a token-based authentication micro-service based on [libipc][libipc]. +`authd` is a (JWT) token-based authentication micro-service based on [libipc][libipc]. +`authd` stores users (login, encrypted password), their profile (arbitrary data) and their *permissions*. +For example, `authd` is used by [dnsmanagerd][dnsmanagerd] to handle authentication and permissions. -> TODO: explain basic concepts behind `authd`. +No SQL, the entire database is stored in plain files, thanks to [the DODB database library][dodb]. + +The [netlibre service][netlibre] is the first to use `authd` in a real-life deployment. ## Build @@ -20,55 +24,43 @@ make install $ authd --help ``` -> TODO: documentation on how to deploy, including with the mail server and tools. +For a more extensive documentation, please read the manual for both [authd][authdmanual] and [authctl][authctlmanual]. -### Users storage +See the [configuration example][configuration-example] to avoid long command-line parameters. -The storage directory will default to `./storage`. +Also, extensive usage examples are available in the makefiles. -No SQL database, database management system or other kind of setup is required to run authd and store users. +## Administration -To migrate an instance of authd, a simple copy of the storage directory will be enough. +```sh +# First user in the database is an administrator. +authctl bootstrap name email +``` -### Administrating users +```sh +# Add a user: +authctl user add login email +``` -> TODO: document how to manage users through `authctl`. +For a comprehensive list of available commands, please read the [authctl manual][authctlmanual]. +## Real-life deployment -## APIs +For a real-life deployment, you might want to enable registration. +In this case, you need to get a `mailer` application to send template emails. +See [an example of such application][mailer]. -### Protocol +### Backup and migration -authd’s protocol is still subject to change. +```sh +# Database backup. +tar cfz db.tar.gz ./db-authd -> TODO: document messages. +# Database migration. +tar xfz db.tar.gz +``` -### Libraries - -> TODO: document basic functions in the `AuthD::Client` class to exchange messages with `authd`. - -A `AuthD::Client` Crystal class is available to build synchronous clients in Crystal. - -# Authorization rules - -Logged users can: -- retrieve public data of any user **individually** -- change their own data: password, email address, profile entries (except the read-only ones) -- delete their account -- check their own permissions - -Admins with 'Read' permission on the '*' resource can: -- list users -- check permissions of other users - -Admins with 'Edit' permission on the '*' resource can: -- change data of another user - -Admins with 'Admin' permission on the '*' resource (or the 'admin' boolean) can: -- change read-only profile entries -- change permissions -- delete a user -- uprank and downrank admins +Wasn't that hard, isn't it? ## Contributing @@ -76,19 +68,17 @@ Pull requests are welcome. For major changes, please open an issue first to disc Please make sure to update tests as appropriate. -# WIP: design choices +# API and design choices -An user has a number, a login, an email address, a profile (`Hash(String, JSON::Any)`) and permissions. -An `admin` boolean also tells weither or not the user is an administrator. - -**Requests work mostly on current user**. -Some take a *UserID* to identify another user (its number or its login, both are valid), which often implies admin permissions. - -**Permissions** are: None, Read, Edit, Admin. -Plus, the `admin` boolean value in the `AuthD::User` class. - -> TODO: continue explaining design choices. +See [API.md][API] and [DESIGN-CHOICES.md][design]. [libipc]: https://git.baguette.netlib.re/Baguette/libipc [dnsmanagerd]: https://git.baguette.netlib.re/Baguette/dnsmanagerd -[netlibre]: https://netlib.re +[netlibre]: https://www.netlib.re +[configuration-example]: ./configuration-example.yml +[mailer]: https://git.baguette.netlib.re/Baguette/mailer +[authdmanual]: ./man/authd.1 +[authctlmanual]: ./man/authctl.1 +[dodb]: https://git.baguette.netlib.re/Baguette/dodb.cr +[API]: ./API.md +[design]: ./DESIGN-CHOICES.md diff --git a/TODO.md b/TODO.md index 3b45dc3..dc87140 100644 --- a/TODO.md +++ b/TODO.md @@ -8,11 +8,6 @@ A combinaison of both is fine as long as the logic is comprehensively documented A simple error message is given instead of specific messages for each recurring error. In the same time, some exceptions (such as **AdminAuthenticationException**) are used a few times for the same kind of errors. -### New features - -- On login: inform the user he doesn't have an email address. - This happens when the user was migrated. - ### Structures, not classes Maybe in some cases, it could be great to use structures instead of classes. diff --git a/configuration-example.yml b/configuration-example.yml new file mode 100644 index 0000000..c8934d4 --- /dev/null +++ b/configuration-example.yml @@ -0,0 +1,50 @@ +# Login and password so `authctl` can be authenticated to `authd`. +login: admin +pass: secret + +# In case you have a special `mailer` application. +# Read the manual to understand how it is invoked. +mailer_exe: /usr/local/bin/my-special-mailer + +# File used as password to encrypt user passwords. +secret_key_file: /var/authd/password + +# Path to the database. +storage_directory: /var/authd/db + +# Does symlinks have to be recreated each time the app starts? +#recreate_indexes: false + +# Are registrations open? Does it require an email? +registrations: true +require_email: true + +# Name of the email templates for account activation and password recovery. +activation_template: netlibre-email-activation +recovery_template: netlibre-email-recovery + +# Name of the `authd` IPC service. +#service_name: auth + +# Read-only user profile keys (to prevent modification from third-parties). +#read_only_profile_keys: [] + +# +# Verbosity-related options. +# + +#verbosity: 4 + +#print_password_recovery_parameters: false + +# IPC-related variables. By default, only print errors and exceptions. +#print_ipc_timer: false +#print_ipc_connection: false +#print_ipc_disconnection: false +#print_ipc_extra_socket: false +#print_ipc_message_received: false +#print_ipc_message_sent: false +#print_ipc_switch: false +#print_ipc_error: true +#print_ipc_exception: true +#print_keepalive: false diff --git a/man/authctl.1 b/man/authctl.1 index 3eac52c..0803189 100644 --- a/man/authctl.1 +++ b/man/authctl.1 @@ -120,9 +120,9 @@ Operations on users. .Nm authctl .Ar user No .Ar subcommand No - -.Ar subcommand : No +.br .in +4 +Subcommands: .Bl -tag -width "change-password" -compact .It Li add Adding a user to the DB.