If the directory/file paths specified in this guide do not exist in your WSO2 product, see Directory Structure of WSO2 Products to locate the paths applicable to your product.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

GuidelineDetails

Apply security updates

Apply all the security patches relevant to your product version. If your WSO2 product version is supported by WSO2 Update Manager (WUM), you need to use WUM to get the latest fixes.

Note

Note the following:

  • WSO2 releases security patch notifications monthly via the Support Portal and the above mentionedWSO2 Security Patch Releases page. However, for highly critical issues, patches are issued immediately to customers.
  • The WSO2 Security Patch Release page has all the security patches for the latest product versions. WSO2 does not issue patches publicly for older product versions. Community users are encouraged to use the latest product version to receive all the security fixes.

Change default keystores

Change the default key stores and create new keys for all the cryptographic operations. WSO2 products by default come with a self-signed SSL key. Since these keys are public, it is recommended to configure your own keys for security purposes. Consider the following guidelines when creating the keystores:

  • Select a key size of at least 2048 bits.

  • Use an SHA256 certificate.

  • Make sure that WSO2 default certificates do not exist in any of the keystores in your production environment. For example, be sure to delete the default public certificate in the default trust store that is shipped with the product.

See the recommendations for using keystores in WSO2 products for information.
See Creating New Keystores for information on how to create and configure your own keys.

Encrypt passwords in configuration files

WSO2 products use a tool called Secure Vault to encrypt the plain-text passwords in configuration files.

See Securing Passwords in Configuration Files for instructions.

Change default ports


All the default ports used by WSO2 products are listed in Default Ports of WSO2 Products. For example, the default HTTPS port is 9443 and the HTTP port is 9763. Also, Axis2 services are exposed over the following ports: 8243 and 8280.

To change a default port, update the <Offset> element in the carbon.xml file as explained in Changing the Default Ports.

Enable read-only access to external user stores (LDAPs etc.)

If your WSO2 product is connecting to an external user store, such as Microsoft Active Directory, for the purpose of reading and retrieving user information, be sure to enable read-only access to that user store.

For example, see Configuring a Read-Only LDAP User Store under Configuring User Stores for instructions.

Always communicate (with external user stores) over TLS

All connections from your WSO2 product to external databases, userstores (LDAP), or other services, should be over TLS, to ensure adequate network-level protection. Therefore, be sure to use external systems (user stores, databases) that are TLS-enabled.

Connect to data stores using a less privileged user

When connecting the WSO2 product to external databases or user stores (LDAP), be sure to go through a user who does not have permission to change the data store's schema. Be sure not to use the root user of the data store because all permissions are generally granted to the root user.

Configure strong HTTP(S) security

To have strong transport-level security, use TLS 1.2 and disable SSL, TLS 1.0 and 1.1. The TLS protocol and strong ciphers are configured for an HTTP connector in the catalina-server.xml file (using the sslEnabledProtocols and ciphers attributes). See the following links for instructions:

Note

Note the following:

  • When deciding on the TLS protocol and the ciphers, consider the compatibility with existing client applications. Imposing maximum security might cause functional problems with client applications.
  • Apply ciphers with 256 bits key length if you have applied the Unlimited strength policy. Note that Unlimited strength policy is recommended.
  • Also, consider the following factors when deciding on the ciphers:
    • DES/3DES are deprecated and should not be used.
    • MD5 should not be used, due to known collision attacks.
    • RC4 should not be used, due to crypto-analytical attacks.
    • DSS is limited to a small 1024 bit key size.
    • Cipher-suites that do not provide Perfect Forward Secrecy/ Forward Secrecy (PFS/FS).
    • GCM based ciphers are recommended over CBC ciphers.

Remove weak ciphers for PassThrough transport

Note

Applicable only to products that use the PassThrough transport, such as WSO2 API Manager and WSO2 Enterprise Integrator (ESB profile).

