Add simple README.md and implement CLI command 'config set'.

Cargo.toml

@@ -34,7 +34,7 @@ handlebars = { version = "4.3", features = ["dir_source"] }
 serde_json = "1.0"
 
 # CLI dependencies
-clap = { version = "3.1.15", features = ["derive"] }
+clap = { version = "3.1.15", features = ["derive", "env"] }
 rpassword = "6.0"
 stderrlog = "0.5"
 qr2term = "0.3.1"

README.md

@@ -0,0 +1,145 @@
+### uidc, a lightweight OpenID Connect server ###
+
+uidc is a lightweight OpenID Connect server, implementing the [OpenID Connect
+Core][openid-spec] specification. It's designed as a replacement for
+heavyweight systems like [Keycloak][keycloak] when you want to have SSO without
+a dedicated machine running it, for example on personal or small-scale
+infrastructure.
+
+
+[openid-spec]: https://openid.net/specs/openid-connect-core-1_0.html
+[keycloak]: https://keycloak.org/
+
+uidc is designed in an opinionated fashion, eschewing general flexibility for
+simplicity, which means it is most definitely not a one-size-fits-all solution.
+If you're planning on dealing with hundreds of thousands of users or complicated
+authentication flows, look elsewhere. But, if you want:
+
+- lightweight (runtime memory usage is less than 20MB, even under moderate load)
+- simple (single statically-linked executable and minimal supporting files)
+- ready to use out of the box (as long as your authentication needs fall into the first 95% of use cases)
+- easily configured (configuration is mostly done via CLI, with tab-completion available, and designed for interactive use)
+- flexible, within limits (implements generic role-based access control)
+
+... then uidc might be what you're looking for.
+
+### Getting started ###
+
+(The following will assume that `$UIDC` points to the `uidc` executable.)
+
+The general format of a `uidc` invocation runs something like the following:
+```shell
+./path/to/uidc --db $PATH_TO_DB <noun> <verb> <options>
+```
+
+If a database is not explicitly passed via `--db`, it will default to using a
+file called `uidc.db` in the current directory; you can also set the
+environment variable `UIDC_DB` if that's more convenient.
+
+#### Initial setup ####
+
+First thing is to initialize the database and create a signing key:
+```shell
+$UIDC init
+$UIDC key generate
+```
+
+Next, set some basic information:
+```shell
+$UIDC config set base_url "https://externally-visible-url"
+```
+
+Create yourself a user and add a password (and 2FA if you want, by passing a `-pt` instead of `-p`):
+```shell
+$UIDC user create <username>
+$UIDC user auth -p <username>
+```
+
+Finally, create an OIDC client:
+
+```shell
+$UIDC client create example-client
+```
+
+#### RBAC ####
+
+uidc implements a simple role-based authentication schema. it works as follows:
+
+- users are part of _groups_
+- _groups_ and OIDC clients have _roles_ (permissions) assigned to them
+- _roles_ are further grouped into _scopes_
+
+When authentication tokens (or refresh tokens!) are created, a list of _scopes_
+is requested. All roles in the intersection of the target user's groups and the
+client's available roles will then be attached to that token.
+
+For illustration, let's create three roles, put them into two groups, and
+assign each group to a single user. We'll also put all the roles into a scope
+to make all this available to clients.
+
+```shell
+# users
+$UIDC user create user1
+$UIDC user create user2
+
+# roles
+$UIDC role create roleA
+$UIDC role create roleB
+$UIDC role create roleC
+
+# groups
+$UIDC group create group1
+$UIDC group create group2
+
+$UIDC group attach-user group1 user1
+$UIDC group attach-role group1 roleA
+$UIDC group attach-role group1 roleB
+
+$UIDC group attach-user group2 user2
+$UIDC group attach-role group2 roleB
+$UIDC group attach-role group2 roleC
+
+# scope
+$UIDC scope create example-scope
+$UIDC scope attach-role example-scope roleA
+$UIDC scope attach-role example-scope roleB
+$UIDC scope attach-role example-scope roleC
+```
+
+Now, if we generate some authentication tokens for `user1` and `user2` and peek at the JWT claims:
+
+```shell
+$UIDC token generate-auth --client example-client --username user1 --scopes example-scope \
+    | awk -F. '{print $2}' | base64 -d | jq
+{
+  "sub": "user1",
+  "iss": "https://externally-visible-url/primary",
+  "aud": "example-client",
+  "iat": 1699926032,
+  "exp": 1699926632,
+  "roles": [
+    "roleA",
+    "roleB"
+  ]
+}
+```
+
+and
+
+```shell
+$UIDC token generate-auth --client example-client --username user2 --scopes example-scope \
+    | awk -F. '{print $2}' | base64 -d | jq
+{
+  "sub": "user2",
+  "iss": "https://externally-visible-url/primary",
+  "aud": "example-client",
+  "iat": 1699926035,
+  "exp": 1699926635,
+  "roles": [
+    "roleB",
+    "roleC"
+  ]
+}
+```
+
+

src/cli.rs

@@ -9,7 +9,7 @@ use microrm::prelude::*;
 #[derive(Debug, Parser)]
 #[clap(author, version, about, long_about = None)]
 struct RootArgs {
-    #[clap(short, long, default_value_t = String::from("uidc.db"))]
+    #[clap(short, long, env = "UIDC_DB", default_value_t = String::from("uidc.db"))]
     /// Database path
     db: String,
 
@@ -183,7 +183,8 @@ impl ConfigArgs {
                 println!("config: {:?}", config);
             }
             ConfigCommand::Set { key, value } => {
-                todo!()
+                qi.delete().by(schema::PersistentConfig::Key, &key).exec()?;
+                qi.insert(&schema::PersistentConfig { key: key.clone(), value: value.clone() })?;
             }
             ConfigCommand::Load { toml_path } => {
                 let config = config::Config::build_from(&qi, Some(toml_path));

src/main.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod cli;
 mod client_management;
 mod config;