96 lines
2.3 KiB
Markdown
96 lines
2.3 KiB
Markdown
# authd
|
||
|
||
authd is a token-based authentication micro-service.
|
||
|
||
> TODO: explain basic concepts behind `authd`.
|
||
|
||
## Build
|
||
|
||
`authd` is written in Crystal.
|
||
You’ll 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
|
||
|
||
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
|
||
|
||
## 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.
|