CASA/CASA-auth-token/server-java/Svc/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 AuthTokenSvc
 *
 ***********************************************************************/

INTRODUCTION

AuthTokenSvc is the CASA Authentication Token Service (ATS). It is implemented
as a Java servlet and supporting classes that execute in the Tomcat environment.

The ATS is responsible for providing clients with the necessary authentication
policy information, for authenticating client entities, and for providing
clients with Authentication Tokens that they can then use for authenticating
to CASA Authentication enabled services.

The ATS utilizes mechanism plug-ins for authenticating client entities as well
Identity Token Providers for the generation of Identity Tokens.

ENVIRONMENT SETTINGS

The following options must be set in the JAVA_OPTS environment variable before
starting Tomcat to allow the Kerberos authentication mechanism to work properly
with Sun's Java:

-Djava.security.auth.login.config={replace with the path for JAAS configuration
                                   file for the service}
                                   
After setting the above values in the JAVA_OPTS variable you must export it for
Tomcat to be able to make use of it.

The following entry should be included in the JAAS configuration file specified
in the java.security.auth.login.config option above to enable the Krb5 authentication
mechanism to work correctly:

other {
com.sun.security.auth.module.Krb5LoginModule required
      useTicketCache=true
      ticketCache="/var/cache/tomcat5/base/temp/ticket.cache"
      useKeyTab=true
      principal="host/server.company.com"
      doNotPrompt=true
      storeKey=true
      keyTab="/etc/krb5.keytab";
}

Please adjust the ticketCache and principal setting to match your installation.

By default, AuthTokenSvc reads its configuration from the "conf" folder under
the WEB-INF folder of the Tomcat Web Application ($CATALINA_HOME/webapps/CasaAuthTokenSvc/WEB-INF/conf).
This can be over-ridden by setting the following option in the JAVA_OPTS environment variable:

 -Dcom.novell.casa.authtoksvc.config={replace with the path to the configuration
                                      folder}

CONFIGURATION

AuthTokenSvc configuration consists of multiple entities. The authTokenSvc configuration
is contained within the "conf" folder under the WEB-INF folder of the application
($CATALINA_HOME/webapps/CasaAuthTokenSvc/WEB-INF/conf). For an example configuration setup
for the AuthTokenSvc see the sampleConf folder.

The location of the AuthTokenSvc configuration folder can be over-ridden by specifying
a different path via the com.novell.casa.authtoksvc.config system property.

CONFIGURING THE BASE SERVICE

The ATS base settings are configured in the svc.settings file under the conf folder.

The following is an example svc.settings file:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
	<SessionTokenLifetime>43200</SessionTokenLifetime>
	<LifetimeShorter>10</LifetimeShorter>
	<IAConfigFile>/etc/CASA/authtoken/svc/iaRealms.xml</IAConfigFile>
	<ReconfigureInterval>60</ReconfigureInterval>
	<SigningKeyAliasName>signingKey<SigningKeyAliasName>
	<SigningKeyPassword>secret<SigningKeyPassword>
</settings>

Note the following about the sample svc.settings file:

- The settngs that you can specify in the svc.settings file are: SessionLifetime,
  LifetimeShorter, and IAConfigFile.
  
- The SessionTokenLifetime setting specifies the number of seconds for which a
  session token is good for after being issued. The default value for this setting
  is 43200 seconds. Note that a larger value reduces overhead.
  
- The LifetimeShorter setting specifies the number of seconds that should be substracted
  from the SessionTokenLifetime when calculating the number of seconds that clients are
  told that the session tokens are good for.  The default value for this setting is 5
  seconds.
  
- The IAConfigFile settings specifies the path to the identity abstraction
  configuration file. The identity abstraction configuration file configures
  the different realms (contexts) that the ATS can utilize to authenticate
  entities and resolve identities. In the future the configuration of this
  settng will be optional.

- The ReconfigureInterval setting specifies how often the ATS should refresh its
  configuration. The default value for this setting is 60 seconds. A ReconfigureInterval
  value of 0 means that the ATS will not refresh its configuration once it has been
  initialized, thus requiring that the servlet be re-initialized to make configuration
  changes take effect.
  
