### 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, and CPU usage is minimal)
- 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. The database path is
elided from the following examples for brevity.

#### 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
```

And then run the server! By default, it listens on port 2114, but that can be
changed with `--port`.

```shell
$UIDC server
```

#### Realms ####

uidc implements 'realms', or independent authentication domains. By default,
everything is in the `primary` realm, but you can switch to another realm with
`-r`. For example:

```shell
$UIDC realm create secondary
$UIDC -r secondary user create someuser
```

Each realm has its own set of users, groups, roles, and clients.

#### 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"
  ]
}
```