85 lines
2.2 KiB
Markdown
85 lines
2.2 KiB
Markdown
# authd
|
||
|
||
`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.
|
||
|
||
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
|
||
|
||
`authd` is written in Crystal.
|
||
You’ll need the following tools to build it: `crystal`, `shards` and `make`.
|
||
|
||
```
|
||
make
|
||
make install
|
||
```
|
||
|
||
## Run
|
||
|
||
```
|
||
$ authd --help
|
||
```
|
||
|
||
For a more extensive documentation, please read the manual for both [authd][authdmanual] and [authctl][authctlmanual].
|
||
|
||
See the [configuration example][configuration-example] to avoid long command-line parameters.
|
||
|
||
Also, extensive usage examples are available in the makefiles.
|
||
|
||
## Administration
|
||
|
||
```sh
|
||
# First user in the database is an administrator.
|
||
authctl bootstrap name email
|
||
```
|
||
|
||
```sh
|
||
# Add a user:
|
||
authctl user add login email
|
||
```
|
||
|
||
For a comprehensive list of available commands, please read the [authctl manual][authctlmanual].
|
||
|
||
## Real-life deployment
|
||
|
||
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].
|
||
|
||
### Backup and migration
|
||
|
||
```sh
|
||
# Database backup.
|
||
tar cfz db.tar.gz ./db-authd
|
||
|
||
# Database migration.
|
||
tar xfz db.tar.gz
|
||
```
|
||
|
||
Wasn't that hard, isn't it?
|
||
|
||
## 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.
|
||
|
||
# API and 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/dnsmanager
|
||
[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
|