The "java" folder has been renamed "server-java" to reflect that it only
contains server components. In the process, I also flatened its directory structure.
This commit is contained in:
Juan Carlos Luciani
339
CASA-auth-token/server-java/Svc/README
Normal file
339
CASA-auth-token/server-java/Svc/README
Normal file
@@ -0,0 +1,339 @@
|
||||
/***********************************************************************
|
||||
*
|
||||
* 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="ISO-8859-1"?>
|
||||
<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, 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 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 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
|
||||
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/anabled_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="ISO-8859-1"?>
|
||||
<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="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 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="ISO-8859-1"?>
|
||||
<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="ISO-8859-1"?>
|
||||
<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
|
||||
|
||||
- TBD -
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user