Common Authentication Service Adapter (CASA)

September 28, 2007

* Section1, Overview
* Section2, Documentation"
* Section3, Documentation Conventions"
* Section4, Known Issues"
* Section5, Open Source Code"
* Section6, Legal Notices"

1 Overview

Common Authentication Service Adapter (CASA) provides a common infrastructure for client authentication across the Linux* and Microsoft* Windows* desktops. Novell products (such as GroupWise, GroupWise Messenger, iPrint, Novell iFolder, and the Novell clients for Windows and Linux) are integrated with the miCASA interface and can take advantage of the credential store that provides the cornerstone for CASA.

CASA provides the following main components:

     * CASA Identity Development Kit (IDK): The developer kit provides a set of APIs that application and service developers can use to write user/application credentials to the credential store. The APIs internally store the credentials passed onto them by the applications in miCASAd. There are C, C++, C# and Java bindings available for the CASA Identity Development Kit (IDK).

     *  Login Credential Capture Module: On Linux, the login credential capture module is implemented as a PAM module. This PAM module captures the users desktop login credentials and stores them in miCASAd using the IDK APIs. This PAM module is placed as the last module in the auth and session stacks of xdm, gdm, kdm, login and sshd PAM configuration files. In the auth stack, the functionality of this module is to store the credentials in miCASAd and in the session stack, then closes the users session with miCASAd.

     * miCASAd: An active component that starts during boot time. 

Linux:

miCASAd stores and provides credentials or secrets based on the user identifier (uid) of the process that makes the IDK API calls. It is available in the run-levels 1, 2, 3 and 5. It runs with root privileges and is active as long as the system is up.

Windows:

CASA consists of a single CASA.msi, which is the installation module that contains the following components that match their Linux counterparts:

     * CASA-gui.msm

     * CASA.msm

A separate Windows package called CASA-devel.msi installs the CASA development kit.

Credentials saved by user applications are encrypted and saved to the file system. When the user logs into the desktop, the credentials are read back into computer memory and made available to user applications.

NOTE: Any pluggable authentication module (PAM) that uses the IDK APIs must set its effective user ID temporarily to that of the user logging in (the user returned by calling pam_get_user()), if the credentials need to be stored against that user. There might be cases where the user obtained through pam_get_user() might not be the one against whom the PAM module actually intends to store credentials.

2 Documentation