Remove any weak ciphers from the PassThrough transport and ensure that the server does not accept connections using those weak ciphers. The PassThrough transport is configured using the axis2.xml file (stored in the <PRODUCT_HOME>/repository/conf/axis2/ directory. You need to add the PreferredCiphers parameter under the "Transport Ins (Listeners)" section along with the list of relevant cipher suites.

See Configuring the PassThrough Transport for instructions.

Update the HTTP Response header "Server" value

By default, all WSO2 products pass "WSO2 Carbon Server" as the server value in HTTP headers when sending HTTP responses. This means that information about the WSO2 product stack will be exposed through HTTP responses. It is recommended to change this by configuring the server name in the catalina -server.xml file.

See Configuring Transport Level Security for instructions.

Enabling HTTP Strict Transport Security Headers (HSTS)

Be sure that HTTP Strict Transport Security (HSTS) is enabled for all the applications deployed in your WSO2 server. This includes the management console, and any other web applications and/or Jaggery applications.

Note that (for products based on Carbon 4.4.11 or later versions) HSTS is disabled for the applications with which the product is shipped by default. This is because HSTS validation can interrupt the development processes by validating signatures of self-signed certificates.

See the topic on Enabling HTTP Strict Transport Security Headers for instructions.

Preventing browser caching

If there are dynamic pages in your application with sensitive information, you need to prevent browser caching. This can be done by making sure that the applications deployed in your server will return the relevant HTTP response headers.

Note that cache prevention headers are enabled for the applications with which the product is shipped by default. Therefore, you need to manually enable cache prevention headers only for all the new applications that you deploy in your server.

See the topic on Preventing browser caching for instructions.

Increase Ephemeral Diffie-Hellman Key size

Before starting the server, open the product startup script (wso2server.sh in Linux and wso2server.bat in Windows) and enter the following with the other Java properties:

Code Block
-Djdk.tls.ephemeralDHKeySize=2048 \

Disable client-initiated renegotiation


Before starting the server, open the product startup script (wso2server.sh in Linux and wso2server.bat in Windows) and enter the following with the other Java properties:

Code Block
-Djdk.tls.rejectClientInitiatedRenegotiation=true \

Enable HostName Verification


If your product is using Carbon Kernel 4.4.17 or a later version, make sure that hostname verification is enabled in the product startup script (wso2server.sh in Linux and wso2server.bat in Windows) with the Strict mode. That is, you need to enable the following parameter:

Code Block
-Dhttpclient.hostnameVerifier=Strict \

In Carbon versions prior to 4.4.17, be sure that hostname verification is enabled by setting the following property to false.

Code Block
-Dorg.wso2.ignoreHostnameVerification=false \

See Enabling HostName Verification for instructions.

Enable additional XSS Protection

XSS attacks are prevented on the latest WSO2 products by default. This is due to output encoding of the displaying values. However, if additional protection is required, an input validation valve can be configured.

See Mitigating Cross Site Scripting Attacks for instructions.

Increase JSESSIONID length

If required, increase the session ID length by changing the sessionIDLength attribute of the session manager in the context.xml file (stored in the <PRODUCT_HOME>/repository/conf/tomcat/context.xml directory) as shown below. The default value is 16 bytes.

Code Block
<Manager className="org.wso2.carbon.webapp.mgt.CarbonTomcatSessionManager" sessionIdLength="16"></Manager>

Change default admin credentials


All WSO2 products have the Administrator account configured by default. The default user nameand password of the administrator account is "admin". To change the administrator credentials, you need to first sign in tothe management console of the product as "admin", and then use the Change Password option under  Home->Configure->User Management->Users in the navigator.

See Changing a Password for more information on how to change the password of the administrator.

Restrict access to the management console


Make sure that the permission for signing into the management console is granted only to the users that need to use the management console. For example, in products such as WSO2 Identity Server and WSO2 API Manager, the majority of users only need to login to the connected service providers via the WSO2 product. Therefore, such users should not have permission to log into the management console.

You can make sure that only administrative users have access to the product's management console. Further, instead of granting all permission to one administrator, you can distribute the responsibilities among administrators by assigning different permissions for conducting various tasks.

See Managing Users, Roles and Permissions for instructions.

Disable the TryIt Tool in the management console
Note
titleNote

Be sure to disable the Try It tool of the management console in your production environment by adding the following system property to the carbon.properties file (stored in the <EI_HOME>/conf/ folder): 

Code Block
tryitFunctionalityDisabledtryItFunctionalityDisabled=true


The Try It tool is useful for testing purposes in the ESB profile of WSO2 Enterprise Integrator but it is not recommended to be used in a production environment.

Enable log rotation and monitoring


Ensure that you have a relevant log rotation scheme to manage logs. Log4J properties for WSO2 products can be configured in the <PRODUCT_HOME>/repository/conf/log4j.properties file. To roll the wso2carbon.log based on size, the following configurations can be used.

Code Block
log4j.appender.CARBON_LOGFILE=org.apache.log4j.RollingFileAppender
log4j.appender.CARBON_LOGFILE=${carbon.home}/repository/logs/${instance.log}/wso2carbon${instance.log}.log
log4j.appender.CARBON_LOGFILE.MaxFileSize=1000KB
log4j.appender.CARBON_LOGFILE.MaxBackupIndex=10

See Monitoring Logsfor details on how to configure logging details in WSO2 products.

Prevent Log Forging

Log forging can be prevented by appending a UUID to the log message.

See Monitoring Logsfor more information on configuring the log4j.properties file.

Set appropriate JVM parameters


The recommended JDK version is JDK 1.7 or 1.8. See the installation pre-requisites for more information.

For JDK 1.7, set the appropriate Heap and Permgen values for the JVM based on your deployment scenario. These can be set in the <PRODUCT_HOME>/bin/wso2server.sh file. You do not need to set this in JDK 1.8 as the MaxPermSize value has been removed from Hotspot JVM.

Code Block
titleFor example
-Xms512m -Xmx2048m -XX:MaxPermSize=1024m
Tip

Tip: To run the JVM with 2 GB (-Xmx2048m), you should ideally have about 4GB of memory on the physical machine.

Securing Carbon Applications

See Securing Carbon Applications for information.

Warning

Applicable to the Business Process profile of WSO2 EI:

Note that the BPMN Explorer and the  Human Task Explorer are sample web applications enabled in the Business Process profile of WSO2 Enterprise Integrator. These apps are not recommended for use in a production environment. 

If required, you can develop your own web apps to replace the BPMN Explorer and Human Task Explorer.

...