Philippe Pittoli 5f3f208798 | ||
---|---|---|
spec | ||
src | ||
.gitignore | ||
README.md | ||
TODO.md | ||
db-password-file | ||
makefile | ||
project.zsh | ||
shard.yml |
README.md
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.
You’ll 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 authd’s 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
authd’s protocol is still subject to change.
Libraries
A AuthD::Client
Crystal class is available to build synchronous clients in 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.