authd/README.md

96 lines
2.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# authd
authd is a token-based authentication micro-service.
> TODO: explain basic concepts behind `authd`.
## Build
`authd` is written in Crystal.
Youll need the following tools:
- crystal
- shards
- make
To build authd, run the following commands:
```
make
```
## Deployment
```
$ authd --help
```
> TODO: documentation on how to deploy, including with the mail server and tools.
### Users storage
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.
### Administrating users
> TODO: document how to manage users through `authc`.
## APIs
### Protocol
authds 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
## 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.