Pluggable Authentication Modules - XSSO Sign-on Services

X/Open Single Sign-on Service (XSSO) -<br> Pluggable Authentication Modules

X/Open Single Sign-on Service (XSSO) -
Pluggable Authentication Modules
Copyright © 1997 The Open Group

XSSO Sign-on Services

XSSO Sign-on Service Structure

This specification defines an API to an XSSO Sign-on Service for use by sign-on applications. The XSSO Service API is independent of the specific authentication mechanisms used. There are two distinct aspects to a Single Sign-on service; the Primary Sign-on operation in which a user signs onto the policy domain as a whole, and Secondary Sign-on operations in which a user signs onto a service within the domain. The principal objective of a Single Sign-on service is that Secondary Sign-on operations may be transparent to the user.

The XSSO Service API comprises the PAM (Pluggable Authentication Modules) Service. The next subsection describes the PAM service.

The chapter concludes by providing illustrations of how the PAM service is used to support both Primary and Secondary Sign-on operations in upport of the concept of Single Sign-on. There are four models of secondary sign-on considered:

Single Sign-on to a secondary domain colocated with primary sign-on session, that is on the same host platform.
Single Sign-on to a distributed authentication service to access a target application on a remote platform. This model uses the GSS-API or any such appropriate mechanism for authentication between the client and target applications. The secondary authentication uses a secure authentication protocol, for example the DCE security service or a GSS-API implementation over Kerberos.
Single Sign-on to a local service on a remote platform. This involves a distributed application on the remote system acting as a proxy for the user principal and conducting the sign-on to the secondary local service.
Single Sign-on to a secondary distributed authentication service. This involves a distributed application acting as proxy for the user principal and conducting the sign-on to the secondary distributed authentication service.

PAM Service Overview

This section provides an overview of the PAM service.

PAM (Pluggable Authentication Modules) provides system administrators with the flexibility to:

choose any authentication service available on a system to perform end-user authentication for an application
use multiple authentication services thus providing a means of integrating authentication technologies with system-entry services
add new authentication service modules to a system and make them available without having to modify any applications
incorporate mapping services to map user names and authentication tokens between different authentication domains.

The PAM framework comprises an interface library and multiple PAM service modules. The PAM interface library is the layer implementing the Application Programming Interface (PAM-API). The PAM service modules are a set of dynamically loadable objects invoked by the PAM-SPI to provide a particular type of user authentication.

Figure: PAM Framework

PAM Framework illustrates the PAM framework. PAM supports five different types of service modules:

Authentication
Account Management
Session Management
Password Management
Mapping.

PAM may be configured with multiple instances of each module type to support sign-on operations to different authentication domains and the use of multiple mechanisms.

A system manager configures the PAM service via the PAM Configuration Data. This specifies which PAM service modules are to be called for a particular application. It also specifies the sequence, if more than one module is to be called, and the interdependencies of the results of each of the authentication operations.

A calling application is responsible for implementing the routines for conducting a dialogue with an end-user. This makes PAM independent of the user interface. The address of these callback communication functions, together with the servicename and the username are passed to the first PAM call. This call returns a handle to an internal PAM structure which maintains information related to the caller and via which information is passed to and returned by each of the PAM service modules that is invoked.

The user prompts used for a dialogue with an end-user are provided by the backend module and can therefore easily prompt for service specific information such as a PIN.

PAM-API

The functions comprising the PAM-API may be grouped into six categories of functions:

PAM Framework Layer Functions

These functions enable an application to invoke PAM service modules and to communicate information to the PAM Service Modules.

 

pam_start()
pam_end()
pam_get_data()
pam_set_data()
pam_get_item()
pam_set_item()
pam_getenv()
pam_getenvlist()
pam_putenv()
pam_strerror()

pam_start() and pam_end() are PAM transaction routines for establishing and terminating a PAM session. pam_start() takes as arguments the name of the application calling PAM, the name of the user to be authenticated and the address of the callback conversation structure provided by the caller. It returns a handle for use with subsequent calls to the PAM library.

pam_get_data() and pam_set_data() are routines for accessing and updating module specific data from the PAM handle.

pam_get_item() and pam_set_item() are routines for PAM that allow both applications and PAM service modules to access and update common PAM information such as service name, user name, remote host name, remote user name, and so on, from the PAM handle. The values that may be manipulated by these functions are listed in PAM Item Names .

Item Name Description
PAM_SERVICE Service name
PAM_USER User name
PAM_RUSER Remote user name
PAM_TTY tty name
PAM_RHOST remote host name
PAM_CONV pam_conv structure
PAM_AUTHTOK Authentication token
PAM_OLDAUTHTOK Old authentication token

Item Name	Description
PAM_SERVICE	Service name
PAM_USER	User name
PAM_RUSER	Remote user name
PAM_TTY	tty name
PAM_RHOST	remote host name
PAM_CONV	pam_conv structure
PAM_AUTHTOK	Authentication token
PAM_OLDAUTHTOK	Old authentication token

Table: PAM Item Names

Note:: The values of PAM_AUTHTOK and PAM_OLDAUTHTOK are only available to PAM modules and not to applications.

pam_getenv(), pam_getenvlist() and pam_putenv() enable the calling application and PAM modules to set and retrieve environment variables for the user session which will be established with pam_open_session().

pam_strerror() returns error status information.

Authentication Functions

 

pam_authenticate()
pam_authenticate_secondary()
pam_setcred()

The pam_authenticate() function is called to verify the identity of the current user. The pam_authenticate_secondary() function is called to authenticate a username in a secondary domain independently of the primary user authentication and user session establishment. The caller will typically have previously retrieved the username and authentication token to be used with the secondary target domain by calls to the mapping module.

