====== PAM support in OpenSSH ======

===== PAM introduction =====

Pluggable authentication module (PAM) supports authentication mechanism. Applications can make use of this module for implementing authentication mechanism in AIX®. PAM provides different service modules, and each module supports different functionality. Make use of these PAM service modules to enable PAM with authentication, account, password, and session management mechanisms in AIX.

Advantages: PAM is "standard" on linux, more flexible to manage access to a server.

===== PAM configuration =====

==== Enable PAM authentication method ====

To enable PAM authentication in OpenSSH, run the following configuration commands (file /etc/security/login.cfg):
<cli prompt='#'>
# lssec -f /etc/security/login.cfg -s usw -a auth_type 
usw auth_type=STD_AUTH
</cli>		    

If the code looks like this: auth_type = STD_AUTH, then change it to PAM_AUTH using the following command:
<cli prompt='#'>
# chsec -f /etc/security/login.cfg -s usw -a auth_type=PAM_AUTH
</cli>	    

<cli prompt='#'>
# chsec -f /etc/security/login.cfg -s usw -a mkhomeatlogin=true 
</cli>
==== Modify pam.conf to add ssh ====

As openssh is not fully integrated into AIX, you have to add this ssh into /etc/pam.conf.\\
Add the following to the /etc/pam.conf file, in each section before the pam_prohibit line:

<cli prompt='#'>
# Authentication
  sshd    auth       required         pam_aix
  sudo    auth       required         pam_aix	    

# Account Management
  sshd    account    required         pam_aix
  sudo    account    required         pam_aix
  
# Password Management
  sshd    password   required         pam_aix
  sudo    password   required         pam_aix
  
# Session Management
  su      session    optional         pam_mkuserhome
  sudo    session    required         pam_mkuserhome
  ...
  sshd    session    required         pam_aix  
  sshd    session    optional         pam_mkuserhome
</cli>

==== Enable PAM as ssh authentication method ====

Edit /etc/ssh/sshd_config
<cli promt='#'>	
# vi /etc/ssh/sshd_config
</cli>	
  Uncomment the UsePAM line and change UsePAM no to **UsePAM yes**.
  
  For information is authentification in login.cfg is set to STD_AUTH, then the parameter UsePAM is not applicable

==== Restart ssh demon ====

Stop and restart sshd.
<cli prompt='#'>
# stopsrc -s sshd
# startsrc -s sshd
</cli>

===== PAM Debug =====

To enable PAM debug output, complete the following steps:

Create an empty file named pam_debug in the **/etc/pam_debug** directory by using the touch command, if the file does not exist. The PAM library checks for the /etc/pam_debug file and enables syslog output if it is found.

Edit the /etc/syslog.conf file to identify a file where it will log the auth syslog messages at the priority level you want. For example, to send PAM debug-level messages to the /var/log/auth.log file, add the following text as a new line in the syslog.conf file:
  *.debug /var/log/auth.log

Create the output file /var/log/auth.log, by using the touch command, if it does not exist.
    
To restart the syslogd daemon so that configuration changes are recognized, complete the following steps:
<cli prompt='#'>
# stopsrc -s syslogd
# startsrc -s syslogd
</cli>

===== PAM configuration file =====

=== Example of file for AIX (partial) ===
<code>
...
#
# Authentication
#
authexec auth   required        pam_aix
dtaction auth   required        pam_aix
dtsession auth  required        pam_aix
dtlogin auth    required        pam_aix
ftp     auth    required        pam_aix
imap    auth    required        pam_aix
login   auth    required        pam_aix
rexec   auth    required        pam_aix
rlogin  auth    sufficient      pam_rhosts_auth
rlogin  auth    required        pam_aix
rsh     auth    required        pam_rhosts_auth
snapp   auth    required        pam_aix
su      auth    sufficient      pam_allowroot
su      auth    required        pam_aix
swrole  auth    required        pam_aix
telnet  auth    required        pam_aix
xdm     auth    required        pam_aix
sshd    auth    requisite       pam_permission file=/etc/auth.allow found=allow
sshd    auth    required        pam_aix
sudo    auth    required        pam_aix
OTHER   auth    required        pam_prohibit
...
</code>

