authd/README.md

# 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