/*********************************************************************** * * 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: 43200 10 /home/jluciani/jakarta-tomcat-5.0.28/webapps/CasaAuthTokenSvc/WEB-INF/conf/iaRealms.xml 60 o=novell 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: CorpTree Krb5Authenticate host@tokenserver.company.novell.com CorpTree PwdAuthenticate 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: 3600 10 CasaIdentityToken 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: sn,groupMembership,guid false Base64 encoded certificate 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: com.novell.casa.authtoksvc.Krb5Authenticate WEB-INF/classes host@authtokenserver.company.com 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 -