Authentication server providing tokens for users. Usable by all libIPC services.
 
 
 
 
Go to file
Philippe Pittoli 5f3f208798 Permissions: code simplification. 2023-06-11 21:27:52 +02:00
spec Very basic initial spec. 2019-06-29 03:56:06 +02:00
src Permissions: code simplification. 2023-06-11 21:27:52 +02:00
.gitignore git ignore 2020-01-23 21:04:11 +01:00
README.md New TODO.md + improved password management (simpler code and messages). 2023-06-11 21:10:03 +02:00
TODO.md TODO.md: document some inconsistencies to fix. 2023-06-11 21:27:18 +02:00
db-password-file initial commit 2018-09-22 17:08:28 +00:00
makefile makefile: setup and run-authd rules. 2023-06-08 17:33:43 +02:00
project.zsh Removed unused build targets. 2020-01-04 08:39:37 +01:00
shard.yml New file structure: authd can now be used as a simple library. 2023-02-10 09:51:53 +01:00

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.

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.

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.