Previous section.

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:

PAM Service Overview

This section provides an overview of the PAM service.

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

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:

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  


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    


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    


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.

Models of Primary and Secondary Sign-on