/***********************************************************************
*
* 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.
BUILDING THE SOFTWARE PACKAGE
1. 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.
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.
Token validation requires the installation of the certificate used by ATSs to
sign the tokens. The software assumes that any certificate installed by the
administrator is valid.
a50234c0f6