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.

Features

Supports authentication and setting/changing one's password.
Can be restrained to only a group of users, so it won't interfere with system users.
Debuggable, if the option is set, you will get useful logs when using the module.
Error ready, extensive logging and descriptive errors to discover what and where went wrong.
Minimal, made in rust with a tiny dependency tree, avoiding unnecessary dynamic memory use, all methods are straight-forward and lightweight.
Reliable, made in rust without the use of unwrap, expect, slice indexing, etc; and graceful error handling.

[!INFO] Debuggability can be turned off with a rust feature flag to slightly decrease library size.

System Configuration

For examples, refer to the test nix configuration at tests/nixos/configuration.nix.

To explain the basic PAM flow, I will assume some PAM knowledge, but still explain most details, refer to PAM documentation if you have doubts.

All parts of the module should have a PAM priority slightly prior to the pam_unix.so counterpart.

The PAM module can work as two rule types: auth and password; but both behave in a similar way. Both do different stuff, but I will call it their "action" as they match for most of the flow.

For correct behavior, the module has to be staged:

The first stage is sufficient, if the user is meant to be handled (refer to the configuration) the PAM module will perform its action or fail. One issue with sufficient is that failure will fall through the next module (pam_unix.so if configured as intended).
To fix this, the module has to be loaded again as requisite (so failures don't trigger the rest of the required chain) with an argument that will make it behave differently, this will behave analogous to pam_deny.so, but only for users meant to be handled. Essentially acts as a barrier preventing keycloak users from falling to additional authentication methods.

This means that normal users exempt from keycloak authentication will use PAM as if keycloak wasn't there. But users meant to be handled won't be able to pass onto other authentication methods.

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. For instance, currently, password change needs to convert to String at some point and UTF-8 input is required.

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 it and will fail gracefully.

Security

Important security concerns or questions might be:

faillock: Faillock is a required PAM module that runs well before unix and this module. This service does not implement rate-limiting or similar mechanisms, but faillock should be there to handle this for us.
Setting a password as another user. This module doesn't check the user calling it, and it can be used to set password of uninitialized users, so if things were passed stright to the module, passwd test as anotheruser would just ask for a new password for test. Tested with passwd and this is not the case, PAM or passwd check the user you are trying to change the password to and your current one to prevent things like this.
Falling back to pam_unix, as explained in configuration, the module can be set up as a barrier to itself so failures of it in sufficient mode won't fall back to unix. If this were the case, it could create inconsistencies with /etc/passwd and keycloak, allowing arbitrary login with either module.

As the project evolves, it's important to revisit these concerns as it's a bit harder to guarantee them and could be potential breach points.

Policy

Keycloak can be configured in a lot of ways, so it's important to understand how this module will interact with Keylcoak. Otherwise misconfiguration can allow anyone to login as another user.

Think of this as stages, where the first one for all actions is:

Must check the subject user against the configured group. If it's not a member, it will just fallback to the next PAM module.

Here things differ a bit from login to password change:

Authentication

This is simple, will only allow login if the password used to log in is not temporary, any error will fail with an error.

The client used for this is still not definitive, currently it uses a client ID and client secret for this, account by default, but this might change.

Password

Even then, a user might and should be able to login ito their unix account if their keycloak account is not set up (e.g. through ssh).

If they try to change their password without having one set up, it won't ask for their current one and will use the admin REST API to set the first one, this one won't be a temporary password and will fully set up their accounts.

Behavior

User Authentication

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.

Password Change

This is a bit more convoluted and frail.

First of all, when a user wants to change their password, this module fetches their current passwords to see if the user has any.

If it has some, it will authenticate the user in the same way that User Authentication does, and if it succeeds, change the password in the same way a user with none would.

If the user has no password it will ask for one and use the admin API to PUT a new one with the reset-password endpoint.

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, 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.