Web Container Application Security (webAppSecurity)

Configures web container application security.

NameTypeDefaultDescription

allowAuthenticationFailOverToAuthMethod

  • APP_DEFINED

  • BASIC

  • FORM

Specifies the authentication failover method that is used when the certificate authentication fails or if the certificate is missing. Valid values are BASIC, FORM, and APP_DEFINED. APP_DEFINED is only valid when overrideHttpAuthMethod attribute is set to CLIENT_CERT. When APP_DEFINED is set, the authentication method that is configured in the application is used.

allowFailOverToBasicAuth

boolean

false

Specifies whether to fail over to basic authentication when certificate authentication fails. The equivalent custom property in the full application server profile is com.ibm.wsspi.security.web.failOverToBasicAuth.

allowLogoutPageRedirectToAnyHost

boolean

false

Warning, security risk: Setting this property to true may open your systems to potential URL redirect attacks. If set to true, any host can be specified for the logout page redirect. If set to false, and the logout page points to a different host, or one not listed in the logout page redirect domain list, then a generic logout page is displayed. The equivalent custom property in the full application server profile is com.ibm.websphere.security.allowAnyLogoutExitPageHost.

basicAuthenticationMechanismRealmName

string

defaultRealm

Specifies a realm name for the Java EE 8 Security HTTP basic authentication. This value is applicable when overrideHttpAuthMethod is set to BASIC, or if overrideHttpAuthMethod is set to CLIENT_CERT and allowAuthenticationFailOverToAuthMethod is set to BASIC. The default value is defaultRealm.

contextRootForFormAuthenticationMechanism

string

Specifies the context root of a form login page, which is specified by the loginFormURL property. If this value is not set, the first path element of the loginFormURL property is used as a context root. This value is applicable when overrideHttpAuthMethod is set to FORM, or if overrideHttpAuthMethodis is set to CLIENT_CERT and allowAuthenticationFailOverToAuthMethod is set to FORM.

displayAuthenticationRealm

boolean

false

Warning, security risk: if this property is set to true, and the user registry's realm name contains sensitive information, it is displayed to the user. For example, if an LDAP configuration is used, the LDAP server hostname and port are displayed. This configuration controls what the HTTP basic authentication login window displays when the realm name is not defined in the application web.xml. If the realm name is defined in the application web.xml file, this property is ignored. If set to true, the realm name displayed will be the user registry realm name for the LTPA authentication mechanism. If set to false, the realm name displayed will be "Default Realm". The equivalent custom property in the full application server profile is com.ibm.websphere.security.displayRealm.

httpOnlyCookies

boolean

true

Specifies whether the HTTP only (HttpOnly) cookies option is enabled.

includePathInWASReqURL

boolean

false

Setting the Path parameter can allow the client/browser to manage multiple WASReqURL cookies during multiple concurrent logins on the same user agent. The equivalent custom property in the full application server profile is com.ibm.websphere.security.setContextRootForFormLogin.

loggedOutCookieCacheRef

A reference to top level cache element (string).

The JCache cache reference that is used as the logged-out-cookie cache.

loginErrorURL

string

Specifies the global URL of a form login error page that includes the root context. The form login error page must be part of a WAR file. An application uses the global login error URL if the application uses form login authentication and does not specify either the form login page or the login error page in the auth-method element of the web.xml file. This is required when overrideHttpAuthMethod attribute is set to FORM.

loginFormURL

string

Specifies the global URL of a form login page including the root context. The form login page must be part of the WAR file. If a form login application does not specify the form login page in the web.xml file, it uses the global form login URL. This is required when overrideHttpAuthMethod attribute is set to FORM.

logoutOnHttpSessionExpire

boolean

false

Specifies whether users will be logged out after the HTTP session timer expires. If set to false, the user credential will stay active until the Single Sign-On token timeout occurs. The equivalent custom property in the full application server profile is com.ibm.ws.security.web.logoutOnHTTPSessionExpire.

logoutPageRedirectDomainNames

string

A pipe (|) separated list of domain names that are allowed for the logout page redirect (localhost is implied). The equivalent custom property in the full application server profile is com.ibm.websphere.security.logoutExitPageDomainList.

overrideHttpAuthMethod

  • BASIC

  • CLIENT_CERT

  • FORM

Specifies the authentication method to be used for all applications. This specified value overrides any application defined authentication method. The acceptable value is BASIC, FORM or CLIENT_CERT. When FORM is used, loginFormURL and loginErrorURL attributes are required to be set.

postParamCookieSize

int

16384

Size of the POST parameter cookie. If the size of the cookie is larger than the browser limit, unexpected behavior may occur. The value of this property must be a positive integer and represents the maximum size of the cookie in bytes. The equivalent custom property in the full application server profile is com.ibm.websphere.security.util.postParamMaxCookieSize.

