358 lines
16 KiB
Plaintext
358 lines
16 KiB
Plaintext
/***********************************************************************
|
|
*
|
|
* 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="UTF-8"?>
|
|
<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, and IAConfigFile.
|
|
|
|
- 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 casa_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
|
|
casa_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/enabled_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="UTF-8"?>
|
|
<auth_policy>
|
|
<auth_source>
|
|
<realm>CorpTree</realm>
|
|
<mechanism>Krb5Authenticate</mechanism>
|
|
<mechanism_info>SVC_PRINCIPAL=host/tokenserver.company.novell.com</mechanism_info>
|
|
</auth_source>
|
|
<auth_source>
|
|
<realm>CorpTree</realm>
|
|
<mechanism>PwdAuthenticate</mechanism>
|
|
<mechanism_info>REALM_CREDENTIALS_ONLY=true</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. You can use a different
|
|
service principal name by setting the SVC_PRINCIPAL setting equal to it under the
|
|
mechanism_info key. Notice that mechanism info settings for this mechanism are
|
|
separated using a semicolon and no-white space is allowed.
|
|
|
|
- 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. You
|
|
can specify to the client to only utilize credentials for the specified realm by
|
|
setting the mechanism info setting REALM_CREDENTIALS_ONLY equal to "true". Notice that
|
|
mechanism info settings for this mechanism are separated using a semicolon and no-white
|
|
space is allowed.
|
|
|
|
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="UTF-8"?>
|
|
<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="UTF-8"?>
|
|
<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="UTF-8"?>
|
|
<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
|
|
|
|
The ATS runs over Tomcat and by default receives requests over HTTPS on port 2645. For ease
|
|
of use, the basic ATS setup scrip creates a self-signed certificate to be used by SSL. The
|
|
use of self-signed certificates weakens the security properties of the SSL channel by forcing
|
|
clients to accept them. At this time, the default mode for auth_token clients is to allow
|
|
self signed-certificates. It is recommended that administrators obtain a certificate signed
|
|
by the appropriate authority and configure the ATS to use it and change the auth_token client
|
|
configuration to not accept invalid certificates to avoid this issue.
|
|
|
|
CASA Authenticatication Tokens when compromised can be used to either impersonate
|
|
a user or to obtain identity information about the user. Because of this it is
|
|
important that the tokens be secured by applications making use of them. It is
|
|
recommended that the tokens be transmitted using SSL.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|