/***********************************************************************
*
* 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.
REQUIREMENTS FOR BUILDING THE SOFTWARE PACKAGE ON WINDOWS
- Install Visual Studio 2005.
- 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 needed RPMs. Look at BuildRequires line in CASA_auth_token_server.spec.in file
in package/linux folder to see a list of RPM build dependencies.
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 SVN 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.
Currently, the Authentication Token Client defaults to allow the setup of SSL
connections with an ATS even if the Certificate presented by the ATS is considered
invalid. In this mode, it is possible for a malicious user to set up a server which
impersonates an ATS for the purpose of acquiring user credentials. This default
will be modified once we implement a mechanism to give the user the option of either
approving or rejecting a certificate. If this behavior is un-acceptable to you then
you can configure the client to not allow SSL connections to be setup with invalid
server certificates by modifying the settings present in the client.conf file.
