Baguette
/
authd
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

README: add + update + fix most explanations. Sill very much WIP.

master
Philippe Pittoli 2023-06-13 18:15:47 +02:00
parent f58de2ce36
commit dab3a70e3e
2 changed files with 38 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
README.md
View File

@ -2,41 +2,31 @@
authd is a token-based authentication micro-service.
> TODO: explain basic concepts behind `authd`.
## Build
`authd` is written in Crystal and uses `build.zsh` as Makefile generator, as
well as shards to fetch dependencies.
You’ll need the following tools to build authd:
`authd` is written in Crystal.
You’ll need the following tools:
- crystal
- shards
- build.zsh
- make
To build authd, run the following commands:
```
shards install
make
```
Note that if you clone authd from its repository, its `Makefile` may be missing.
In such situations, run `build.zsh -c` to generate it, after which `make` should run fine.
## Deployment
```
$ authd --help
usage: authd [options]
-s directory, --storage directory
Directory in which to store users.
-k file, --key-file file JWT key file
-R --allow-registrations
-h, --help Show this help
$
```
> TODO: documentation on how to deploy, including with the mail server and tools.
### Users storage
The storage directory will default to `./storage`.
@ -44,29 +34,11 @@ The storage directory will default to `./storage`.
No SQL database, database management system or other kind of setup is required to run authd and store users.
To migrate an instance of authd, a simple copy of the storage directory will be enough.
Make sure your copy preserves symlinks, as those are extensively used.
### Administrating users
The `authd-user-add` and `authd-user-allow` are tools to add users to authd’s database and to edit their permissions.
> TODO: document how to manage users through `authc`.
The permission level `none` can be used in `authd-user-allow` to remove a permission.
### Key file
authd will provide users with cryptographically signed tokens.
To sign and check those tokens, a shared key is required between authd and services using authd.
authd reads that key from a file to prevent it being visible on the command line when running authd.
Any content is acceptable as a key file.
Example:
```
$ echo "I am a key." > key-file
$ authd -k ./key-file
```
## APIs
@ -74,25 +46,48 @@ $ authd -k ./key-file
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.
```crystal
require "authd"
# Authorization rules
authd = AuthD::Client.new
authd.key = File.read("./some-file").chomp
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
pp! r = authd.get_token?("login", "password")
Admins with 'Read' permission on the '*' resource can:
- list users
pp! r = authd.add_user("login", "password")
Admins with 'Edit' permission on the '*' resource can:
- change data of another user
pp! u = authd.get_user?("login", "password").not_nil!
```
Admins with 'Admin' permission on the '*' resource (or the 'admin' boolean) can:
- change read-only profile entries and permissions
- delete a user
- uprank and downrank admins
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
# WIP: 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.

21
TODO.md
View File

@ -8,27 +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.
Requests work mostly on current user, but some take a *UserID* to identify another user.
Requests should either always work on current user (which implies to create new requests working on another user) or always take an optional *UserID* parameter.
### 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
Admins with 'Read' permission on the '*' resource can:
- list 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 and permissions
- delete a user
- uprank and downrank admins
### Structures, not classes
Maybe in some cases, it could be great to use structures instead of classes.