Security Guidelines for Production Deployment

Given below are the common security guidelines for deploying a WSO2 product in a production environment.

Also, see the production deployment guidelines and any other product-specific guidelines that might come in the respective product's documentation.

WSO2 product-level security

Guideline Details

Apply security updates

Apply all the security patches relevant to your product version. WSO2 API manager is supported by WSO2 Update Manager (WUM) to get updates, since the version of API-M 2.1.0. Hence you need to use WUM to get the latest security patches.

Note the following:

  • WSO2 releases security patch notifications monthly via the Support Portal. However, for highly critical issues, patches are issued immediately to customers.
  • 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 issues resolved until the particular product release.

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 more information.
See Creating New Keystores for information on how to create and configure your own keys and keystores.

Encrypt passwords in configuration files

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

See Encrypting 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 with Offset.

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 more information, please refer Configuring a Read-Only LDAP User Store.

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 disable SSL protocol versions and enable only TLS protocol versions TLS 1, TLS 1.1 and TLS 1.2 . This can be done by replacing sslProtocol = "TLS" property, with sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2" under [] in deployment.toml file. And also configure strong ciphers for ThriftAuthenticationService, Tomcat transport and PassThrough transport in deployment.toml file. See the following links for instructions:

Note :
  • 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

Remove any weak ciphers from the PassThrough transport and ensure that the server does not accept connections using those weak ciphers. For this, PreferredCiphers should be configured for PassThrough transport, within the deployment.toml file in the <PRODUCT_HOME>/repository/conf/ directory.

Pleser refer Configuring Transport Level Security for more information.

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 for relavant connectors via deployment.toml.

Please refer Configuring Transport Level Security for more information.

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 WSO2 products based on Carbon 4.4.11 or later versions which implies API-M 2.1.0 and newer) 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 ( in Linux and wso2server.bat in Windows) and enter the following with the other Java properties:

-Djdk.tls.ephemeralDHKeySize=2048 \

Disable client-initiated renegotiation

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

-Djdk.tls.rejectClientInitiatedRenegotiation=true \

Enable HostName Verification

If your product is using Carbon Kernel 4.4.17 or a later version (which implies API-M 2.2.0 and newer), make sure that hostname verification is enabled in the product startup script ( in Linux and wso2server.bat in Windows) with the Strict mode. If it is not, you need to enable it as below:

-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 .

-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 done by encoding 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.

<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 name and password of the administrator account is "admin". To change the administrator credentials, you need to first sign in to the 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 the super admin credentials 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, 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 need to 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 User Roles for instructions.

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/ file . Rollover based on a time period can be configured by changing the below configuration (Default value is 1 day).

appender.CARBON_LOGFILE.policies.time.interval = 1

You can also configure rollover based on log file size, and also it is possible to limit the number of backup files. See Managing log growth for details on how to configure log rotation and manage log growth details in WSO2 API Manager.

Prevent Log Forging

Log forging can be identified by appending a UUID to the log message. The conversion character '%u' can be used in the pattern layout to log a UUID. For example, the log pattern can be set as follwing for AUDIT logs, so that the UUID will be printed at the beginning of each log record.

appender.AUDIT_LOGFILE.layout.pattern = [%u] TID: [%tenantId] [%d] %5p {%c} - %m%ex%n

See Setting up logging in API Manage for more information on configuring logging.

Set appropriate JVM parameters

The recommended JDK version is JDK 8 or 11. See the Tested Operating Systems and JDKs for more information.

You do not need to set the Heap and Permgen values for the JVM since JDK 1.8 onwards as the MaxPermSize value has been removed from Hotspot JVM.

Restrict outbound connections of Publisher node

In a WSO2 API-M deployment, WSO2 recommends that you restrict outbound connections of the Publisher node and only allow access to the required internal nodes (only to the nodes that the Publisher portal is intended to communicate with) of the deployment. Therefore, even if a situation arises where privileged user credentials are exposed to a user with malicious intent, such users will not be able to exploit and perform any unintended network interactions.

Defining callback URL regular expression

For password recovery, you can define a regular expression to validate the callback URL. The default configuration allows any callback URL. Note that if you are using the recovery option, it is highly recommended to define the regular expression that validates and only allows access to specific callback URLs.

See the Callback URL Regular Expressions documentation for details.

Configure client authentication

Client authentication is used to identify the application or client making a request to the WSO2 API Manager REST APIs. By default, web applications provided with WSO2 API Manager use a set of default credentials for authentication. However, it is recommended to change these default credentials to enhance security. For more details see, Configure client authentication

OS-level security

This section provides the list of OS-level security guidelines for your production environment.

Guideline Details

Run WSO2 processes with a specific OS-level user

Use a separate OS-level user to run WSO2 products. Make sure that the user is only granted the permissions required for running the product for that particular user. Do not use the root/administrator user of your OS because the root/administrator is granted all privileges by default.

Minimize software to avoid vulnerability

Make sure that you only install the software/packages that are relevant to your WSO2 product's deployment. Also, continuously monitor the software that you install.

See the Installation Prerequisites to identify the minimum software your WSO2 product will need.

Enable the Firewall

Enable a firewall at the OS level (for example, iptables ). This will provide protection for inbound and outbound connections of your WSO2 product. Make sure that you only open the required outbound and inbound ports from the OS-level firewall.

