5.2.8 security.xml
The security.xml file configures the security in use by the environment for WAS-specific, J2EE standard, and Java standard values. Throughout this file are mappings between J2EE security standards and the IBM implementation of that standard. For example, IBM implements the java.security.provider standard with the IBMJSSE2 implementation, where JSSE2 is the IBM JSSEs provider.
An AIX platform administrator will need to understand this file when configuring host security and SSL and firewall configuration, and when installing IBM cryptography adapters within the environment to allow the platform and WAS environments to function together.
The outermost element in the file is the security:Security element used to configure general settings such as whether security is enabled, how the user names are configured and what the cache timeout settings are; see Example 5-12.
Example 5-12 security.xml: outermost element
<?xml version="1.0" encoding="UTF-8"?> <security:Security xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:orb.securityprotocol="http://www.ibm.com/websphere/appserver/schemas/5.0/orb.se curityprotocol.xmi" xmlns:security="http://www.ibm.com/websphere/appserver/sche mas/5.0/security.xmi" xmi:id="Security_1" useLocalSecurityServer="true" useDomainQualifiedUserNames="true" enabled="false" cacheTimeout="600" issuePermissionWarning="true" activeProtocol="BOTH" enforceJava2Security="true" enforceFineGra inedJCASecurity="false" appEnabled="false" dynamicallyUpdateSSLConfig="true" activeAuthMechanism="LTPA_1" activeUserRegistry="LDAPUserRegistry_1" defaultSSLSettings="SSLConfig_1">
Directly inside the security:Security tag is the authMechanisms element that configures what type of security is to be used by the instance (Lightweight Third Party Authentication), as shown in Example 5-13. This then controls what other elements are used within the configuration.
Of particular importance are the Trust Association Interceptor (TAI) settings that load an appropriate TAI to map the external security to the internal tokens using the trustAssociation and interceptors elements. For example, the SPNEGO TAI allows Kerberos authentication to be used by the Web container for single signon.
Example 5-13 security.xml: authMechanisms detail
<authMechanisms xmi:type="security:LTPA" xmi:id="LTPA_1" OID="oid:1.3.18.0.2.30.2"
authContextImplClass="com.ibm.ISecurityLocalObjectTokenBaseImpl.WSSecurityContextLTPA
Impl" authConfig="system.LTPA" simpleAuthConfig="system.LTPA" auth
ValidationConfig="system.LTPA" timeout="120" keySetGroup="KeySetGroup_1">
<trustAssociation xmi:id="TrustAssociation_1" enabled="true">
...
<interceptors xmi:id="TAInterceptor_3"
interceptorClassName="com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl"/>
...
</trustAssociation>
<singleSignon xmi:id="SingleSignon_1" requiresSSL="false" domainName=""
enabled="true"/>
</authMechanisms>
...
The userRegistries element, shown in Example 5-14, is used to identify the location for user information. With WAS 6.1, a combination of user registries can be used concurrently via the Federated Repositories option. This section includes file and LDAP registry configuration, including support for Windows Active DirectoryŽ. This section is useful for identifying hostnames, IP addresses and ports for the target LDAP and Kerberos servers, so it can be useful for platform and network firewall configuration information.
Example 5-14 security.xml: userRegistries detail
<userRegistries xmi:type="security:LocalOSUserRegistry" xmi:id="LocalOSUserRegistry"
serverId="" serverPassword="{xor}" realm="" useRegistryServerId="true"
primaryAdminId=""/>
<userRegistries xmi:type="security:CustomUserRegistry"
xmi:id="CustomUserRegistry_1" useRegistryServerId="true" primaryAdminId=""
customRegistryClassName="com.ibm.websphere.security.FileRegistrySample"/>
The authConfig and applicationLoginConfig section follows the userRegistries sections and configure modules for handling specific security environments, as shown in Example 5-15, such as those set up by the Java Authentication and Authorization Service (JAAS) or Tivoli Access Manager (TAM).
Example 5-15 security.xml: specific security environment detail
<authConfig xmi:id="AuthorizationConfig_1" useJACCProvider="false">
<authorizationProviders xmi:id="AuthorizationProvider_1"
j2eePolicyImplClassName="com.tivoli.pd.as.jacc.TAMPolicy" name="Tivoli Access
Manager"
policyConfigurationFactoryImplClassName="com.tivoli.pd.as.jacc.TAMPolicyConfiguration
Fac
tory"
roleConfigurationFactoryImplClassName="com.tivoli.pd.as.jacc.TAMRoleConfigurationFact
ory" initializeJACCProviderClassName="com.tivoli.pd.as.jacc.cfg.TAMConfigInitialize"
requiresEJBArgumentsPolicyContextHandler="false" supportsDyn
amicModuleUpdates="true"/>
</authConfig>
<applicationLoginConfig xmi:id="JAASConfiguration_1">
<entries xmi:id="JAASConfigurationEntry_1" alias="ClientContainer">
<loginModules xmi:id="JAASLoginModule_1"
moduleClassName="com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy"
authenticationStrategy="REQUIRED">
<options xmi:id="Property_1" name="delegate"
value="com.ibm.ws.security.common.auth.module.WSClientLoginModuleImpl"/>
</loginModules>
</entries>
...
</applicationLoginConfig>
Some of the most important configuration sections inside the security.xml file are found in the CSI and IBM element sections, as shown in Example 5-16. These sections configure the CSIv2 security setup that underlies the J2EE EJB container standard, and in the latter case, the IBM WebSphere-specific settings for it. Layers of security are configured in this area with IIOP settings and garbage collection settings to ensure appropriate management of the information used for security. Remember that IIOP is the protocol used for communication with the EJBs in the EJB container.
Example 5-16 security.xml: CSI and IBM element section detail
<CSI xmi:id="IIOPSecurityProtocol_1">
<claims xmi:type="orb.securityprotocol:CommonSecureInterop" xmi:id="CSIv2 Inbound
Configuration" stateful="true">
<layers xmi:type="orb.securityprotocol:IdentityAssertionLayer"
xmi:id="IdentityAssertionLayer_1">
<supportedQOP xmi:type="orb.securityprotocol:IdentityAssertionQOP"
xmi:id="IdentityAssertionQOP_1" enable="false"/>
</layers>
...
<serverAuthentication xmi:id="IIOPTransport_1" sslConfig=""/>
</layers>
</claims>
<performs xmi:type="orb.securityprotocol:CommonSecureInterop" xmi:id="CSIv2
Outbound Configuration" stateful="true" sessionGCInterval="300000"
sessionGCIdleTime="900000">
<layers xmi:type="orb.securityprotocol:IdentityAssertionLayer"
xmi:id="IdentityAssertionLayer_2">
...
</layers>
</layers>
...
<serverAuthentication xmi:id="IIOPTransport_2" sslConfig=""/>
</layers>
</performs>
</CSI>
<IBM xmi:id="IIOPSecurityProtocol_2">
<claims xmi:type="orb.securityprotocol:SecureAssociationService"
xmi:id="SecureAssociationService_1">
<layers xmi:type="orb.securityprotocol:TransportLayer"
xmi:id="TransportLayer_3">
<supportedQOP xmi:type="orb.securityprotocol:TransportQOP"
xmi:id="TransportQOP_5" enableProtection="true" confidentiality="true"
integrity="true"/>
<serverAuthentication xmi:id="IIOPTransport_3" sslConfig=""/>
</layers>
</claims>
<performs xmi:type="orb.securityprotocol:SecureAssociationService"
xmi:id="SecureAssociationService_2">
<layers xmi:type="orb.securityprotocol:TransportLayer"
xmi:id="TransportLayer_4">
<supportedQOP xmi:type="orb.securityprotocol:TransportQOP"
xmi:id="TransportQOP_6" enableProtection="true" confidentiality="false"
integrity="false"/>
<serverAuthentication xmi:id="IIOPTransport_4" sslConfig=""/>
</layers>
</performs>
</IBM>
The repertoire elements section, shown in Example 5-17, configures SSL/TLS and keystore settings for the Cell and Node. Note that for Web services security, SSL is not part of the WS-Security standards because it is subject to replay attacks under certain circumstances. For this reason, TLS is likely to be configured here.
Example 5-17 security.xml: repertoire element section detail
<repertoire xmi:id="SSLConfig_1" alias="CellDefaultSSLSettings"
managementScope="ManagementScope_1">
<setting xmi:id="SecureSocketLayer_1" clientAuthentication="false"
securityLevel="HIGH" enabledCiphers="" jsseProvider="IBMJSSE2" sslProtocol="SSL_TLS"
keyStore="KeyStore_1" trustStore="KeyStore_2" trustManager="TrustManager_1" keyM
anager="KeyManager_1"/>
</repertoire>
<repertoire xmi:id="SSLConfig_1172252999890" alias="NodeDefaultSSLSettings"
managementScope="ManagementScope_1172252999891">
<setting xmi:id="SecureSocketLayer_1172252999891" clientAuthentication="false"
securityLevel="HIGH" enabledCiphers="" jsseProvider="IBMJSSE2" sslProtocol="SSL_TLS"
keyStore="KeyStore_1172252999891" trustStore="KeyStore_2" trustManag
er="TrustManager_1172252999891" keyManager="KeyManager_1172252999891"/>
</repertoire>
The systemLoginConfig element section, shown in Example 5-18, contains a large number of entries elements that contain loginModules elements. These elements and their attribute values configure the different login modules and options for different types of login.
The module configurations for Lightweight Third Party Authentication (LTPA) and Simple WebSphere Authentication Mechanism (SWAM) high level enabling configuration is here. SWAM was important in earlier WAS releases, but is deprecated in Version 6.1 and will be removed in a future release.
Example 5-18 security.xml: systemLoginConfig section detail
<systemLoginConfig xmi:id="JAASConfiguration_2">
<entries xmi:id="JAASConfigurationEntry_4" alias="SWAM">
<loginModules xmi:id="JAASLoginModule_4"
moduleClassName="com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy"
authenticationStrategy="REQUIRED">
<options xmi:id="Property_8" name="delegate"
value="com.ibm.ws.security.server.lm.swamLoginModule"/>
</loginModules>
</entries>
<entries xmi:id="JAASConfigurationEntry_5" alias="LTPA">
<loginModules xmi:id="JAASLoginModule_5"
moduleClassName="com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy"
authenticationStrategy="REQUIRED">
<options xmi:id="Property_9" name="delegate"
value="com.ibm.ws.security.server.lm.ltpaLoginModule"/>
</loginModules>
</entries>
...
<entries xmi:id="JAASConfigurationEntry_28" alias="WSS_OUTBOUND">
<loginModules xmi:id="JAASLoginModule_29"
moduleClassName="com.ibm.ws.security.server.lm.wsMapCSIv2OutboundLoginModule"
authenticationStrategy="REQUIRED"/>
</entries>
</systemLoginConfig>
The properties element section, shown in Example 5-19, identifies individual properties that can be configured and enabled as part of the WAS security setup.
Example 5-19 security.xml: properties element section detail
<properties xmi:id="Property_20" name="security.enablePluggableAuthentication" value="true" required="false"/> ... <properties xmi:id="Property_37" name="com.ibm.audit.auditPolicy" value="REQUIRED" required="false"/> <properties xmi:id="Property_38" name="com.ibm.audit.auditQueueSize" value="5000" required="false"/> ... <properties xmi:id="Property_43" name="com.ibm.security.useFIPS" value="false" required="false"/> <properties xmi:id="Property_44" name="com.ibm.websphere.security.DeferTAItoSSO" value="com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl" description="Trust Association Interceptors in this list will be invoked after Single Sign On user validation." required="false"/> <properties xmi:id="Property_1172272088006" name="com.ibm.security.SAF.authorization" value="false"/>
The webAuthAttrs element section, shown in Example 5-20, configures the behavior of the authentication mechanisms at the application server level for Web container, particularly what happens when a particular type of authentication mechanism is not available for a given application.
Example 5-20 security.xml: webAuthAttrs element section detail
<webAuthAttrs xmi:id="DescriptiveProperty_1" name="com.ibm.wsspi.security.web.webAuthReq" value="lazy" type="String" displayNameKey="" nlsRangeKey="" hoverHelpKey="" range="lazy,persisting,always" inclusive="false" firstClass="false"/ > <webAuthAttrs xmi:id="DescriptiveProperty_2" name="com.ibm.wsspi.security.web.failOverToBasicAuth" value="false" type="boolean" displayNameKey="" nlsRangeKey="" hoverHelpKey="" range="" inclusive="false" firstClass="false"/>
Within the WAS ND and WAS XD environments, security can be configured and managed at various levels (that is, at the cell level, the node level, and so on). This is configured in the managementScopes element sections, shown in Example 5-21, that identify what levels are in use in the given environment.
Example 5-21 security.xml: managementScopes element section detail
<managementScopes xmi:id="ManagementScope_1" scopeName="(cell):spock44pCell01" scopeType="cell"/> <managementScopes xmi:id="ManagementScope_1172252999891" scopeName="(cell):spock44pCell01:(node):spock44pNode01" scopeType="node"/>
One of the most important configuration items for the security.xml file is the keyStores element section, shown in Example 5-22. It identifies the keystore locations, what security is used to access them (including passwords), what internal providers are used for access and management, and then which security management scope they apply to.
Example 5-22 security.xml: keyStores element section detail
<keyStores xmi:id="KeyStore_1" name="CellDefaultKeyStore" password="{xor}CDo9Hgw="
provider="IBMJCE" location="${CONFIG_ROOT}/cells/spock44pCell01/key.p12"
type="PKCS12" fileBased="true" hostList="" managementScope="ManagementScope_1"
/>
<keyStores xmi:id="KeyStore_2" name="CellDefaultTrustStore"
password="{xor}CDo9Hgw=" provider="IBMJCE"
location="${CONFIG_ROOT}/cells/spock44pCell01/trust.p12" type="PKCS12"
fileBased="true" hostList="" managementScope="ManagementScop
e_1"/>
<keyStores xmi:id="KeyStore_3" name="CellLTPAKeys" password="{xor}CDo9Hgw="
provider="IBMJCE" location="${CONFIG_ROOT}/cells/spock44pCell01/ltpa.jceks"
type="JCEKS" fileBased="true" hostList="" managementScope="ManagementScope_1"/>
<keyStores xmi:id="KeyStore_1172252999891" name="NodeDefaultKeyStore"
password="{xor}CDo9Hgw=" provider="IBMJCE"
location="${CONFIG_ROOT}/cells/spock44pCell01/nodes/spock44pNode01/key.p12"
type="PKCS12" fileBased="true" hostList="" ma
nagementScope="ManagementScope_1172252999891"/>
...
<keyStores xmi:id="KeyStore_1172252999910" name="NodeDefaultTrustStore"
password="{xor}CDo9Hgw=" provider="IBMJCE"
location="${CONFIG_ROOT}/cells/spock44pCell01/nodes/spock44pNode01/trust.p12"
type="PKCS12" fileBased="true" hostList="
" managementScope="ManagementScope_1172252999891"/>
During the setup of an SSL connection, the application server uses trust managers for certificate validation during the handshake process, with a standard X509 and an IBM-specific PKI provider provided by default, although custom trust managers can also be installed. These perform tasks like checking certificate revocation lists (CRLs).
The trustManagers element configuration section, shown in Example 5-23, should be considered a key part of the SSL configuration for the platform, and should be examined if the platform is experiencing SSL-related networking problems.
Example 5-23 security.xml: trustManagers element section detail
<trustManagers xmi:id="TrustManager_1" name="IbmX509" provider="IBMJSSE2"
algorithm="IbmX509" managementScope="ManagementScope_1"/>
<trustManagers xmi:id="TrustManager_2" name="IbmPKIX" provider="IBMJSSE2"
algorithm="IbmPKIX" trustManagerClass="" managementScope="ManagementScope_1">
<additionalTrustManagerAttrs xmi:id="DescriptiveProperty_1"
name="com.ibm.security.enableCRLDP" value="true" type="boolean" displayNameKey=""
nlsRangeKey="" hoverHelpKey="" range="" inclusive="false" firstClass="false"/>
<additionalTrustManagerAttrs xmi:id="DescriptiveProperty_2"
name="com.ibm.jsse2.checkRevocation" value="true" type="boolean" displayNameKey=""
nlsRangeKey="" hoverHelpKey="" range="" inclusive="false" firstClass="false"/>
</trustManagers>
<trustManagers xmi:id="TrustManager_1172252999891" name="IbmX509"
provider="IBMJSSE2" algorithm="IbmX509"
managementScope="ManagementScope_1172252999891"/>
<trustManagers xmi:id="TrustManager_1172252999911" name="IbmPKIX"
provider="IBMJSSE2" algorithm="IbmPKIX" trustManagerClass=""
managementScope="ManagementScope_1172252999891">
<additionalTrustManagerAttrs xmi:id="DescriptiveProperty_1172252999911"
name="com.ibm.security.enableCRLDP" value="true" type="boolean" displayNameKey=""
nlsRangeKey="" hoverHelpKey="" range="" inclusive="false" firstClass="false"/>
<additionalTrustManagerAttrs xmi:id="DescriptiveProperty_1172252999912"
name="com.ibm.jsse2.checkRevocation" value="true" type="boolean" displayNameKey=""
nlsRangeKey="" hoverHelpKey="" range="" inclusive="false" firstClass="false"/
>
</trustManagers>
The keyManagers, keySetGroups, and keySets element sections, shown in Example 5-24, are used to configure access to keystores and set up the management scope they apply to and what providers they use. Passwords for accessing those keystores are configured here, therefore, they should be protected.
Example 5-24 security.xml: keyManagers, keySetGroups, keySets element section detail
<keyManagers xmi:id="KeyManager_1" name="IbmX509" provider="IBMJSSE2"
algorithm="IbmX509" keyManagerClass="" managementScope="ManagementScope_1"/>
<keyManagers xmi:id="KeyManager_1172252999891" name="IbmX509" provider="IBMJSSE2"
algorithm="IbmX509" keyManagerClass=""
managementScope="ManagementScope_1172252999891"/>
<keySetGroups xmi:id="KeySetGroup_1" name="CellLTPAKeySetGroup" autoGenerate="true"
wsSchedule="WSSchedule_1" keySet="KeySet_1 KeySet_2"
managementScope="ManagementScope_1"/>
<keySets xmi:id="KeySet_1" name="CellLTPAKeyPair" aliasPrefix="LTPAKeyPair"
password="{xor}CDo9Hgw=" maxKeyReferences="2" deleteOldKeys="true"
keyGenerationClass="com.ibm.ws.security.ltpa.LTPAKeyPairGenerator" isKeyPair="true"
keyStor
e="KeyStore_3" managementScope="ManagementScope_1">
<keyReference xmi:id="KeyReference_1172271449639" keyAlias="LTPAKeyPair_3"
version="3"/>
<keyReference xmi:id="KeyReference_1196517802804" keyAlias="LTPAKeyPair_4"
version="4"/>
</keySets>
<keySets xmi:id="KeySet_2" name="CellLTPASecret" aliasPrefix="LTPASecret"
password="{xor}CDo9Hgw=" maxKeyReferences="2"
keyGenerationClass="com.ibm.ws.security.ltpa.LTPAKeyGenerator" keyStore="KeyStore_3"
managementScope="ManagementSc
ope_1">
<keyReference xmi:id="KeyReference_1172271460420" keyAlias="LTPASecret_3"
version="3"/>
...
<keyReference xmi:id="KeyReference_1196517802804" keyAlias="LTPAKeyPair_4"
version="4"/>
</keySets>
<keySets xmi:id="KeySet_2" name="CellLTPASecret" aliasPrefix="LTPASecret"
password="{xor}CDo9Hgw=" maxKeyReferences="2"
keyGenerationClass="com.ibm.ws.security.ltpa.LTPAKeyGenerator" keyStore="KeyStore_3"
managementScope="ManagementSc
ope_1">
<keyReference xmi:id="KeyReference_1172271460420" keyAlias="LTPASecret_3"
version="3"/>
<keyReference xmi:id="KeyReference_1196517820815" keyAlias="LTPASecret_4"
version="4"/>
</keySets>
The wsSchedules, wsNotifications, and wsCertificateExpirationMonitor element sections, shown in Example 5-25, are used to configure scheduled checks against keys and certificates for expiration or invalidation (that is, against certificate revocation lists) and to perform the necessary actions and notifications.
Example 5-25 security.xml: wsSchedules, wsNotifications, wsCertificateExpirationMonitor section detail
<wsSchedules xmi:id="WSSchedule_1" name="LTPAKeySetSchedule" frequency="90" dayOfWeek="1" hour="22" nextStartDate="1211148043754"/> <wsSchedules xmi:id="WSSchedule_2" name="ExpirationMonitorSchedule" frequency="30" dayOfWeek="1" hour="21" minute="30" nextStartDate="1201469458829"/> <wsNotifications xmi:id="WSNotification_1" name="MessageLog" logToSystemOut="true" emailList=""/> <wsCertificateExpirationMonitor xmi:id="WSCertificateExpirationMonitor_1" name="Certificate Expiration Monitor" autoReplace="true" deleteOld="true" daysBeforeNotification="60" isEnabled="true" wsNotification="WSNotification_1" wsSched ule="WSSchedule_2"/>
The sslConfigGroups element section, shown in Example 5-26, is used to map a given SSL configuration for the environment to the appropriate management scope configured in the managementScopes section.
Example 5-26 security.xml: sslConfigGroups element section detail
<sslConfigGroups xmi:id="SSLConfigGroup_1" name="spock44pCell01" direction="inbound" sslConfig="SSLConfig_1" managementScope="ManagementScope_1"/> <sslConfigGroups xmi:id="SSLConfigGroup_2" name="spock44pCell01" direction="outbound" sslConfig="SSLConfig_1" managementScope="ManagementScope_1"/> <sslConfigGroups xmi:id="SSLConfigGroup_1172252999925" name="spock44pNode01" direction="inbound" sslConfig="SSLConfig_1172252999890" managementScope="ManagementScope_1172252999891"/> <sslConfigGroups xmi:id="SSLConfigGroup_1172252999926" name="spock44pNode01" direction="outbound" sslConfig="SSLConfig_1172252999890" managementScope="ManagementScope_1172252999891"/> </security:Security>