- The SigningKeyAliasName setting specifies the alias name of the entry in the keystore
  with the private key utilized to sign tokens. The value of this setting defaults to
  "signingKey".

- The SigningKeyPassword setting specifies the password utilized to protect the private key
  used for signing tokens that is stored in the keystore. The value of this setting defaults to
  "secret".

ATSs digitally sign tokens, for this purpose it is necessary that keys be generated and installed
in a keystore whose location and properties are configured in the casa_crypto.properties file present in
the "classes" folder under the WEB-INF folder of the AuthTokenSvc application
($CATALINA_HOME/webapps/CasaAuthTokenSvc/WEB-INF/classes). Please note that you must edit the
casa_crypto.properties file with the appropriate information once the AuthTokenSvc is deployed to
a Tomcat server to deal with your configuration requirements.
 
CONFIGURING SERVICES TO CONSUME CASA AUTHENTICATION TOKENS

By default, an ATS will issue CASA authentication tokens to be consumed by any service
not explicitedly configured as a consumer in the ATS's configuration. This default
behavior can be turned off by setting the following system property in the JAVA_OPTS
environment variable:

 -Dcom.novell.casa.authtoksvc.enabled_svcs_only=true

Services explicitedly configured as consumers of CASA authentication tokens by creating
folders under the conf/enabled_services folder. Since CASA distinguishes between services
of the same name existing in different hosts, the first folder that must be created
is one for the host where the service resides. The host folder name must match the
DNS name of the host where the service resides unless the service resides in the same
host as the ATS in which case the host folder name must be "localhost". Services are
configured by creating a folder under the appropriate host folder with a name matching
the service name.

Note when configuring services that the service folder and the host folder names must match
the service and host names specified by the client applications when requesting tokens to
authenticate to them with the exception of when the service resides in the same host as the
ATS in which case the host folder name is "localhost" and the host name specified by the
application is the host's DNS name.

The services folder can contain an auth.policy file, an authtoken.settings file,
and an identoken.settings file. In the absence of any one of those files or if the service
is not explicitedly configured, the ATS will default to utilizing the files present under
its conf folder.

The auth.policy file specifies the authentication realms (or contexts) to which
entities can authenticate to gain access to the service. The auth.policy file also
specifies the authentication mechanisms that can be utilized to authenticate to the
realms.

The following is an example auth.policy file: 

<?xml version="1.0" encoding="UTF-8"?>
<auth_policy>
	<auth_source>
		<realm>CorpTree</realm>
		<mechanism>Krb5Authenticate</mechanism>
		<mechanism_info>host/tokenserver.company.novell.com@KRB_REALM</mechanism_info>
	</auth_source>
	<auth_source>
		<realm>CorpTree</realm>
		<mechanism>PwdAuthenticate</mechanism>
		<mechanism_info></mechanism_info>
	</auth_source>
</auth_policy>

Note the following about the sample auth.policy file:

- An authentication realm is specified in the auth.policy file by creating an
  auth_policy entry for it. An auth_policy entry must contain the realm name along
  with the entries for the authentication mechanisms.
  
- When a realm supports more than one authentication mechanism, you must create
  an auth_source entry for each supported mechanism.
  
- The realm names correspond to the realmIDs configured in the Identity Abstraction
  configuration file for the desired context entry.
  
- The authentication mechanism entries are: mechanism and mechanism_info. The mechanism
  entry specifies the name of the authentication mechanism. The mechanism_info specifies
  some mechanism specific information, the need for this entry is dependent on the
  configuration requirements of the specified mechanism.
  
- The name of the Krb5 Authentication mechanism is "Krb5Authenticate". This mechanism
  defaults the service principal name to host/hostname@KERBEROS_REALM. You can use a
  different service principal name under the mechanism_info key.
  
- The name of the username/password authentication mechanism is "PwdAuthenticate" and
  it does not require any information to be included under the mechanism_info key.
  
The authtoken.settings file contains settings that should be applied to authentication
tokens issued to authenticate to the service.

The following is an example authtoken.settings file:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
	<TokenLifetime>3600</TokenLifetime>
	<LifetimeShorter>10</LifetimeShorter>
	<IdentityTokenType>CasaIdentityToken</IdentityTokenType>
