Skip to content

Install PAM NSS

Jump to bottom
biancini edited this page Jul 13, 2012 · 2 revisions

Installation of the PAM and NSS modules into a linux machine

Goal of the configuration

Goal of this page is to describe the procedure to install the NSS and PAM module and configure them to work properly.

The PAM authentication module works contacting the Shibboleth HTTP Basic authentication mechanism. The configuration of this authentication mechanism can be found on this wiki at the following page:

[Configuration to authenticate via HTTP Basic Authentication]

Installation of a protected resource listing session attributes

The PAM module works trying to access a protected resource on Apache (protected in the sense that it is behind Shibboleth HTTP Basic authentication) listing all session attributes.

This resource is provided in the form of a very simple PHP page to be put on Apache behind Shibboleth authentication with, for example, the following configuration:

# Directory created as a test to show Shibboleth authentication parameters
Alias /secure "/var/www/html/secure"

<Directory "/var/www/html/secure">
   SSLRequireSSL
   ShibRequireSessionWith PAMLogin
   AuthType shibboleth
   ShibRequireSession On
   ShibUseHeaders On
   require valid-user
   require none
</Directory>

This PHP page can be modified specyfing:

  • in the $headers array all the fields that must be retrieved from SERVER PHP object and put in the user Shibboleth session
  • the function eval_authenticateduser() can be implemented to return a value different from true for users to which the login must be denied.

Installation and configuration of the PAM module

The PAM module, which an be compiled from the pam_nss_modules folder, creates a pam_http.so file. This file must be copied in the folder containing all the PAM modules available on the system.

With the install directive to the Makefile inside the pam_nss_modules folder, the module is copied in the directory where usual linux distributions keep the PAM modules. This folder is /lib(64)/security/.

After that the PAM module is ready to be used and configured in PAM authentication chains. These chains are defined in /etc/pam.d. As an example to this configuration, in the folder pam_nss_modules/etc a check_user file is present showing an example of configuration.

This file contains something similar to:

#
# /etc/pam.d/check_user
# This file contains a possible configuration for the pam_http.so module which authenticates
# users using the HTTP Basic Authentication mechanism.
# This file is required for the check_user program to work correctly and so it is strongly
# suggested that it is copied in the /etc/pam.d folder and not only used as a source for
# modifications to others PAM configuration files.
#

auth     required       pam_http.so url=https://servername.com/pam.php sess_username=username
account  required       pam_http.so
password required       pam_permit.so
session  required       pam_http.so

As from the man of pam, Linux-PAM separates the tasks of authentication into four independent management groups: account management; authentication management; password management; and session management.

Simply put, these groups take care of different aspects of a typical user´s request for a restricted service:

  • account - provide account verification types of service: has the user´s password expired?; is this user permitted access to the requested service?
  • authentication - authenticate a user and set up user credentials. Typically this is via some challenge-response request that the user must
  • satisfy: if you are who you claim to be please enter your password. Not all authentications are of this type, there exist hardware based
  • authentication schemes (such as the use of smart-cards and biometric devices), with suitable modules, these may be substituted seamlessly for more standard approaches to authentication - such is the flexibility of Linux-PAM.
  • password - this group´s responsibility is the task of updating authentication mechanisms. Typically, such services are strongly coupled to those of the auth group. Some authentication mechanisms lend themselves well to being updated with such a function. Standard UN*X password-based access is the obvious example: please enter a replacement password.
  • session - this group of tasks cover things that should be done prior to a service being given and after it is withdrawn. Such tasks include the maintenance of audit trails and the mounting of the user´s home directory. The session management group is important as it provides both an opening and closing hook for modules to affect the services available to a user.

The pam_http.so module accepts different parameters to its configuration:

  • url = specifies the URL of a protected resource showing a list of session values (described above)
  • sess_username = is the field in Shibboleth session that contains the value to be used as username (usually uid or mail field can be used)
  • sslcheck = specifies whether the SSL certificate for HTTPS must be checked against a real CA authority
  • cafile = specifies a files containing public keys of CAs considered trusted authorities, this list is used to check the SSL certificate for HTTPS
  • use_first_pass = standard PAM parameter, tells the PAM module to get the user's entered password as it was stored by a module listed earlier in the stack, usually pam_unix or pam_pwdb, instead of prompting the user for it
  • try_first_pass = standard PAM parameter, tells the PAM module to check the previously-entered password as with use_first_pass, but to prompt the user for another one if the previously-entered one fails.

Installation and configuration of the NSS module

The NSS module, which an be compiled from the pam_nss_modules folder, creates a libnss_shib.so.2 file. This file must be copied in the folder containing all the NSS modules available on the system.

With the install directive to the Makefile inside the pam_nss_modules folder, the module is copied in the directory where usual linux distributions keep the PAM modules. This folder is /lib(64)/.

The NSS module reads a configuration file to be placed under /etc/libnss.conf. An example of this configuration file can be found in the folder pam_nss_module/etc.

This file permits to specify different configuration options:

  • url = the URL to the user/group listing portlet on the IdP (created as described in the wiki page [Configuration to authenticate via HTTP Basic Authentication].
  • sslcheck = specifies whether the SSL certificate for HTTPS must be checked against a real CA authority
  • username = the username to be used to access to the URL on the IdP for the user/group listing portlet
  • password = the password to be used to access to the URL on the IdP for the user/group listing portlet
  • cookie_num = an integer number of cookies to be passed to the URL on the IdP for the user/group listing portlet
  • cookie_#_name = the name of the cookie number # to be passed to the URL on the IdP for the user/group listing portlet
  • cookie_#_value = the value of the cookie number # to be passed to the URL on the IdP for the user/group listing portlet

Clone this wiki locally