# keycloak-pam

Tiny PAM module to perform authentication against a keycloak instance.

Testing and development are done within a nix environment, if you don't plan to use nix extract the pieces you care about, but we only support nix configuration.

# System Configuration

This is being worked on, refer to the test configuration at [`tests/nixos/configuration.nix`](./tests/nixos/configuration.nix).

# Arguments

Module can be easily configured with PAM arguments, for the sake of completeness refer to the source code.

You can `cargo doc` to find the documentation for this at `keycloak_pam > args > Args`.

# Restrictions and Guarantees

With the purpose of being tiny and minimal, the module uses libcurl for the few requests it makes, so HTTP/S and all networking behavior is offloaded to it.

This is also made in rust, which means default `String` and `&str` are guaranteed to be UTF-8 encoded and invalid UTF-8 input might fail. I did try to use OS and C strings for all input, but I recommend still avoiding non-UTF8 input.

The code should **NEVER** panic (aside from memory management issues), no `unwrap`, `expect` or such methods should ever be used, slice indexing is avoided and errors are gracefully managed.

To check the group, keycloak-pam uses libc's `getgrnam_r`, this takes a buffer we hardcoded to 4 KiB, if there happens to be a group bigger than this, keycloak-pam won't be able to handle and will fail explaining this.

# Behavior

To authenticate users, the module uses the endpoint `{BASE_URL}/realms/{realm}/protocol/openid-connect/token` as a configured client. This needs a client ID and its secret that you need to get and configure per realm.

A curl request you can use anywhere to test this is:

```
curl -X POST http://keycloak-pam.test/realms/master/protocol/openid-connect/token \
    -d grant_type=password \
    -d username=admin \
    -d password=dontchangeme \
    -d client_id=account \
    -d client_secret=7bsrMrRuNKpqsxcOOJavWjEqek12ZCkj
```

The secret and id there are just an example (`account` is a client configurd by default by keycloak).

This is the simplest way to check credentials but also has the consequence of leaking unhandled oauth2/OIDC user tokens. I'm unsure if this could have further consequences but it's a risk worth considering.

# Development

The nix test configuration relies on bridging the VM IP, for this it relies on the default `libvirt`'s interface and needs the `qemu-bridge-helper`. This is found in a nix shell hook.

To have the necessary environment you should nix-develop in the shell, which will also provide the proper rust version and components.

You should also have `libvirt` configured on your system, other virtualization methods are not supported, if you have interface issues try to `virsh net-start default/virbr0`.

The test configuration treats itself as `keycloak-pam.test`, you might be interested in adding this to your `/etc/hosts` if you are going to use its web interface much.

# Rust Version

The project is meant to work under rust stable.

No specific MSRV is given, but if it compiles it should work.

# License

This code is meant to be used for [tuxcord.nix](https://git.javalsai.tuxcord.net/tuxcord/tuxcord.nix/issues), it copies some of such configuration and follows its same license.

This is **exclusively** licensed under the GNU Lesser General Public License (`LGPL-3.0-only`).

You are allowed to modify and redistribte derivatives of this work provided you comply with the license.