74 lines
3.8 KiB
Markdown
74 lines
3.8 KiB
Markdown
# Orizentic
|
|
|
|
[](https://circleci.com/gh/luminescent-dreams/orizentic/tree/sol)
|
|
|
|
[Documentation](https://docs.rs/orizentic")
|
|
|
|
Orizentic provides a library that streamlines token-based authentication, and a CLI tool for maintaining a database of tokens.
|
|
|
|
## Credit
|
|
|
|
The name is a contraction of Auth(oriz)ation/Auth(entic)ation, and credit goes to [Daria Phoebe Brashear](https://github.com/dariaphoebe).
|
|
|
|
The original idea has been debated online for many years, but the push to make this useful comes from [Aria Stewart](https://github.com/aredridel).
|
|
|
|
## Tokens
|
|
|
|
Tokens are simple [JWTs](https://jwt.io/). This library simplifies the process by easily generating and checking JWTs that have only an issuer, an optional time-to-live, a resource name, a username, and a list of permissions. A typical resulting JWT would look like this:
|
|
|
|
{ iss = Savanni
|
|
, sub = health
|
|
, aud = "Savanni Desktop"
|
|
, exp = null
|
|
, nbf = null
|
|
, iat = 1499650083
|
|
, jti = 9d57a8d8-d11e-43b2-a4d6-7b82ad043994
|
|
, unregisteredClaims = { perms: [ "read", "write" ] }
|
|
}
|
|
|
|
The `issuer` and `audience` (or username) are almost entirely for human readability. In this instance, I issued a token that was intended to be used on my desktop system.
|
|
|
|
The `subject` in this case is synonymous with Resource and is a name for the resource for which access is being granted. Permissions are a simple list of freeform strings. Both of these are flexible within your application and your authorization checks will use them to verify that the token can be used for the specified purpose.
|
|
|
|
## CLI Usage
|
|
|
|
## Library Usage
|
|
|
|
[orizentic - Rust](https://docs.rs/orizentic/1.0.0/orizentic/)
|
|
|
|
There are multiple errata for the documentation:
|
|
|
|
* There are, in fact, now [two functions](https://docs.rs/orizentic/1.0.0/orizentic/filedb/index.html) for saving and loading a database.
|
|
* An example for how to use the library is currently here [for loading the database](https://github.com/luminescent-dreams/fitnesstrax/blob/8c9f3f418ff75675874f7a8e3928ad3f7d134eb4/server/src/web.rs#L64) and here [as part of the AuthMiddleware for an Iron server](https://github.com/luminescent-dreams/fitnesstrax/blob/8c9f3f418ff75675874f7a8e3928ad3f7d134eb4/server/src/server.rs#L156). I apologize for not writing this in more detail yet.
|
|
|
|
## Language support
|
|
|
|
This library and application is only supported for Rust. Haskell and Go support has been discontinued, but can be revived if I discover folks have an interest. The token database is compatible across tools. See readmes in the language directory for usage information.
|
|
|
|
Future Haskell, Go, and other language versions of the library will be done through language bindings against the Rust utilities instead of through my previous clean-room re-implementations.
|
|
|
|
## Nix installation
|
|
|
|
If you have Nix installed on your system, or you run NixOS, create this derivation:
|
|
|
|
orizentic.nix:
|
|
|
|
```
|
|
{ fetchFromGitHub }:
|
|
let src = fetchFromGitHub {
|
|
owner = "luminescent-dreams";
|
|
repo = "orizentic";
|
|
rev = "896140f594fe3c106662ffe2550f289bb68bc0cb";
|
|
sha256 = "05g7b0jiyy0pv74zf89yikf65vi3jrn1da0maj0k9fxnxb2vv7a4";
|
|
};
|
|
in import "${src}/default.nix" {}
|
|
```
|
|
|
|
At this time, you must have nixpkgs-19.03 defined (and preferably pointing to the 19.03 channel). I will parameterize this and update the instructions in the future.
|
|
|
|
I import this into my shell.nix `with import ./orizentic.nix { inherit (pkgs) fetchFromGitHub; };`.
|
|
|
|
For a complete example, see my [shell.nix](https://github.com/savannidgerinel/nix-shell/blob/sol/shell.nix) file.
|
|
|
|
I have not bundled this application for any other distribution, but you should nave no trouble just building with just cargo build --release with Rust-1.33 and Cargo.
|