pam_setcred() function is called to set the credentials of the current process associated with the authentication handle supplied. Typically, this is done after the user has been authenticated.

Account Management Functions

 

pam_acct_mgmt()

This function is used to verify the authorization of the user to sign-on. It will typically include checking for password and account expiration, valid login times, and so on.

Session Management Functions

 

pam_open_session()
pam_close_session()

These functions are called on the initiation and termination of a PAM session. They may support session auditing.

Password Management Functions

 

pam_chauthtok()

This function is called to change the authentication token (password) associated with the user.

Mapping Functions

 

pam_get_mapped_username()
pam_get_mapped_authtok()
pam_set_mapped_username()
pam_set_mapped_authtok()

These functions are called to set and retrieve identities and authentication tokens (for example, passwords) that are associated with (mapped to) the specified identity.

PAM-SPI

The functions comprising the PAM-SPI are provided by the modules called by the PAM infrastructure and are grouped below on the basis of module type.

Authentication Module Functions

 

pam_sm_authenticate()
pam_sm_authenticate_secondary()
pam_sm_setcred()

The pam_sm_authenticate() function is called to verify the identity of the current user. The pam_sm_authenticate_secondary() function is called to authenticate a username in a secondary domain independently of the primary user authentication and user session establishment. The caller will typically have previously retrieved the username and authentication token to be used with the secondary target domain by calls to the mapping module.

pam_sm_setcred() function is called to set the credentials of the current process associated with the authentication handle supplied. Typically, this is done after the user has been authenticated.

Account Management Module Functions

 

pam_sm_acct_mgmt()

This function is used to verify the authorization of the user to sign-on. It will typically include checking for password and account expiration, valid login times, and so on.

Session Management Module Functions

 

pam_sm_open_session()
pam_sm_close_session()

These functions are called on the initiation and termination of a PAM session. They may support session auditing.

Password Management Module Functions

 

pam_sm_chauthtok()

This function is called to change the authentication token (password) associated with the user.

Mapping Module Functions

 

pam_sm_get_mapped_username()
pam_sm_get_mapped_authtok()
pam_sm_set_mapped_username()
pam_sm_set_mapped_authtok()

These functions are called to set and retrieve identities and authentication tokens (for example, passwords) that are associated with (mapped to) the specified identity.

PAM Configuration

PAM is controlled by a set of configuration information. An example set of configuration information is given in PAM Configuration with Different Modules .

Service Module_type Control_flag Module_path Options
login mapping sufficient libmap.so
login mapping sufficient libmapfoo.so
login auth required pam_unix_auth.so nowarn
login session required pam_unix_session.so
login account required pam_unix_account.so
login password required pam_unix_passwd.so
ftp auth required pam_skey_auth.so debug
ftp session required pam_unix_session.so
telnet session required pam_unix_session.so
passwd mapping required libmap.so
passwd mapping required libmapfoo.so
passwd password required pam_unix_passwd.so
OTHER auth required pam_unix_auth.so
OTHER session required pam_unix_session.so
OTHER account required pam_unix_account.so
OTHER password required pam_unix_passwd.so

Service	Module_type	Control_flag	Module_path	Options
login	mapping	sufficient	libmap.so
login	mapping	sufficient	libmapfoo.so
login	auth	required	pam_unix_auth.so	nowarn
login	session	required	pam_unix_session.so
login	account	required	pam_unix_account.so
login	password	required	pam_unix_passwd.so
ftp	auth	required	pam_skey_auth.so	debug
ftp	session	required	pam_unix_session.so
telnet	session	required	pam_unix_session.so
passwd	mapping	required	libmap.so
passwd	mapping	required	libmapfoo.so
passwd	password	required	pam_unix_passwd.so
OTHER	auth	required	pam_unix_auth.so
OTHER	session	required	pam_unix_session.so
OTHER	account	required	pam_unix_account.so
OTHER	password	required	pam_unix_passwd.so

Table: PAM Configuration with Different Modules

The PAM configuration data is logically grouped into records comprising the following five fields:

Service

Service denotes the systems-entry application, for example login, passwd, rlogin. The name OTHER denotes the module used by default if a specific entry for a service is not specified.

Module_type

Module_type denotes the type of PAM module. Valid module types are mapping, auth, account, session and password.

Control_flag

The control_flag determines the behavior of stacking multiple modules by specifying whether any particular module is required, sufficient, requisite or optional.

Module_path

The Module_path specifies the location of the module to be loaded.

Options

Options is used to define module-specific options that are passed to PAM modules.

Note:: A general option to instruct a module to use a Personal Security Device (for example, a smartcard) is not included in this specification. Such an option is considered to be unnecessary and an administrative complication. It is expected that specific PSD aware modules will be developed for any appropriate service and will be specified within the PAM configuration.

Service Module_type Control_flag Module_path Options
login auth required pam_unix_auth.so nowarn
login auth optional pam_kerberos.so
rlogin auth sufficient pam_rhosts_auth.so
rlogin auth required pam_unix_passwd.so

Service	Module_type	Control_flag	Module_path	Options
login	auth	required	pam_unix_auth.so	nowarn
login	auth	optional	pam_kerberos.so
rlogin	auth	sufficient	pam_rhosts_auth.so
rlogin	auth	required	pam_unix_passwd.so

Table: PAM Configuration File with Stacked Modules

PAM Configuration File with Stacked Modules illustrates the stacking of authentication modules within a PAM configuration file. The entries for login illustrate support for integrated authentication to both UNIX and Kerberos domains. The entries for rlogin illustrate support for alternative methods of authentication; rhosts based authentication is sufficient for rlogin but if that is not successful then normal UNIX authentication is required.