{"id":20358099,"url":"https://github.com/irods/irods_auth_plugin_pam_interactive","last_synced_at":"2025-07-12T13:07:06.617Z","repository":{"id":37447655,"uuid":"503687754","full_name":"irods/irods_auth_plugin_pam_interactive","owner":"irods","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-16T17:43:35.000Z","size":72,"stargazers_count":2,"open_issues_count":6,"forks_count":6,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-16T18:39:22.275Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/irods.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2022-06-15T08:53:28.000Z","updated_at":"2025-05-16T17:43:40.000Z","dependencies_parsed_at":"2023-01-21T07:16:19.313Z","dependency_job_id":"29987ce1-354c-4afe-bf29-17d3ab224fdc","html_url":"https://github.com/irods/irods_auth_plugin_pam_interactive","commit_stats":null,"previous_names":["irods/irods_auth_plugin_pam_interactive"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/irods/irods_auth_plugin_pam_interactive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_auth_plugin_pam_interactive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_auth_plugin_pam_interactive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_auth_plugin_pam_interactive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_auth_plugin_pam_interactive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/irods","download_url":"https://codeload.github.com/irods/irods_auth_plugin_pam_interactive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_auth_plugin_pam_interactive/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264995426,"owners_count":23694959,"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":[],"created_at":"2024-11-14T23:25:22.286Z","updated_at":"2025-07-12T13:07:06.597Z","avatar_url":"https://github.com/irods.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# irods_auth_plugin_pam_interactive\n\n## How to build\n\nThe following packages are required to build this project:\n - irods-dev\n - irods-runtime\n\nYou will also need CMake of minimum version 3.12.0 and Clang of minimum version 13.0.0. These can be acquired through the following iRODS externals packages:\n - irods-externals-cmake3.21.4-0\n - irods-externals-clang13.0.0-0\n\nTo build, run the following:\n```bash\nmkdir -p build \u0026\u0026 cd build\ncmake ..\nmake package\n```\n\n## How to build with Docker\n\nThis project uses a \"build hook\" which allows the [iRODS Development Environment](https://github.com/irods/irods_development_environment) to build packages in the usual manner. Please see the instructions for building plugins with the development environment: [https://github.com/irods/irods_development_environment?tab=readme-ov-file#how-to-build-an-irods-plugin](https://github.com/irods/irods_development_environment?tab=readme-ov-file#how-to-build-an-irods-plugin)\n\n## Configuration\n\n### Server-side configuration\n\n#### Require TLS/SSL\n\nIt is **highly recommended** that TLS/SSL be required in the server when using this plugin for authentication. More information about configuring iRODS to use TLS/SSL can be found here: [https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#server-ssl-setup](https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#server-ssl-setup)\n\n#### `R_GRID_CONFIGURATION` for TTL\n\nThis plugin uses the standard set of authentication configurations found in `R_GRID_CONFIGURATION` for configuring Time-To-Live (TTL) on authenticated \"sessions\". You can read about these configurations here: [https://docs.irods.org/4.3.2/system_overview/configuration/#authentication-configuration](https://docs.irods.org/4.3.2/system_overview/configuration/#authentication-configuration)\n\n#### `pam_stack_name`\n\n`pam_stack_name` gives the iRODS administrator the ability to specify a PAM stack to use for `pam_interactive` authentication. Historically, the plugin has required that `/etc/pam.d/irods` be the name of the PAM stack file to use. With this configuration option, the administrator can specify a different PAM stack name to use.\n\nThe value of `pam_stack_name` must be a string which refers to the name of a file in `/etc/pam.d` or a service in `/etc/pam.conf` on the catalog service provider. In the absence of this configuration, a default value of \"irods\" is used. For example, if an administrator wishes to use a PAM stack called `/etc/pam.d/super-secure-auth` with `pam_interactive` which is in use by other services within the system, rather than changing the name of the PAM stack to `irods`, the administrator can change the `pam_stack_name` value to `super-secure-auth` to leverage the same PAM stack as other services.\n\nNote: The value of this configuration is used as the value for the `service_name` argument for `pam_start`. If the configured `pam_stack_name` does not exist in `/etc/pam.d` or `/etc/pam.conf`, the PAM system will fall back to its default behavior. This default behavior varies from platform to platform, so the administrator should take care that the system is properly configured. For more information about configuring PAM services, see the documentation: [https://linux.die.net/man/5/pam.conf](https://linux.die.net/man/5/pam.conf). For more information about `pam_start`, see the documentation: [https://linux.die.net/man/3/pam_start](https://linux.die.net/man/3/pam_start)\n\nThe configuration option is set in the server's `server_config.json` file (for packaged installations, this is found in `/etc/irods`). Here is how to configure `pam_stack_name`:\n```javascript\n\"plugin_configuration\": {\n    \"authentication\": {\n        \"pam_interactive\": {\n            \"pam_stack_name\": \"irods\"\n        }\n    }\n}\n```\n\n#### `insecure_mode`\n\n`insecure_mode` gives the iRODS administrator the ability to allow for non-TLS/SSL-enabled communications between the client and the server for authentications using `pam_interactive`. TLS/SSL is required by default when using this plugin because sensitive user information is sent over the network to communicate with the PAM service via the catalog service provider. **It is highly recommended to leave this configuration option at its default value of `false`.** The configuration option has been introduced for demo and testing purposes.\n\nIf the value is set to `true` and the user attempting to authenticate using this plugin does not have TLS/SSL enabled in the client-server communications, it is allowed, and a warning message is written to the server log to remind the administrator that sensitive user information is being sent over the network without encryption. If the value is set to `false`, a `SYS_NOT_ALLOWED` error will be returned if the user attempting to authenticate using this plugin does not have TLS/SSL enabled in the client-server communications. In the absence of this configuration, a default value of `false` is used.\n\nThe configuration option is set in the server's `server_config.json` file (for packaged installations, this is found in `/etc/irods`). Here is how to configure `insecure_mode`:\n```javascript\n\"plugin_configuration\": {\n    \"authentication\": {\n        \"pam_interactive\": {\n            \"insecure_mode\": false\n        }\n    }\n}\n```\n\n#### Logging\n\nThe server-side plugin includes a logging category which can be configured in `server_config.json` under the `log_level` section like so:\n```javascript\n\"log_level\": {\n    // ... Other Log Categories ...\n\n    \"pam_interactive_auth_plugin\": \"info\",\n\n    // ... Other Log Categories ...\n},\n```\n\n### Client-side configuration\n\nSet the `irods_authentication_scheme` in the client environment to `pam_interactive`.\n\nThe client environment should be configured to use TLS/SSL if the server requires TLS/SSL. More information about configuring the iRODS client environment to use TLS/SSL can be found here: [https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#client-ssl-setup](https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#client-ssl-setup)\n\n## Example Implementations and Usage\n\n### Linux password authentication (i.e. `pam_password`)\n\nThis plugin can be used as a drop-in replacement for `pam_password` and the legacy PAM authentication plugin (with the exception of some differing prompts). Here's how to set it up.\n\n#### Setting up users\n\nIn order to use the plugin in this case, a PAM user with a password must exist and be permitted to authenticate in the Linux environment with a password. There must also exist an iRODS user in the local zone with the same name as the PAM user. For example, if there is a PAM user named `alice` to whom we want to give iRODS access, an iRODS user named `alice` must also exist in the zone with which the user will be authenticating.\n\nHere is a simple way to create a Linux user with a password (note: this requires root access):\n```bash\nsudo useradd -m alice # the -m means \"create a home directory\"\nsudo usermod -p password_for_alice alice\n```\n\nHere is a simple way to create an iRODS user (note: this requires `rodsadmin` permissions):\n```bash\niadmin mkuser alice rodsuser\n```\n\n#### Configure the PAM stack\n\nConfigure the `irods` PAM stack as described in the documentation for PAM authentication (see [https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#pam-pluggable-authentication-module](https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#pam-pluggable-authentication-module)):\n```\n$ cat /etc/pam.d/irods\nauth        required      pam_env.so\nauth        sufficient    pam_unix.so\nauth        requisite     pam_succeed_if.so uid \u003e= 500 quiet\nauth        required      pam_deny.so\n```\n\n#### Try it out\n\nSwitch to the Linux user that we wish to authenticate. The user should be able to run `iinit` and see the following:\n```bash\n$ iinit\nEnter your iRODS user name: alice\nPassword: \n```\n\nIf \"Password\" is entered correctly, the user will be authenticated with iRODS, just like `pam_password`. The \"Password\" prompt is coming from the `pam_unix` module. For more information about this module, see the documentation in **man pam_unix**, or [https://linux.die.net/man/8/pam_unix](https://linux.die.net/man/8/pam_unix).\n\n### Kerberos authentication\n\nThis plugin can be used as a replacement for the Kerberos authentication plugin ([https://github.com/irods/irods_auth_plugin_kerberos](https://github.com/irods/irods_auth_plugin_kerberos)). Here's how to set it up.\n\n#### Set up the Kerberos service\n\nMake sure that your organization has a Kerberos service. For information about how to do this, please see the official Kerberos documentation: [http://web.mit.edu/kerberos/krb5-current/doc/admin/install.html](http://web.mit.edu/kerberos/krb5-current/doc/admin/install.html) In the \"Additional References\", the Kerberos team has provided an externally written guide for installing and configuring Kerberos on Debian-based systems which may prove helpful: [http://techpubs.spinlocksolutions.com/dklar/kerberos.html#intro](http://techpubs.spinlocksolutions.com/dklar/kerberos.html#intro)\n\n#### Setting up users\n\nIn order to use the plugin in this case, a Kerberos user with a password must exist and be permitted to authenticate in the Kerberos environment with a password. There must also exist an iRODS user in the local zone with the same name as the Kerberos user. For example, if there is a Kerberos user named `alice` to whom we want to give iRODS access, an iRODS user named `alice` must also exist in the zone with which the user will be authenticating.\n\nHere is a simple way to create a user in Kerberos (note: requires admin privileges in Kerberos). First, run `kadmin` and authenticate as the Kerberos administrator (if you are connected directly to a Kerberos administration server, you can use `kadmin.local`). Then, you can run this to create an unprivileged user:\n```bash\naddprinc -policy user alice\n```\n\nHere is a simple way to create an iRODS user (note: this requires `rodsadmin` permissions):\n```bash\niadmin mkuser alice rodsuser\n```\n\n#### Configure the PAM stack\n\nIn order to use Kerberos via PAM, we need to install the Kerberos PAM module, `pam_krb5`. Locating this software package is an exercise left to the reader. If all else fails, the .tar.gz files and source code can be found here: [https://www.eyrie.org/~eagle/software/pam-krb5](https://www.eyrie.org/~eagle/software/pam-krb5)\n\nFor more information about this module, see the documentation in **man pam_krb5**, or [https://linux.die.net/man/8/pam_krb5](https://linux.die.net/man/8/pam_krb5).\n\nConfigure the `irods` PAM stack as described in the documentation for PAM authentication (see [https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#pam-pluggable-authentication-module](https://docs.irods.org/4.3.2/plugins/pluggable_authentication/#pam-pluggable-authentication-module)):\n```\n$ cat /etc/pam.d/irods\nauth    sufficient    pam_krb5.so minimum_uid=1000\nauth    requisite     pam_deny.so\nauth    required      pam_permit.so\n```\nNote: The PAM stack doesn't have to look exactly like this. For instance, Linux authentication via `pam_unix` can be used as a backup if Linux users exist and are allowed to authenticate with a password in your system. This example is just demonstrating Kerberos authentication for iRODS via PAM in a very simple manner.\n\n#### Try it out\n\nSwitch to the PAM user that we wish to authenticate. The user should be able to run `iinit` and see the following:\n```bash\n$ iinit\nEnter your iRODS user name: alice\nPassword: \n```\n\nIf \"Password\" is entered correctly, the user will be authenticated with iRODS. The \"Password\" prompt is coming from the `pam_krb5` module.\n\n## Testing\n\nRunning the tests for this plugin should be familiar to those who have run tests for other iRODS plugins. This repository provides a test hook which is used by the iRODS Testing Environment. You can read about how to run plugin tests in the testing environment here: [https://github.com/irods/irods_testing_environment/?tab=readme-ov-file#run-irods-plugin-tests](https://github.com/irods/irods_testing_environment/?tab=readme-ov-file#run-irods-plugin-tests) Please note that using the `--use-ssl` option with the testing environment could cause tests to be skipped, so, as usual, please be mindful of which options are being used when running tests.\n\nIn order to run tests aside from the tools provided by the testing environment, one can use the `run_tests.py` script provided by the iRODS server package:\n```bash\npython3 scripts/run_tests.py --run_specific_test test_irods_auth_plugin_pam_interactive\n```\n\nUse the `--help` option for `run_tests.py` to learn about other options. Please note that the test files are installed with the server package produced by this repository so it is assumed that a packaged installation is being used. If not, make sure that the test files in the `packaging` directory are placed alongside the other iRODS test files (for default packaged installations, this should be `/var/lib/irods/scripts/irods/test`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firods%2Firods_auth_plugin_pam_interactive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firods%2Firods_auth_plugin_pam_interactive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firods%2Firods_auth_plugin_pam_interactive/lists"}