Install • Usage • Configuration • Contributers • Contributing •
kc-ssh-pam designed to streamline the process of user authentication and enable users to access Linux systems through SSH. The program integrates with Keycloak to obtain a password grant token based on the user's login credentials, including their username and password. If two-factor authentication is enabled for the user, the program supports OTP code as well.
Once the password grant token is obtained, the program verifies it and passes the necessary parameters so that the user can be authenticated via SSH and access the Linux systems.
DEB & RPM
# DEB
sudo dpkg -i kc-ssh-pam_amd64.deb
# RPM
sudo rpm -i kc-ssh-pam_amd64.rpm
Manual
# Chose desired version
export KC_SSH_PAM_VERSION="0.1.2"
wget -q https://github.com/kha7iq/kc-ssh-pam/releases/download/v${KC_SSH_PAM_VERSION}/kc-ssh-pam_linux_amd64.tar.gz && \
tar -xf kc-ssh-pam_linux_amd64.tar.gz && \
chmod +x kc-ssh-pam && \
sudo mkdir -p /opt/kc-ssh-pam && \
sudo mv kc-ssh-pam config.toml /opt/kc-ssh-pam❯ kc-ssh-pam --help
Usage: kc-ssh-pam USERNAME PASSWORD/[OTP]
Generates a password grant token from Keycloak for the given user.
Options:
-h, --help Show this help message and exit
-v, --version Show version information
-c Set configuration file path
Notes:
For the program to function properly, it needs to locate a configuration file called 'config.toml'.
The program will search for this file in the current directory, '/opt/kc-ssh-pam' and '$HOME/.config/config.toml',
in that specific order. You can also set a custom path by specifying KC_SSH_CONFIG variable or -c flag which takes prefrence.
In addition to defaults, all configuration parameters can also be provided through environment variables.
KC_SSH_CONFIG KC_SSH_REALM KC_SSH_ENDPOINT KC_SSH_CLIENTID KC_SSH_CLIENTSECRET KC_SSH_CLIENTSCOPE
To use the program, you must create a client in Keycloak and provide the following
information in the configuration file: realm, endpoint, client ID, client secret, and
client scope is optional.
Arguments:
USERNAME The username of the user is taken from $PAM_USER environment variable
PASSWORD The password of the user is taken from stdIn
OTP (Optional) The OTP code if two-factor authentication is enabled i.e (password/otp)
EXAMPLE (With otp): echo testpass/717912 | kc-ssh-pam (Only Password): echo testpass | kc-ssh-pam
For the program to function properly, it needs to locate a configuration file called config.toml.
The program will search for this file in the follwoing order..
- If a config path is specified using the
-cflag, it will override any other defined options. - Verify the existence of the KC_SSH_CONFIG variable; if it's defined, use the location specified within it.
- The working directory where the program is being executed from.
- proxyurl is optional. If defined, the program will route Keycloak requests through the specified proxy. If proxyurl is missing or empty, a direct connection is used.
- Default install location
/opt/kc-ssh-pam/ $HOME/.config/
Important
For proper operation, ensure that SeLinux is configured in Permissive mode.
config.toml
realm = "ssh-demo"
endpoint = "https://keycloak.example.com"
clientid = "keycloak-client-id"
clientsecret = "MIKEcHObWmI3V3pF1hcSqC9KEILfLN"
clientscope = "openid"
clientrole = "keycloak-client-role"
proxyurl = "https://192.168.0.1:8080" # Optional: HTTP/HTTPS proxy to use when accessing Keycloak
- Edit
/etc/pam.d/sshdand add the following at the top of file
auth [success=done default=die] pam_exec.so expose_authtok quiet log=/var/log/kc-ssh-pam.log /opt/kc-ssh-pam/kc-ssh-pam- User is not automatically created during login, so a local user must be present on the system before hand.
Restart sshd service
sudo systemctl restart sshdStep 1: Log in to the Keycloak Administration Console.
Step 2: Select the realm for which you want to create the client.
Step 3: Click on "Clients" from the left-hand menu, then click the "Create client" button.
Step 4: In the "Client type" field, select "openid-connect".
Step 5: In the "Client ID" field, enter "ssh-login".
Step 6: Set "Client authentication" to ON.
Step 7: Set "Standard Flow Enabled" to ON.
Step 8: Set "Direct Access Grants" to ON.
Step 9: In the "Redirect URIs" field, enter "urn:ietf:wg:oauth:2.0:oob".
Step 10: Click the "Save" button to create the client.Step 1: Go to the "Clients" page in the Keycloak Administration Console.
Step 2: Select the "ssh-login" client from the list.
Step 3: Go to the "Roles" tab.
Step 4: Click the "Create role" button.
Step 5: Set the Role name to "ssh-pc1".
Step 6: Click the "Save" button to create the client role.Step 1: Go to the "Groups" page in the Keycloak Administration Console.
Step 2: Select the group to assign the client role to.
Step 3: Go to the "Role mapping" tab.
Step 4: Click the "Assign role" button.
Step 5: Select the client role "ssh-pc1".
Step 6: Click the "Assign" button to assign the client role.Step 1: Go to the "Clients" page in the Keycloak Administration Console.
Step 2: Select the "ssh-login" client from the list.
Step 3: Click on the "Credentials" tab.
Step 4: The client secret is displayed under the "Client Secret" section.Sean Radigan 📖 💻 |
Contributions, issues and feature requests are welcome!
Feel free to check
issues page. You can also take a look
at the contributing guide.