301 lines
13 KiB
Plaintext
301 lines
13 KiB
Plaintext
/***********************************************************************
|
|
*
|
|
* 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 -
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|