/***********************************************************************
*
* 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>
<KeyStoreUser>privKey<KeyStoreUser>
<KeyStorePwd>foobar<KeyStorePwd>
</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.
- The KeyStoreUses setting specifies the user's alias name in the keystore that identifies
the private key that is to be used to sign tokens.
- The KeyStorePwd setting specifies the password of the user specified by KeyStoreUser to get
the private signing key from the keystore.
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 -