The following sources provide information about CASA:

     * Product documentation included with the software: The download includes a single file: CASA Administration Guide(casa_enu.pdf) in the [install directory]\doc directory. 

     * Novell CASA online product documentation: Common Authentication Service Adapter (http://developer.novell.com/wiki/index.php/Casa)

     *  Bandit Open Source Common Authentication Services Adapter (CASA) Documentation (http://www.bandit-project.org/index.php/Common_Authentication_Services_Adapter_%28CASA%29_Documentation)

To read or print the documentation, you need Adobe Acrobat Reader 4.0 (http://www.adobe.com/prodindex/acrobat/readstep.html).
 
The document in this download was created as a standalone file; therefore, links to files in other downloads will not resolve.

3 Documentation Conventions

In this documentation, a greater-than symbol (>) is used to separate actions within a step and items in a cross-reference path.

A trademark symbol ( , TM, etc.) denotes a Novell trademark; an asterisk (*) denotes a third-party trademark.

4   Known Issues

Here are some known issues when deploying CASA 1.7:
     * Section4.1, Secret ID Failure"
     * Section4.2, Upgrading the CASA Authentication Service"
     * Section4.3, Runtime Architecture Compatibility"
     * Section4.4, Unstable Login Conditions"
     * Section4.5, Manually Starting the Gnome Keyring"
     * Section4.6, Installing CASA Developer Packages"

4.1 Secret ID Failure

Secrets with IDs using  \ as a reserved character might fail. This will be fixed in a future release.

4.2 Upgrading the CASA Authentication Service

There is a know problem with upgrading the CASA authentication service (ATS) to a later release. 
If you upgrade manually, you must first stop the CASA ATS before applying the upgrade. You do this by issuing the following command: /etc/init.d/casa_atsd stop

You may then proceed with the upgrade.

If the upgrade occurs as part of an automated update, then the CASA ATS must be restarted using the following procedure:

     1 Find the CASA ATS process that needs to be killed by entering the following comand: ps -ef | grep casaats

     2 Kill the listed ATS process.

     3 Restart the CASA ATS by entering the following command: /etc/init.d/casa_atsd start

4.3 Runtime Architecture Compatibility

To avoid runtime problems, do not install CASA 32 bit architecture RPMs intended for 64 bit architecture machines.

4.4  Unstable Login Conditions

Because CASA is tied to the Linux login process via a PAM, events that cause the system to become inconsistent or unstable might prevent users from logging in to workstations. Some possible causes of inconsistency or instability are:

     * Installing 32 bit CASA RPMs on a 64 bit OS

     * Performing a hard reset on the machine

       Use the following steps to restore the ability to login:

          1 Reboot the machine.

          2 When boot loader menu appears, execute init=/bin/bash on the command option line. This causes the machine to boot into a command shell with root privileges.

          3 To prevent the CASA daemon from loading during bootup, enter the following at the command prompt: 
chkconfig micasad off 

          4 With a console-based text editor (e.g., Vi, Emacs), remove all lines referencing the pam_micasa module in the following PAM configuration files (some files may not exist, depending on which desktop managers are installed):
               * /etc/pam.d/gdm
               * /etc/pam.d/xdm
               * /etc/pam.d/kdm
               * /etc/pam.d/sshd
               * /etc/pam.d/login

          5 At the command prompt execute init 5 to boot into runlevel 5 to obtain a graphical login prompt. You should be able to login at this point.

          6 To enable CASA to run at boot time, open a shell and at the prompt type
chkconfig micasad 1235. This causes micasad to run at runlevels 1, 2, 3, and 5.

          7 After you have restored login capabilities, resolve the inconsistency that prevented the initial login. If you had installed a 32 bit CASA package on a 64 bit OS, uninstall the 32 bit package and install a CASA package built for 64 bit architectures. If you are recovering from a hard reset, no further action should be needed.

4.5 Manually Starting the Gnome Keyring

When logged in to a KDE session, the gnome-keyring-daemon does not run by default. Therefore, all applications that access the daemon, including the CASAManager, will not be able to access or manage the gnome-keyring.

You can manually start the daemon by running the following command from a shell prompt: gnome-keyring-daemon
 
After the gnome-keyring-daemon starts, it prints the GNOME_KEYRING_SOCKET environment variable and its value to the terminal. In Gnome, the daemon starts and the environment variable loads into your X session environment by default. However, in KDE, you must manually load this environment variable: 

     1 Run a command similar to the following command from a shell prompt (replacing the value of the environment variable with what the daemon output to the screen when you started it): export GNOME_KEYRING_SOCKET=/tmp/keyring-oaTsPs/socket

     2 Run the CASAManager GUI (from the same terminal you exported the variable from).
You can now manage and use the gnome-keyring in KDE just like you could if you were logged into Gnome.

4.6 Installing CASA Developer Packages

CASA-devel packages are available only for software development and are not automatically included when installing a production Novell Open Enterprise Server. Developers should install CASA-devel at the same time Auth-token-server-devel and Auth-token-client-devel are installed. CASA is an Open Source project found at http://forge.novell.com/modules/xfmod/project/?casa. Download CASA-devel from there.
 
4.7 Using CASA in chroot Environment

For an application to access CASA in a change root (chroot) environment, the root user must do the following:

     1 Copy the micasa libraries to the chroot directory, as shown in the following example: cp /usr/lib/libmicasa* <chrootdir>/usr/lib/

     2 Create the CASA socket file in the chroot directory by linking the current CASA socket. An example of how to do this is explained below:

          2a From the <chrootdir>/var/run directory, execute the following command: ln /var/run/.novellCASA

NOTE: The chrootdir must be on the same disk partition as /var/run.

5 Open Source Code

Novell, hereby, offers to give any third party a complete machine-readable copy of the source code of Common Authentication Service Adapter (CASA) under the terms of Sections 1 and 2 of version 2 of the GNU General Public License as published by the Free Software Foundation, on a medium customarily used for software interchange. Please contact Novell Developer Services if you require a copy of the same.

6 Legal Notices

Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.

Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes.

Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export, or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. Please refer to the Novell International Trade Services Web page (http://www.novell.com/info/exports/) for more information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export approvals.

Copyright   2007 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Novell, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed on the Novell Legal Patents Web page (http://www.novell.com/company/legal/patents/) and one or more additional patents or pending patent applications in the U.S. and in other countries.

For Novell trademarks, see the Novell Trademark and Service Mark list (http://www.novell.com/company/legal/trademarks/tmlist.html).

All third-party trademarks are the property of their respective owners.
