javalsai
0f736b1fc4
will only check users of such group also cleaned some code: - Input doesn't need to be UTF-8 valid. - Main fuction is dead-simple, very readable. - Added some modularity. - Add some docs on behavior details.
69 lines
3.4 KiB
Markdown
69 lines
3.4 KiB
Markdown
# 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.
|