Restrict access to TCP ports used for clustering Apply a firewall at host-level to disallow access to TCP ports used for clustering (port 4000, 4001, … by default) from unrecognized hosts. These ports should be accessible only from other members of the WSO2 product cluster.

Use Secure Shell(SSH)

Use Secure Shell (SSH) when interacting with servers and executing commands. Adhere to the following best practices when you configure SSH:

  • Change the default ssh port to a higher value.
  • Disable the root or administrator.
  • Enable login with user keys.
  • Display a legal banner or a security banner with security warnings before SSH authentication.

Keep the system up-to-date

If there are security updates available for the packages installed in your OS (including the Java runtime), be sure to perform the necessary testing in a staging environment, and then proceed to install them for your OS.

Monitor user activities

Monitor the activities of your OS users. You can do this by enabling OS-level logs and by reviewing them regularly. You can also set up a centralized log monitoring system for this purpose.

Session Data Cleanup

Note : This security guideline is specific only to WSO2 API Manager.

In a production environment, there is a possibility for a deadlock/database lock to occur when running a session data cleanup task in high load scenarios. To mitigate this, configure the following property to clean data in chunks. Configure this property in the <IS_HOME>/repository/conf/deployment.toml file under <SessionDataCleanUp> with the required chunk size. This value is in the number of records and depends on the database type and server capacity. It also depends on the amount of load generated by single sign-on (SSO). A higher value increases the chances of deadlocks and a lower value increases the time it takes for a cleanup.

cleanup.clean_expired_session_data_in_chunks_of = 8192

For more information on configuring sessions in production, see Authentication Session Persistence in the WSO2 API Manager documentation.

Make regular backups

Make sure to backup important files and archive them continuously. See Backup and Recovery Recommendations for more information.

Network-level security

This section provides the list of security guidelines for configuring the network.

Guideline Details

Create a failover setup

When your WSO2 products are clustered, you need to regularly monitor the health of your server instances. For example, you need to monitor resource-level factors such as the server's resource utilization, response time anomalies, and the number of incoming network connections. Server monitoring will help you identify when additional server instances (failover instances) are required. You can also make decisions about network routing changes that you need to do in order to avoid server downtime.

  • See Deployment and Clustering/Key Concepts for information on configuring failover.
  • See the topics under Administer -> Product Administration -> Monitoring for information on the monitoring options for WSO2 API Manager.

Maintain network level logging

Be sure to maintain and monitor logs for your proxy servers, load balancers, and other network devices.

Check open ports and services

Periodically check for open ports using port scanning tools and make sure that only the necessary ports are open to both internal and external networks. Be sure that only the ports relevant to your WSO2 products are open for communication. If there are other ports started, be sure to monitor them.

See Default Ports of WSO2 Products for the full list of ports in all WSO2 products.

Configure device-level security

All your network devices should be periodically checked for anomalies. For example, you need to verify routing tables and firewall rules.

Also, make sure that the default credentials are changed before the first use of those devices.

Apply firmware updates

Firmware updates for your network devices should be applied regularly.

Block the /services and /carbon contexts from the DMZ

Access to the "/services" and "/carbon" contexts should be blocked from the DMZ level (i.e., from the proxy server, load balancer and/or firewall).

  • The "/services" context is used in WSO2 products to expose admin services. These admin services are used for performing administrative operations using SOAP requests.
  • The "/carbon" context is used in WSO2 products to expose the management console (administration console) of the product. The management console is a user interface for performing some of the administrative operations of a product.
  • In addition to the "/services" and "/carbon" contexts, be sure to expose only the required applications in your product to users beyond the DMZ level in your network.

Note :

It is recommended to use a whitelisting approach when allowing access to resources in your product from the DMZ level.

Configure client authentication

Client authentication is used to identify the application or the client that is making the request. The web applications provided out of the box use a set of default credentials to authenticate with WSO2 API Manager REST APIs that are marked as secure under the ResourceAccessControl tag of the <APIM_HOME>/repository/conf/identity/identity.xml file.

Follow the steps below to change the default credentials.

  1. Shut the server down in case you have already started it.

  2. Add the following configuration changes to the <APIM_HOME>/repository/conf/deployment.toml file.

    • Add the app_password property and enter a preferred password as the value.

      app_password="<value of preferred password>"
    • Add the hash property and enter the SHA-256 hash value of the app_password as the property value.

      hash="<SHA-256 hash of the newly added app_password property value>"
    • If the authenticationendpoint web app is hosted externally, follow the instructions given below.

      a. Open the file found in the root of the authenticationendpoint folder.

      b. Change the app.password property value to the value added as app_password in the deployment.toml file.

      c. Do the same changes to the file located in the <APIM_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/classes directory.

    • If the accountrecoveryendpoint web app is hosted externally, follow the instructions given below.

      a. Open the file found in the root of the accountrecoveryendpoint folder.

      b. Change the app.password property value to the value added as app_password in the deployment.toml file.

      c. Do the same changes to the file located in the <APIM_HOME>/repository/deployment/server/webapps/accountrecoveryendpoint/WEB-INF/classes directory.

  3. Once these changes are configured, restart the server.

    • Linux/Unix : sh
    • Windows : wso2server.bat