To allow a user to connect using ssh in the previous example, create the file containing users, and groups
[root@nim]/etc# cat /etc/auth.allow
root
@admin_access
</cli>

=== Session Management: ===

^Type^Description^
|auth|Authenticate users and set, refresh, or destroy credentials.|
|account|Determine validity of the user account and subsequent access after identification from authentication module.|
|password|Perform password modification and related attribute management.|
|session|Initiate and terminate user sessions.|

=== The Control_flag specifies the stacking behavior for module. ===
 Valid flags are required, requisite, sufficient, and optional.
^Flag^Description^
|required|All required modules in a stack must pass for a successful result. If one or more fail, all of the required modules are attempted, but the error from the first failed required module is returned.|
|requisite|Similar to required except that if a requisite module fails, it immediately returns the first failure code from a required or requisite module.|
|sufficient|If a module flagged as sufficient succeeds and no previous required or sufficient modules have failed, all remaining modules in the stack are ignored and success is returned.|
|optional|Result ignored unless there are no required modules and no sufficient modules have succeeded.|

=== PAM modules are located into /usr/lib/security: ===
^ Module name ^ Description ^
|pam_aix|AIX style authentication.|
|pam_allow|Returns PAM_SUCCESS for all invocations.|
|pam_allowroot|Returns PAM_SUCCESS if invoking user is root (uid = 0).|
|pam_ckfile|Provides checks similar to /etc/nologin.|
|pam_permission|Provides enhanced /etc/ftpusers type checking.|
|pam_prohibit|Returns a PAM failure code for all invocations.|
|pam_rhosts_auth|Performs rhosts authentication.|

The **pam_rhosts_auth** module provides rhosts type of authentication facility similar to r-cmds like rlogin, rsh, and rexec. This module checks for username and hostname in /etc/hosts.equiv and followed by $HOME/.rhosts file. If a match is not found in the files, it returns PAM_AUTH_ERR failure code. 

The **pam_ckfile** module allows or denies authentication based on existence of a file. This module provides functionality similar to the historic behavior of the /etc/nologin file. If the specified file exists, only the root user may authenticate. This module supports Authentication and Account Management module types. This module recognizes the file, debug, and nowarn options.

=== The Module_options specifies a list of options supported by PAM service module. ===
Some common options are:
^Option^Description^
|debug|Log debugging information to syslog.|
|nowarn|Do not display error messages.|
|try_first_pass|Try a previously entered password. If it fails, prompt for a new one.|
|use_first_pass|Use a previously entered password, do not prompt for a new one.|


Here is a sample of a full pam.conf file for AIX:
<code>
# IBM_PROLOG_BEGIN_TAG
# This is an automatically generated prolog.
#
# bos720 src/bos/etc/pam/pam.conf 1.8.1.1
#
# Licensed Materials - Property of IBM
#
# COPYRIGHT International Business Machines Corp. 2003,2012
# All Rights Reserved
#
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#
# IBM_PROLOG_END_TAG
#
# PAM Configuration File
#
# This file controls the PAM stacks for PAM enabled services.
# The format of each entry is as follows:
#
# <service_name> <module_type> <control_flag> <module_path> [module_options]
#
# Where:
#       <service_name> is:
#               The name of the PAM enabled service.
#
#       <module_type> is one of:
#               auth, account, password, session
#
#       <control_flag> is one of:
#               required, requisite, sufficient, optional
#
#       <module_path> is:
#               The path to the module. If the field does not begin with '/'
#               then /usr/lib/security is prefixed for 32-bit services,
#               /usr/lib/security/64/ is prefixed for 64-bit services.
#               If the module path is specified as full path,then it
#               directly uses for 32-bit services, for 64-bit services
#               module path derived as <module_path>/64/<module_name>.
#               /usr/lib/security/64/ is prefixed for 64-bit services.
#               If the module path is specified as full path,then it
#               directly uses for 32-bit services, for 64-bit services
#               module path derived as <module_path>/64/<module_name>.
#
#       [module_options] is:
#               An optional field. Consult the specified modules documentation
#               for valid options.
#
# The service name OTHER controls the behavior of services that are PAM
# enabled but do not have an explicit entry in this file.
#