postParamSaveMethod

  • Cookie

  • None

  • Session

Cookie

Specifies where POST parameters are stored upon redirect. Valid values are cookie (POST parameters are stored in a cookie), session (POST parameters are stored in the HTTP Session) and none (POST parameters are not preserved). The equivalent custom property in the full application server profile is com.ibm.websphere.security.util.postParamSaveMethod.

preserveFullyQualifiedReferrerUrl

boolean

false

Warning, security risk: Setting this to true may open your systems to potential URL redirect attacks. This property specifies whether the fully qualified referrer URL for form login redirects is preserved. If false, the host for the referrer URL is removed and the redirect is to localhost. The equivalent custom property in the full application server profile is com.ibm.websphere.security.util.fullyQualifiedURL

sameSiteCookie

  • Disabled

  • Lax

  • None

  • Strict

Disabled

Specifies the SameSite attribute value to use for the SSO cookie.
Disabled
Do not set the SameSite attribute value on the SSO cookie
Lax
Set the SSO cookie SameSite attribute value to Lax
None
Set the SSO cookie SameSite attribute value to None. When None is set, the secure attribute is set to true on the cookie.
Strict
Set the SSO cookie SameSite attribute value to Strict

singleSignonEnabled

boolean

true

Specifies whether single sign-on is enabled.

ssoCookieName

string

LtpaToken2

Customizes the SSO cookie name. A custom cookie name allows you to logically separate authentication between SSO domains and to enable customized authentication to a particular environment. Before setting this value, consider that setting a custom cookie name can cause an authentication failure. For example, a connection to a server that has a custom cookie property set sends this custom cookie to the browser. A subsequent connection to a server that uses either the default cookie name or a different cookie name, is not able to authenticate the request via a validation of the in-bound cookie. The equivalent custom property in the full application server profile is com.ibm.websphere.security.customSSOCookieName.

ssoDomainNames

string

A pipe (|) separated list of domain names that SSO Cookies should be presented. The equivalent custom property in the full application server profile is com.ibm.ws.security.config.SingleSignonConfig

ssoRequiresSSL

boolean

false

Specifies whether a SSO cookie is sent over SSL. The equivalent property in the full application server profile is requiresSSL.

ssoUseDomainFromURL

boolean

false

Specifies whether to use the domain name from the request URL for the cookie domain.

trackLoggedOutSSOCookies

boolean

false

Specifies whether to track LTPA single signon tokens that are logged out on a server so that it can not be reused on the same server.

useAuthenticationDataForUnprotectedResource

boolean

true

Specifies whether authentication data can be used when accessing an unprotected resource. The unprotected resource can access validated authenticated data that it previously could not access. This option enables the unprotected resource to call the getRemoteUser, isUserInRole, and getUserPrincipal methods to retrieve an authenticated identity. The equivalent custom property in the full application server profile is com.ibm.wsspi.security.web.webAuthReq=persisting.

useContextRootForSSOCookiePath

boolean

false

Specifies that the cookie path equals the context root of the web module instead of the backslash character (/).

useLtpaSSOForJaspic

boolean

false

Enables the single sign-on behavior using the LTPA token for a JASPIC authentication. After the initial authentication is performed by the JASPIC provider, the LTPA cookie is created and used for subsequent logins to achieve the single-sign on behavior. The JASPIC provider is not called until the token expires. The JASPIC authentication applies when an external provider is used and also when the application uses the Java EE Security API annotations. The single sign-on behavior can also be achieved by enabling the JASPIC session cookie or the application provided RememberMeIdentityStore bean for a JASPIC authentication. In this case, set the useLtpaSSOForJaspic attribute to false.

useOnlyCustomCookieName

boolean

false

Specifies whether to use only the custom cookie name.

wasReqURLRedirectDomainNames

string

A pipe (|) separated list of domain names that are allowed for the WASReqURL page redirect. The hostname found on the form login request is implied.

webAlwaysLogin

boolean

false

Specifies whether the login() method will throw an exception when an identity has already been authenticated.

loggedOutCookieCache

The JCache cache reference that is used as the logged-out-cookie cache.

NameTypeDefaultDescription

cacheManagerRef

A reference to top level cacheManager element (string).

The JCache CacheManager instance that manages this cache.

name

string
Required

The JCache cache name to use for caching. If this cache does not exist, it is created at runtime. The name must be unique for a given CacheManager instance.

loggedOutCookieCache > cacheManager

The JCache CacheManager instance that manages this cache.

NameTypeDefaultDescription

cachingProviderRef

A reference to top level cachingProvider element (string).

