CASA/CASA-auth-token/java/server/Svc/README

/***********************************************************************
 *
 *  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 setting before starting Tomcat
to allow the Kerberos authentication mechanism to work properly:

-Djavax.security.auth.useSubjectCredsOnly=false
-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. 

CONFIGURATION

AuthTokenSvc configuration consists of multiple entities. Most of the AuthTokenSvc
configuration is contained within the "conf" folder under the WEB-INF folder of the
application. 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.

Thhe following is an example svc.settings file:

<?xml version="1.0" encoding="ISO-8859-1"?>
<settings>
	<SessionTokenLifetime>43200</SessionTokenLifetime>
	<LifetimeShorter>10</LifetimeShorter>
	<IAConfigFile>/home/jluciani/jakarta-tomcat-5.0.28/webapps/CasaAuthTokenSvc/WEB-INF/conf/iaRealms.xml</IAConfigFile>
	<ReconfigureInterval>60</ReconfigureInterval>
	<startSearchContext>o=novell</startSearchContext>
</settings>

Note the following about the sample svc.settings file:

- The settngs that you can specify in the svc.settings file are: SessionLifetime,
  LifetimeShorter, IAConfigFile, and startSearchContext.
  
- 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 startSearchContext setting specifies the begin location for initiating
  context searches. The absence of this setting will result in searches ocurring
  from the root of the tree. This setting or an equivalent setting will be moved
  to the identity abstraction configuration file where it belongs. Once this is done,
  the setting will no longer be recognized within the svc.settings file. 
 
CONFIGURING SERVICES TO CONSUME CASA AUTHENTICATION TOKENS

Services are configured to consume CASA authentication tokens by creating folders
under the conf/enabled_services folders. 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. 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 name and the host names must match
the service and host names specified by the client applications when requesting
tokens to authenticate to them.

The services folder must contain an auth.policy file, an authtoken.settings file,
and an identoken.settings file. In the absence of any one of those files, 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="ISO-8859-1"?>
<auth_policy>
	<auth_source>
		<realm>CorpTree</realm>
		<mechanism>Krb5Authenticate</mechanism>
		<mechanism_info>host@tokenserver.company.novell.com</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. Both authentication mechanism entries must be
  specified for an auth_source entry.
  
- The name of the Krb5 Authentication mechanism is "Krb5Authenticate". This mechanism
  requires that you specify the service's kerberos 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="ISO-8859-1"?>
<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 compromized.
  
- 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="ISO-8859-1"?>
<settings>
	<Attributes>sn,groupMembership,guid</Attributes>
	<EncryptAttributes>false</EncryptAttributes>
	<Certificate>Base64 encoded certificate</Certificate>
</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 Certificate setting specifies the certificate that must be utilized to encrypt
  identity attribute data. The certificate contains the public key of the targeted
  service. The certificate data is Base64 encoded.
  
- 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="ISO-8859-1"?>
<settings>
	<ClassName>com.novell.casa.authtoksvc.Krb5Authenticate</ClassName>
	<RelativeClassPath>WEB-INF/classes</RelativeClassPath>
	<ServicePrincipalName>host@authtokenserver.company.com</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 requires that the following setting also be included
in 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

- TBD -

SECURITY CONSIDERATIONS

- TBD -