authd/README.md

96 lines
2.3 KiB
Markdown
Raw Normal View History

2019-12-17 16:18:29 +01:00
# authd
authd is a token-based authentication micro-service.
> TODO: explain basic concepts behind `authd`.
2019-12-17 16:18:29 +01:00
## Build
2019-12-17 16:18:29 +01:00
`authd` is written in Crystal.
Youll need the following tools:
2019-12-17 16:18:29 +01:00
- 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.
2019-12-17 16:18:29 +01:00
### 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`.
2019-12-17 16:18:29 +01:00
## APIs
### Protocol
authds protocol is still subject to change.
> TODO: document messages.
2019-12-17 16:18:29 +01:00
### Libraries
> TODO: document basic functions in the `AuthD::Client` class to exchange messages with `authd`.
2019-12-17 16:18:29 +01:00
A `AuthD::Client` Crystal class is available to build synchronous clients in Crystal.
# Authorization rules
2019-12-17 16:18:29 +01:00
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
2019-12-17 16:18:29 +01:00
Admins with 'Read' permission on the '*' resource can:
- list users
2023-06-13 18:34:51 +02:00
- check permissions of other users
2019-12-17 16:18:29 +01:00
Admins with 'Edit' permission on the '*' resource can:
- change data of another user
2019-12-17 16:18:29 +01:00
Admins with 'Admin' permission on the '*' resource (or the 'admin' boolean) can:
2023-06-13 18:34:51 +02:00
- change read-only profile entries
- change permissions
- delete a user
- uprank and downrank admins
2019-12-17 16:18:29 +01:00
## 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.