/***********************************************************************
*
* 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 JaasSupport
*
***********************************************************************/
INTRODUCTION
CasaLoginModule is a JAAS login module which can be configured
to validate credentials consisting of CASA Authentication Tokens.
CONFIGURATION
To configure the CasaLoginModule for your service follow the following
steps:
- Set the java.security.auth.login.config property to point to the JAAS
configuration file for your application.
- Set the org.xml.sax.driver property to point to an appropriate SAX Parser.
The Xerces SAX Parser is a good option (org.apache.xerces.parsers.SAXParser).
- Include the "/etc/CASA/authtoken/keys/client" path in the applications
CLASSPATH. This is the location of the crypto.properties file used by the
module to access the keystore with the ATS's signing certificate.
- Add the "/usr/share/java/CASA/authtoken/CasaJaasSupport.jar" and the
"/usr/share/java/CASA/authtoken/CasaAuthToken.jar" paths to the applications
CLASSPATH.
- Add the jar files in the /usr/share/java/CASA/authtoken/external folder
to the applications CLASSPATH.
The JAAS configuration file should include the following line:
com.novell.casa.jaas.CasaLoginModule Required;
The CasaLoginModule supports the following parameters:
PerformUsernameCheck - This parameter when set to true tells the CasaLoginModule
that it must verify that the username is set to "CasaPrincipal". If the parameter
is not specified the username is not checked.
CLIENT PROGRAMMING NOTES
Clients must specify the same service name when requesting Authentication
Tokens from the CASA Client as the service name specified by the server
when opening a JAAS Context.
SERVER PROGRAMMING NOTES
Server applications validating credentials containing CASA Authentication
tokens can obtain information about the authenticated identity by getting
access to the CasaPrincipal that gets associated with the Subject object
returned from a successful JAAS login. The CasaPrincipal provides the
following information: username, name of the identity data source (realm),
and an URL to the identity data source. The CasaPrincipal also contains
the attributes of the authenticated identity configured as required by the
service in the Authentication Token Service.
EXAMPLE SERVER APPLICATION
See src/com/novell/casa/jaas/sample/SampleApp.java for an example application
using JAAS to authenticate credentials consisting of CASA Authentication Tokens.
Note that to get the application to run you must set the path to the JAAS configuration
file as the JAVA property java.security.auth.login.config. You must also make sure that
the JAVA property org.xml.sax.driver.org is set to a valid SAX parser. The following shows
the JAVA options that you would set to run the test application: -Djava.security.auth.login.
config=/home/user/SampleApp/SampleApp.conf -Dorg.xml.sax.driver=org.apache.xerces.parsers.
SAXParser
The SampleApp.conf file should have the following contents:
SampleApp {
com.novell.casa.jaas.CasaLoginModule Required debug=true;
};
SECURITY CONSIDERATIONS
CASA Authenticatication 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.