#
# Authentication
#
authexec auth   required        pam_aix
dtaction auth   required        pam_aix
dtsession auth  required        pam_aix
dtlogin auth    required        pam_aix
ftp     auth    required        pam_aix
imap    auth    required        pam_aix
login   auth    required        pam_aix
rexec   auth    required        pam_aix
rlogin  auth    sufficient      pam_rhosts_auth
rlogin  auth    required        pam_aix
rsh     auth    required        pam_rhosts_auth
snapp   auth    required        pam_aix
sshd    auth    requisite       pam_permission file=/etc/auth.allow found=allow
sshd    auth    required        pam_aix
su      auth    sufficient      pam_allowroot
su      auth    required        pam_aix
sudo    auth    sufficient      pam_allowroot
sudo    auth    required        pam_aix
sudo-i  auth    required        pam_aix
swrole  auth    required        pam_aix
telnet  auth    required        pam_aix
xdm     auth    required        pam_aix
OTHER   auth    required        pam_prohibit

#
# Account Management
#
authexec account required       pam_aix
dtlogin account required        pam_aix
ftp     account required        pam_aix
login   account required        pam_aix
rexec   account required        pam_aix
rlogin  account required        pam_aix
rsh     account required        pam_aix
sshd    account required        pam_aix
su      account sufficient      pam_allowroot
su      account required        pam_aix
sudo    account sufficient      pam_allowroot
sudo    account required        pam_aix
sudo-i  account required        pam_aix
swrole  account required        pam_aix
telnet  account required        pam_aix
xdm     account required        pam_aix
OTHER   account required        pam_prohibit

#
# Password Management
#
authexec password  required     pam_aix
dtlogin password  required      pam_aix
login   password  required      pam_aix
passwd  password  required      pam_aix
rlogin  password  required      pam_aix
sshd    password  required      pam_aix
su      password  required      pam_aix
sudo    password  required      pam_aix
sudo-i  password  required       pam_aix
telnet  password  required      pam_aix
xdm     password  required      pam_aix
OTHER   password  required      pam_prohibit

#
# Session Management
#
dtlogin session required        pam_aix
ftp     session required        pam_aix
imap    session required        pam_aix
login   session required        pam_aix
rexec   session required        pam_aix
rlogin  session required        pam_aix
rsh     session required        pam_aix
snapp   session required        pam_aix
sshd    session required        pam_aix
sshd    session optional        pam_mkuserhome
su      session required        pam_aix
sudo    session required        pam_aix
sudo    session optional        pam_mkuserhome
sudo-i  session required        pam_aix
swrole  session required        pam_aix
telnet  session required        pam_aix
xdm     session required        pam_aix
OTHER   session required        pam_prohibit
</code>

Create also a file /etc/auth.allow, with users, groups...
<cli prompt='#'>
[root@aixsrv]/root# cat /etc/auth.allow
root
@usr
</cli>

common errors using **sudo**, this is related to missing entries for sudo in /etc/pam.conf !
<cli prompt='#'>
[toto@nim]/home/toto# sudo /usr/bin/su -

We trust you have received the usual lecture from the local System
Administrator. It usually boils down to these three things:

    #1) Respect the privacy of others.
    #2) Think before you type.
    #3) With great power comes great responsibility.

Sorry, try again.
Sorry, try again.
sudo: 3 incorrect password attempts
</cli>