{"id":15645951,"url":"https://github.com/kha7iq/kc-ssh-pam","last_synced_at":"2025-04-06T11:07:33.752Z","repository":{"id":153256454,"uuid":"628388096","full_name":"kha7iq/kc-ssh-pam","owner":"kha7iq","description":"KC SSH PAM is built to streamline the process of user authentication to access Linux systems through SSH with keycloak oidc","archived":false,"fork":false,"pushed_at":"2024-12-13T06:54:23.000Z","size":86,"stargazers_count":90,"open_issues_count":5,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T10:06:38.044Z","etag":null,"topics":["golang","keycloak","linux","oidc","ssh","sso"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kha7iq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-15T19:42:24.000Z","updated_at":"2025-03-28T08:06:00.000Z","dependencies_parsed_at":"2023-11-23T05:46:20.150Z","dependency_job_id":"bde4f124-17ad-4708-93ce-4d32b30dc396","html_url":"https://github.com/kha7iq/kc-ssh-pam","commit_stats":{"total_commits":53,"total_committers":4,"mean_commits":13.25,"dds":0.05660377358490565,"last_synced_commit":"8b2feaf07e351da92fdb7faa6ebbd38cc32ff5a8"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kha7iq%2Fkc-ssh-pam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kha7iq%2Fkc-ssh-pam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kha7iq%2Fkc-ssh-pam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kha7iq%2Fkc-ssh-pam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kha7iq","download_url":"https://codeload.github.com/kha7iq/kc-ssh-pam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247471517,"owners_count":20944158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","keycloak","linux","oidc","ssh","sso"],"created_at":"2024-10-03T12:10:42.347Z","updated_at":"2025-04-06T11:07:33.731Z","avatar_url":"https://github.com/kha7iq.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch2 align=\"center\"\u003e\n  \u003cp align=\"center\"\u003e\u003cimg width=30% src=\"https://raw.githubusercontent.com/kha7iq/kc-ssh-pam/master/.github/img/logo.png\"\u003e\u003c/p\u003e\n\u003c/h2\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub Build Status\" src=\"https://img.shields.io/github/actions/workflow/status/kha7iq/kc-ssh-pam/build.yml?label=Build\"\u003e\n   \u003ca href=\"https://github.com/kha7iq/kc-ssh-pam/releases\"\u003e\n   \u003cimg alt=\"Release\" src=\"https://img.shields.io/github/v/release/kha7iq/kc-ssh-pam?label=Release\"\u003e\n   \u003ca href=\"https://goreportcard.com/report/github.com/kha7iq/kc-ssh-pam\"\u003e\n   \u003cimg alt=\"Go Report Card\" src=\"https://goreportcard.com/badge/github.com/kha7iq/kc-ssh-pam\"\u003e\n   \u003ca href=\"#\"\u003e\n   \u003cimg alt=\"GitHub go.mod Go version\" src=\"https://img.shields.io/github/go-mod/go-version/kha7iq/kc-ssh-pam\"\u003e\n   \u003ca href=\"https://github.com/kha7iq/kc-ssh-pam/issues\"\u003e\n   \u003cimg alt=\"GitHub issues\" src=\"https://img.shields.io/github/issues/kha7iq/kc-ssh-pam?style=flat-square\u0026logo=github\u0026logoColor=white\"\u003e\n   \u003ca href=\"https://github.com/kha7iq/kc-ssh-pam/blob/master/LICENSE.md\"\u003e\n   \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/kha7iq/kc-ssh-pam\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e •\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e •\n  \u003ca href=\"#contributers \"\u003eContributers \u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e •\n\u003c/p\u003e\n\n# Keycloak SSH PAM\n\n**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.\n\nOnce 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.\n\n## Install\n\n\u003cdetails\u003e\n    \u003csummary\u003eDEB \u0026 RPM\u003c/summary\u003e\n\n```bash\n# DEB\nsudo dpkg -i kc-ssh-pam_amd64.deb\n\n# RPM\nsudo rpm -i kc-ssh-pam_amd64.rpm\n\n```\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n    \u003csummary\u003eManual\u003c/summary\u003e\n\n```bash\n# Chose desired version\nexport KC_SSH_PAM_VERSION=\"0.1.2\"\nwget -q https://github.com/kha7iq/kc-ssh-pam/releases/download/v${KC_SSH_PAM_VERSION}/kc-ssh-pam_linux_amd64.tar.gz \u0026\u0026 \\\ntar -xf kc-ssh-pam_linux_amd64.tar.gz \u0026\u0026 \\\nchmod +x kc-ssh-pam \u0026\u0026 \\\nsudo mkdir -p /opt/kc-ssh-pam \u0026\u0026 \\\nsudo mv kc-ssh-pam config.toml /opt/kc-ssh-pam\n```\n\u003c/details\u003e\n\n\n## Usage\n```bash\n❯ kc-ssh-pam --help\nUsage: kc-ssh-pam USERNAME PASSWORD/[OTP]\n\nGenerates a password grant token from Keycloak for the given user.\n\nOptions:\n  -h, --help              Show this help message and exit\n  -v, --version           Show version information\n  -c                      Set configuration file path\n\nNotes:\n  For the program to function properly, it needs to locate a configuration file called 'config.toml'.\n  The program will search for this file in the current directory, '/opt/kc-ssh-pam' and '$HOME/.config/config.toml',\n  in that specific order. You can also set a custom path by specifying KC_SSH_CONFIG variable or -c flag which takes prefrence.\n\n  In addition to defaults, all configuration parameters can also be provided through environment variables.\n\n  KC_SSH_CONFIG KC_SSH_REALM KC_SSH_ENDPOINT KC_SSH_CLIENTID KC_SSH_CLIENTSECRET KC_SSH_CLIENTSCOPE\n  \n  To use the program, you must create a client in Keycloak and provide the following \n  information in the configuration file: realm, endpoint, client ID, client secret, and \n  client scope is optional.\n\nArguments:\n  USERNAME                The username of the user is taken from $PAM_USER environment variable\n  PASSWORD                The password of the user is taken from stdIn\n  OTP                     (Optional) The OTP code if two-factor authentication is enabled i.e (password/otp)\n\n  EXAMPLE                 (With otp): echo testpass/717912 | kc-ssh-pam (Only Password): echo testpass | kc-ssh-pam\n\n```\n\n## Configuration\n  For the program to function properly, it needs to locate a configuration file called `config.toml`.\n  \n  The program will search for this file in the follwoing order..\n  1. If a config path is specified using the `-c` flag, it will override any other defined options.\n  2. Verify the existence of the KC_SSH_CONFIG variable; if it's defined, use the location specified within it.\n  3. The working directory where the program is being executed from.\n  4. Default install location `/opt/kc-ssh-pam/`\n  5. `$HOME/.config/`\n  \n  \n\u003e [!IMPORTANT]  \n\u003e For proper operation, ensure that SeLinux is configured in Permissive mode.\n  \n`config.toml`\n  ```\nrealm = \"ssh-demo\"\nendpoint = \"https://keycloak.example.com\"\nclientid = \"keycloak-client-id\"\nclientsecret = \"MIKEcHObWmI3V3pF1hcSqC9KEILfLN\"\nclientscop = \"openid\"\n\n  ```\n* Edit `/etc/pam.d/sshd` and add the following at the top of file\n```bash\nauth sufficient pam_exec.so expose_authtok      log=/var/log/kc-ssh-pam.log     /opt/kc-ssh-pam/kc-ssh-pam\n```\n- User is not automatically created during login, so a local user must be present on the system before hand.\n\nTo automatically create a user install \n```bash\n apt-get install libpam-script\n```\nAdd the follwoing in `/etc/pam.d/sshd` underneath previous argument\n```bash\nauth optional pam_script.so\n```\n\nThen, the script itself. In the file `/usr/share/libpam-script/pam_script_auth`\n```bash\n#!/bin/bash\nadduser $PAM_USER --disabled-password --quiet --gecos \"\"\n```\nIn PAM modules, username is given in \"$PAM_USER\" variable.\n\nMake this script executable\n```bash\nchmod +x /usr/share/libpam-script/pam_script_auth \n```\nRestart sshd service\n```bash\nsudo systemctl restart sshd\n```\n\n### Keycloak Cleint Creation\n```bash\nStep 1: Log in to the Keycloak Administration Console.\n\nStep 2: Select the realm for which you want to create the client.\n\nStep 3: Click on \"Clients\" from the left-hand menu, and then click on the \"Create\" button.\n\nStep 4: In the \"Client ID\" field, enter \"ssh-login\".\n\nStep 5: Set the \"Client Protocol\" to \"openid-connect\".\n\nStep 6: In the \"Redirect URIs\" field, enter \"urn:ietf:wg:oauth:2.0:oob\".\n\nStep 7: In the \"Access Type\" field, select \"confidential\".\n\nStep 8: In the \"Standard Flow Enabled\" field, select \"ON\".\n\nStep 9: In the \"Direct Access Grants Enabled\" field, select \"ON\".\n\nStep 10: Click on the \"Save\" button to create the client.\n\nTo get the credentials of the client, follow these steps:\n\nStep 1: Go to the \"Clients\" page in the Keycloak Administration Console.\n\nStep 2: Select the \"ssh-login\" client from the list.\n\nStep 3: Click on the \"Credentials\" tab.\n\nStep 4: The client secret will be displayed under the \"Client Secret\" section.\n```\n\n:diamond_shape_with_a_dot_inside: Detailed article with screenshots is also [available here](https://lmno.pk/post/kc-sso-pam/)\n\n## Contributers\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"left\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/sradigan\"\u003e\u003cimg src=\"https://gitlab.com/uploads/-/system/user/avatar/2473327/avatar.png\" width=\"100px;\" alt=\"Sean Radigan \"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSean Radigan \u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/kha7iq/kc-ssh-pam/pull/6\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/kha7iq/kc-ssh-pam/pull/6\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\n## Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr/\u003eFeel free to check\n[issues page](https://github.com/kha7iq/kc-ssh-pam/issues). You can also take a look\nat the [contributing guide](https://github.com/kha7iq/kc-ssh-pam/blob/master/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkha7iq%2Fkc-ssh-pam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkha7iq%2Fkc-ssh-pam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkha7iq%2Fkc-ssh-pam/lists"}