</settings>

Note the following about the sample authtoken.settings file: 

- The settings that you can specify in the authtoken.settings file are: TokenLifetime,
  LifetimeShorter, and IdentityTokenType. If one of this tokens is not specified then
  its default value is utilized.
  
- The TokenLifetime setting specifies the number of seconds for which a token is good
  for after being issued. The default value for this setting is 3600 seconds. Note that
  a larger value reduces overhead, but it also gives more time for an intruder to
  utilize the token if it becomes compromised.
  
- The LifetimeShorter setting specifies the number of seconds that should be substracted
  from the TokenLifetime when calculating the number of seconds that clients are told
  that the tokens are good for.  The default value for this setting is 5 seconds.
  
- The IdentityTokenType specifies the type of identity tokens that must be embedded in
  the authentication tokens with identity information. The default value for this
  setting is CasaIdentityToken.
  
The identoken.settings file contains settings that should be applied to identity tokens
embedded in authentication tokens.

The following is an example identoken.settings file:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
	<Attributes>sn,groupMembership,guid</Attributes>
	<EncryptAttributes>false</EncryptAttributes>
</settings>

Note the following about the sample identoken.settings file:

- The settings that you can specify in the identoken.settings file are: Attributes.
  EncryptAttributes, and Certificate.
  
- The Attributes setting specifies the identity attributes that must be included
  as part of the identity token, The attributes are specified in the form of a coma
  delimited list. The default velue for this setting is "sn".
  
- The EncryptAtributes setting specifies whether or not the identity information
  contained in the identity token should be emcrypted with the services's Public
  Certificate. The default value for this setting is "false". Please note that
  to enable identity attribute encryption you must not allow the ATS to default to
  the file present in its conf folder (Attribute encryption is not yet supported
  by the Casa identity token provider).
  
- The identoken.settings file can also contain additional identity token provider
  specific settings.
  
CONFIGURING AUTHENTICATION MECHANISMS

Authentication mechanisms available to the AuthTokenSvc are configured by creating
a sub-folder named after the authentication mechanism type under the
conf/auth_mechanisms folder. The authentication mechanism folders must contain a
settings file named mechanism.settings. The mechanism.settings file must contain the
name of the class implementing the mechanism along with path information which
can be utilized by the ATS to load the class. The mechanism.settings file can
also contain mechanism specific settings.

The following setting is mandatory:

ClassName - This is the name of the class implementing the authentication mechanism.

One of the following settings must be included:

RelativeClassPath - This is a relative path from the web application's root folder
to the folder containing the class implementing the mechanism.

ClassPath - This is an absolute path to the folder containing the path to the class
implementing the mechanism.

The following is an example mechanism.settings file for the Krb5Authentication
mechanism:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
	<ClassName>com.novell.casa.authtoksvc.Krb5Authenticate</ClassName>
	<RelativeClassPath>WEB-INF/classes</RelativeClassPath>
	<ServicePrincipalName>host</ServicePrincipalName>
</settings>

The base AuthTokenSvc package contains two authentication mechanisms, these are
Krb5Authenticate and PwdAuthenticate. The configuration under sampleConf is set up
to allow an AuthTokenSvc to leverage both mechanisms.

The Krb5Authenticate mechanism defaults the service principal name to "host/hostname",
you can over-ride this parameter by adding the following entry to its mechanism.settings file:

ServicePrincipalName - This is the name of the Kerberos Service Principal that the
Authentication Token Service runs as when authenticating other entities.

CONFIGURING ADDITIONAL IDENTITY TOKEN PROVIDERS

<This feature is not currently supported>

SECURITY CONSIDERATIONS

The ATS runs over Tomcat and by default receives requests over HTTPS on port 2645. For ease
of use, the basic ATS setup scrip creates a self-signed certificate to be used by SSL. The
use of self-signed certificates weakens the security properties of the SSL channel by forcing
clients to accept them. At this time, the default mode for auth_token clients is to allow
self signed-certificates. It is recommended that administrators obtain a certificate signed
by the appropriate authority and configure the ATS to use it and change the auth_token client
configuration to not accept invalid certificates to avoid this issue.

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.