Product-Level Security Guidelines for Production Deployment¶

This section provides the list of product-level security guidelines that are recommended for your production environment.

Security updates¶

Apply all the security patches relevant to your WSO2 Identity Server version. For more information, see here

Default keystores¶

Change the default keystores and create new keys for all the cryptographic operations. WSO2 Identity Server 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 truststore that is shipped with the product.

Passwords in config files¶

WSO2 Identity Server uses a tool called Secure Vault to encrypt the plain-text passwords in configuration files. For instructions, see Encrypt Passwords with the Cipher Tool.

Default ports¶

All the default ports that are used by WSO2 Identity Server are listed in Default Ports of WSO2 Identity Server, e.g., the default HTTPS port is 9443 and the HTTP port is 9763. For instructions on changing default ports, see Change the default port offset.

Access to external systems¶

Read-only access¶

If your WSO2 Identity Server is connecting to an external userstore, such as Microsoft Active Directory, for the purpose of reading and retrieving user information, make sure to enable read-only access to that userstore. For instructions, see Configure Userstores.

TLS¶

To ensure adequate network-level protection, all connections from your WSO2 Identity Server to external databases, userstores (LDAP), or other services should be over TLS. Therefore, make sure to use TLS-enabled external systems.

Priviledged users¶

When connecting WSO2 Identity Server to external databases or userstores (LDAP), make sure to go through a user who does not have permission to change the data store's schema.

HTTPS security¶

To have strong transport-level security, use TLS 1.2 and disable SSL, TLS 1.0, and 1.1.

The TLS protocol and ciphers are configured for an HTTP connector using the SSLEnabled element in the <IS_HOME>/repository/conf/deployment.toml file. For instructions, see Configure Transport-Level Security.

HTTP response¶

When sending HTTP responses, by default, WSO2 Identity Server passes WSO2 Carbon Server as the server value in HTTP headers. This means that information about WSO2 Identity Server stack will be exposed through HTTP responses.

It is recommended to change this by configuring the server name in the deployment.toml file in the <IS_HOME>/repository/conf directory. For instructions, see Configure Transport Level Security.

HSTS¶

For products based on Carbon 4.4.11 or later versions, HTTP Strict Transport Security (HSTS) is disabled for the applications with which WSO2 Identity Server is shipped by default. This is because HSTS validation can interrupt the development processes by validating signatures of self-signed certificates.

Make sure to enable HSTS for all the applications that are deployed in WSO2 Identity Server. This includes the WSO2 Identity Server Management Console and any other web applications. For instructions, see Enable HTTP Strict Transport Security (HSTS) Headers.

Browser cache¶

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.

Ephemeral Diffie-Hellman key size¶

Before starting the server,

1. Open the product startup script in the <IS_HOME>/bin directory.

   Linux/Mac OS

   wso2server.sh

   Windows

   wso2server.bat

2. Add the following with the other Java properties.

   -Djdk.tls.ephemeralDHKeySize=2048 \

Client-initiated renegotiation¶

Before starting the server,

1. Open the product startup script in the <IS_HOME>/bin directory.

   Linux/Mac OS

   wso2server.sh

   Windows

   wso2server.bat

2. Add the following with the other Java properties.

   -Djdk.tls.rejectClientInitiatedRenegotiation=true \

HostName verification¶

To enable hostname verification,

1. Open the product startup script in the <IS_HOME>/bin directory.

   Linux/Mac OS

   wso2server.sh

   Windows

   wso2server.bat

2. For products with the Carbon version 4.4.17 or later, set the hostnameVerifier property to Strict.

   -Dhttpclient.hostnameVerifier=Strict \

3. For products with the Carbon version prior to 4.4.17, set the ignoreHostnameVerification property to false.

   -Dorg.wso2.ignoreHostnameVerification=false \

XSS protection¶

By default, XSS attacks are prevented in the latest WSO2 Identity Server versions. This is due to output encoding of the displaying values. 

JSESSIONID length¶

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

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

Admin credentials¶

By default, WSO2 Identity Server has the Administrator account configured. The default username and password of the administrator account are admin.

Follow the instructions given below to change the administrator credentials.

1. Sign in to the WSO2 Identity Server Management Console (https://<IS_HOST>:<PORT>/carbon) with the admin credentials.

2. Click Main > Identity > User and Roles > Users.

3. Click List.

4. Click Change Password option that is relevant to the admin user and change the password.

Access to management console¶

Majority of the users only need to sign in to the connected service providers via WSO2 Identity Server. Such users should not have permissions to sign in to the WSO2 Identity Server Management Console.

Make sure that the permission for signing in to the WSO2 Identity Server Management Console is granted only to the users that need to use the Management Console. Instead of granting all permission to one administrator, distribute the responsibilities among multiple administrators by assigning different permissions. For instructions, see Manage User Roles.

Log rotation and monitoring¶

Ensure that you have a relevant log rotation scheme to manage logs. Log4J properties for WSO2 Identity Server can be configured in the log4j2.properties file in the <IS_HOME>/repository/conf folder.

To roll the wso2carbon.log based on the size, use the following configurations.

appender.CARBON_LOGFILE.type = RollingFile
appender.CARBON_LOGFILE.fileName = ${sys:carbon.home}/repository/logs/wso2carbon.log
appender.CARBON_LOGFILE.policies.size.size=10MB
appender.CARBON_LOGFILE.strategy.max = 20

Log forging¶

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

JVM parameters¶

• The recommended JDK versions are JDK 1.8 and 11. For more information, see Prerequisites.

  -Xms512m -Xmx2048m 

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

Mutual SSL¶

If mutual SSL is enabled, enable intermediate certificate validation as well to make sure that only certificates signed by the issuers mentioned in the IntermediateCertValidation configuration are allowed to be used during mutual SSL authentication.

If mutual SSL authentication capabilities are not required, you can disable it .

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 Identity Server REST APIs that are marked as secure under the ResourceAccessControl tag of the <IS_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 <IS_HOME>/repository/conf/deployment.toml file.

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

     [identity.auth_framework.endpoint] 
     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.

     [account_recovery.endpoint.auth]
     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 EndpointConfig.properties 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 EndpointConfig.properties file located in the <IS_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 RecoveryEndpointConfig.properties 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 RecoveryEndpointConfig.properties file located in the <IS_HOME>/repository/deployment/server/webapps/accountrecoveryendpoint/WEB-INF/classes directory.

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

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

Callback URL Regular Expressions¶

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

• Password Recovery
• Username Recovery
• Self User Registration
• Lite User Registration