CASA/CASA-auth-token/client/README

/***********************************************************************
 * 
 *  Copyright (C) 2006 Novell, Inc. All Rights Reserved.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; version 2.1
 *  of the License.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, Novell, Inc.
 * 
 *  To contact Novell about this file by physical or electronic mail, 
 *  you may find current contact information at www.novell.com.
 * 
 *  Author: Juan Carlos Luciani <jluciani@novell.com>
 *
 ***********************************************************************/
/***********************************************************************
 *
 *  README for auth_token
 *
 ***********************************************************************/

INTRODUCTION

CASA-auth-token is an authentication token infrastructure with support for multiple
authentication mechanisms with an emphasis on providing a scalable single
sign-on solution.
 
A key feature of auth_token is that its authentication tokens contain identity
information about the entity being authenticated. This information is made available
to the consuming services. The amount of information contained in the tokens is
configured on a per-service basis. Because of this feature, we say that CASA-auth-token
projects an "Authenticated Identity".

ARCHITECTURE COMPONENTS

The infrastructure provided by auth_token consists of client and server components.

The client components of auth_token consists of a Client Engine, Get Authentication
Token API, Authentication Token Cache, and Authentication Mechanism plug-ins.

The server components of auth_token consists of an Authentication Token Service, a
Verify Authentication Token API, a JAAS module, a PAM module, and an Apache Authentication
Provider module. The Authentication Token Service makes use of Authentication Mechanism
plug-ins, an Identity Data Store Abstraction Layer, and of Identity Token Providers.

SECURITY FEATURES AND DATA FLOW

Communications between the Client Engine and the Authentication Token Service (ATS)
occur over HTTPS. When a client desires to obtain an Authentication Token to access
a particular service it contacts an ATS which then proceeds to inform the client about
the Authentication Policy configured for the service. The policy contains information
about authentication mechanisms supported as well as information about the types of
credentials that the client can utilize to authenticate to the ATS. Once the client
receives the Authentication Policy, it then decides what authentication mechanism to
utilize to authenticate to the ATS based on the available authentication mechanisms
plug-ins as well as the available credentials. During the authentication process, the
ATS associates an identity with the entity being authenticated. The result of this
resolution is saved in a Session Token which is then sent to the client where it is
cached. Once the client is authenticated to the ATS, it then requests Authentication
Tokens from it using the obtained Session Token. When an ATS receives a request for
an Authentication Token, it then verifies the validity of the received Session Token
and then it creates the appropriate Identity Token for the target service which it then
embeds within the Authentication Token. The identity information contained in the
Identity Token as well as the type of Identity Token utilized depends on what is
configured for the tatget service.

Session Tokens and Authentication Tokens are signed by the issuing ATS using Signing
Certificates. Session Tokens and Authentication Tokens have a Lifetime Value associated
with them. Token verification involves verifying the token signatures, verifying that
the tokens where signed by a trusted entity, and verifying that the token lifetime has
not been exceeeded.

The auth_token client/service protocol allows for the authentication of the client entity.
auth_token relies in the server authentication mechanisms of SSL to verify the identity
of the ATS.

IMPLEMENTATION STRATEGY AND CURRENT STATUS

auth_token is currently under development and is not ready to be used in production.
The implementation strategy has been to first complete the framework with all of its
modules, APIs, and packaging to allow application writters to start developing to it.
Once this is done, then the implementation focus will switch to completing the plumbing.

As of this time, a lot of the framework has been completed and there are sample
applications that can be utilized to exercise it. For a more complete picture of where
we are, look at the various TODO lists present in the child folders.

The schedule for completing auth_token is agressive.

REQUIREMENTS FOR BUILDING THE SOFTWARE PACKAGE ON WINDOWS

  - Install Visual Studio .NET 2003
  - Install Windows Platform SDK for Windows Server 2003 SP1
  - Register the platform sdk with VS - Start/All Programs/Windows Platform SDK for Windows Server 2003 SP1/Visual Studio Registration/Register PSDK Directories with Visual Studio
  - Install Cygwin - See instructions below.
  - Extract Expat-2.0.0.zip in casa source directory parent
  - Install Casa

Download and start cygwin install:
Browse to http://sources.redhat.com/cygwin/ 

Click on "Install or update now!" or "Install Cygwin now"

Cygwin Setup:
Next

Cygwin Setup - Choose Installation Type:
Install from Internet
Next

Cygwin Setup - Choose Installation Directory:
Root Directory: C:\cygwin
Install For:  "All Users"

Default Text File Type: DOS

Cygwin Setup - Select Local Package Directory:
  Local Package Directory: C:\cygwin-packages

Cygwin Setup - Select Connection Type:
  Direct Connection

Choose A Download Site:
  ftp://ftp.nas.nasa.gov 

Cywin Setup - Select Packages:
  Base:
    defaults

  Devel:
    autoconf
    automake
    libtool
    make
    pkgconfig
    cvs
    gcc
    gcc-g++

  Editors:
    vim (optional)

  Net:
    openssh
    openssl

  Text:
    more

  Utils:
    clear (optional)

Cygwin Setup - Create Icons:
Finish

Edit cygwin.bat (c:\cygwin\cygwin.bat) to add a call to
%VS71COMNTOOLS%\vsvars32.bat (see example below). This sets up the
Visual Studio tools in Cygwin.

Sample cygwin.bat:

@echo off

call "%VS71COMNTOOLS%\vsvars32.bat" > NUL

C:
chdir C:\cygwin\bin

bash --login -i


REQUIREMENTS FOR BUILDING THE SOFTWARE PACKAGE ON LINUX

Install latest mono and mono-devel RPM - Obtain RPMs from
www.go-mono.org.


BUILDING THE SOFTWARE PACKAGE

Windows:  Start at Step 1.
Linux:  Skip to Step 2.

1. Run cygwin.bat to start up Cygwin.

2. Generate autotools files:
./autogen.sh --prefix=/<install_dir>  [--enable-debug]
(<install_dir> is some writable directory where 'make install' will
install files for testing.

3. To reconfigure later, or to configure software that came from a source
distribution (.tar.gz) file, use configure.
./configure --prefix/<install_dir> [--enable-debug]
(run ./configure --help for more options)

4. Select your make target, here are a few interesting ones:

make [all] - build product files (package files not included)

make clean - clean up files built by 'make all'

make package - build product and package files

make package-clean - clean up package files

make install - install product files to <install_dir> specified by
--prefix during configure

make uninstall - undo 'make install'

make dist - build a source distribution tarball.

make distclean - removes files to return state back to same as the
source distribution (configure, Makefile.in files, and other distributed
autotools files are not removed)

make maintainer-clean - removes files to return state back to same as
the CVS checkout (you will need to run ./autogen.sh again before running
make again)

SECURITY CONSIDERATIONS

CASA Authentication Tokens when compromised can be used to either impersonate
a user or to obtain identity information about the user. Because of this it is
important that the tokens be secured by applications making use of them. It is
recommended that the tokens be transmitted using SSL.