The JCache CachingProvider that this JCache CacheManager instance uses.

uri

A file, directory or url.

Vendor-specific JCache configuration URI, which is passed to the CachingProvider when the CacheManager instance is obtained.

loggedOutCookieCache > cacheManager > cachingProvider

The JCache CachingProvider that this JCache CacheManager instance uses.

NameTypeDefaultDescription

commonLibraryRef

List of references to top level library elements (comma-separated string).

A library or libraries that contain any classes that might be stored in the cache.

jCacheLibraryRef

A reference to top level library element (string).

A library that contains the JCache implementation.

providerClass

string

The fully-qualified class name of the JCache javax.cache.CachingProvider instance.

loggedOutCookieCache > cacheManager > cachingProvider > commonLibrary

A library or libraries that contain any classes that might be stored in the cache.

NameTypeDefaultDescription

apiTypeVisibility

string

spec,ibm-api,api,stable

The types of API packages that this class loader supports. This value is a comma-separated list of any combination of the following API packages: spec, ibm-api, api, stable, third-party.

description

string

Description of shared library for administrators

filesetRef

List of references to top level fileset elements (comma-separated string).

Id of referenced Fileset

id

string

A unique configuration ID.

name

string

Name of shared library for administrators

loggedOutCookieCache > cacheManager > cachingProvider > commonLibrary > file

Id of referenced File

NameTypeDefaultDescription

id

string

A unique configuration ID.

name

Path to a file
Required

Fully qualified filename

loggedOutCookieCache > cacheManager > cachingProvider > commonLibrary > fileset

Id of referenced Fileset

NameTypeDefaultDescription

caseSensitive

boolean

true

Boolean to indicate whether or not the search should be case sensitive (default: true).

dir

Path to a directory

${server.config.dir}

The base directory to search for files.

excludes

string

The comma or space separated list of file name patterns to exclude from the search results, by default no files are excluded.

id

string

A unique configuration ID.

includes

string

*

The comma or space separated list of file name patterns to include in the search results (default: *).

scanInterval

A period of time with millisecond precision

0

The scanning interval to determine whether files are added or removed from the fileset. The individual files are not scanned. The suffix for the interval of time is h-hour, m-minute, s-second, and ms-millisecond, for example, 2ms or 5s. The scanning interval is disabled by default and is disabled manually by setting the scan interval, scanInterval, to 0. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

loggedOutCookieCache > cacheManager > cachingProvider > commonLibrary > folder

Id of referenced folder

NameTypeDefaultDescription

dir

Path to a directory
Required

Directory or folder to be included in the library classpath for locating resource files

id

string

A unique configuration ID.

loggedOutCookieCache > cacheManager > cachingProvider > jCacheLibrary

A library that contains the JCache implementation.

NameTypeDefaultDescription

apiTypeVisibility

string

spec,ibm-api,api,stable

The types of API packages that this class loader supports. This value is a comma-separated list of any combination of the following API packages: spec, ibm-api, api, stable, third-party.

description

string

Description of shared library for administrators

filesetRef

List of references to top level fileset elements (comma-separated string).

Id of referenced Fileset

name

string

Name of shared library for administrators

loggedOutCookieCache > cacheManager > cachingProvider > jCacheLibrary > file

Id of referenced File

NameTypeDefaultDescription

id

string

A unique configuration ID.

name

Path to a file
Required

Fully qualified filename

loggedOutCookieCache > cacheManager > cachingProvider > jCacheLibrary > fileset

Id of referenced Fileset

NameTypeDefaultDescription

caseSensitive

boolean

true

Boolean to indicate whether or not the search should be case sensitive (default: true).

dir

Path to a directory

${server.config.dir}

The base directory to search for files.

excludes

string

The comma or space separated list of file name patterns to exclude from the search results, by default no files are excluded.

id

string

A unique configuration ID.

includes

string

*

The comma or space separated list of file name patterns to include in the search results (default: *).

scanInterval

A period of time with millisecond precision

0

The scanning interval to determine whether files are added or removed from the fileset. The individual files are not scanned. The suffix for the interval of time is h-hour, m-minute, s-second, and ms-millisecond, for example, 2ms or 5s. The scanning interval is disabled by default and is disabled manually by setting the scan interval, scanInterval, to 0. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

loggedOutCookieCache > cacheManager > cachingProvider > jCacheLibrary > folder

Id of referenced folder

NameTypeDefaultDescription

dir

Path to a directory
Required

Directory or folder to be included in the library classpath for locating resource files

id

string

A unique configuration ID.

loggedOutCookieCache > cacheManager > properties

Vendor-specific JCache configuration properties, which are passed to the CachingProvider when the CacheManager instance is obtained.