authd/README.md

101 lines
2.4 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.
## Build
`authd` is written in Crystal and uses `build.zsh` as Makefile generator, as
well as shards to fetch dependencies.
Youll need the following tools to build authd:
- crystal
- shards
- build.zsh
- make
To build authd, run the following commands:
```
shards install
make
```
Note that if you clone authd from its repository, its `Makefile` may be missing.
In such situations, run `build.zsh -c` to generate it, after which `make` should run fine.
## Deployment
```
$ authd --help
usage: authd [options]
-s directory, --storage directory
Directory in which to store users.
-k file, --key-file file JWT key file
-R --allow-registrations
-h, --help Show this help
$
```
### 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.
Make sure your copy preserves symlinks, as those are extensively used.
### Administrating users
The `authd-user-add` and `authd-user-allow` are tools to add users to authds database and to edit their permissions.
The permission level `none` can be used in `authd-user-allow` to remove a permission.
### Key file
authd will provide users with cryptographically signed tokens.
To sign and check those tokens, a shared key is required between authd and services using authd.
authd reads that key from a file to prevent it being visible on the command line when running authd.
Any content is acceptable as a key file.
Example:
```
$ echo "I am a key." > key-file
$ authd -k ./key-file
```
## APIs
### Protocol
authds protocol is still subject to change.
### Libraries
A `AuthD::Client` Crystal class is available to build synchronous clients in Crystal.
```crystal
require "authd"
authd = AuthD::Client.new
authd.key = File.read("./some-file").chomp
pp! r = authd.get_token?("login", "password")
pp! r = authd.add_user("login", "password")
pp! u = authd.get_user?("login", "password").not_nil!
```
## 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.