Configure Process Services using a properties file named activiti-app.properties
. This file must be placed on the application server’s classpath to be found.
Additionally, the properties file is available with the following options:
- An
activiti-app.properties
file with default values in the WAR file (or exploded WAR folder) under theWEB-INF/classes/META-INF/activiti-app
folder. - An
activiti-app.properties
file with custom values on the classpath. For example, theWEB-INF/classes
folder of the WAR, the/lib
folder of Tomcat, or other places specific to the web container being used.
The values of a configuration file on the classpath have precedence over the values in the WEB-INF/classes/META-INF/activiti-app/activiti-app.properties
file.
For the Process Services user interface, there is an additional configuration file named app-cfg.js
. This file is located inside the .war file’s script
directory.
At a minimum, the application requires the following settings to run:
- A database connection using a JDBC connection or JNDI data source.
- An accurate Hibernate dialect.
All other properties use the default settings, and this will be allow the application to start up and run.
General settings
By default, the following properties are defined:
Property | Description |
---|---|
server.contextroot | The context root on which the user accesses the application. This is used in various places to generate URLs to correct resources. The default value is activiti-app . |
security.rememberme.key | Used for cookie validation. In a multi-node setup, all nodes must have the same value for this property. |
security.csrf.disabled | When true , the cross-site forgery (CSRF) protection is disabled. The default value is false . |
security.signup.disabled | When true , the Process Services sign up functionality is disabled. An error message sign up is not possible will be displayed. The default value is false . |
Encrypt configuration properties
You can encrypt sensitive properties in the activiti-app.properties
, activiti-admin.properties
and activiti-ldap.properties
configuration files.
-
Download Jasypt http://www.jasypt.org/download.html.
-
Extract the zip file and grant yourself full run permissions on its
bin
directory.You need to know what encryption algorithms are supported. If you’re using the JVM to which the application will be deployed you can do this using the listAlgorithms tool that Jasypt provides: http://www.jasypt.org/cli.html.
Note: Certain algorithms such as
SHA1 (PBEWITHSHA1ANDDESEDE)
andMD5 (PBEWithMD5AndDES)
are available on most JVMs but more secure algorithms require modifications to the JRE policies. -
Choose an algorithm.
If you do not specify an algorithm to Jasypt, then you effectively obtain the default of
PBEWithMD5AndDES
. Some algorithms may appear in the list but may not be usable as the JRE policy blocks them.If you want to increase your range of choices then you can modify the JRE policies: https://www.ca.com/us/services-support/ca-support/ca-support-online/knowledge-base-articles.tec1698523.html. There is an equivalent for the IBM JRE: https://www-01.ibm.com/marketing/iwm/iwm/web/reg/pick.do?source=jcesdk..
Algorithms using AES are generally considered most secure. TripleDES also passes security checks at present. You should consult your security department for advice specific to your organization and the needs of your server.
-
Use the Jasypt tools to encrypt the value.
You can use the encrypt script that comes with Jasypt to encrypt the value against your chosen secret password. In addition to their documentation, see this guide: http://www.programering.com/a/MjN1kTNwATg.html.
We recommend to avoid using quotes. Also check that you can decrypt the value, preferably using the intended JRE.
-
Deploy the application.
See the application installation instructions.
-
Set the value in the properties file.
If the property is called datasource.password, remove the existing entry and put in a new entry of the form
datasource.password=ENC(<ENCRYPTEDPASSWORD>)
whereENCRYPTEDPASSWORD
is the value encrypted by Jasypt. -
Configure your application server to set the encryption algorithm and secret encryption password.
If, for example, you are using Tomcat on Unix then you could include a shell script called
setenv.sh
in tomcat_home/bin with the following content:export JAVA_OPTS="$JAVA_OPTS -Djasypt.encryptor.password=secretpassword -Djasypt.encryptor.algorithm=PBEWITHSHA1ANDDESEDE"
This assumes that your password is
secretpassword
and you are using the algorithmPBEWITHSHA1ANDDESEDE
. The configuration could alternatively be done instartup.sh
.If you then run using
catalina.sh
you will see the secret password in the logging on application startup. This is a Tomcat feature, which you can disable by removing<Listener className="org.apache.catalina.startup.VersionLoggerListener" />
from your Tomcat’sserver.xml
https://stackoverflow.com/questions/35485826/turn-off-tomcat-logging-via-spring-boot-application You may initially, however, want to leave this on for diagnostic purposes until you’ve proven you’ve got encryption working. For an example of this, see https://stackoverflow.com/questions/17019233/pass-user-defined-environment-variable-to-tomcat.For other servers there will be other ways of setting environment/JVM variables. These values can be read as JVM parameters, environment variables or as property file entries (though you would not want to put the secret encryption password in a property file). Therefore, with WebSphere they could set using JVM parameter config http://www-01.ibm.com/support/docview.wss?uid=swg21417365 or environment variable config https://www.ibm.com/support/knowledgecenter/en/SSAW57_8.5.5/com.ibm.websphere.nd.doc/ae/welcvariables.html..
-
Start the application.
The application should now start as normal. If it doesn’t, try without the encrypted values and without the encryption parameters to determine whether the problem is related to the encryption setup. Check that you are able to encrypt and decrypt with Jasypt to rule out any issues due to copy-paste errors.
-
Logging.
Some property values (though not sensitive ones) are logged by Alfresco applications if the log level is set high. If you want to restrict this then reduce the log level in
log4j.properties
CORS
To enable Cross Origin Resource Sharing (CORS) in Process Services, set the cors.enabled
property to true in the
activiti-app.properties
file.
Note: This feature is only supported on Tomcat application server.
# CORS CONFIGURATION
#
cors.enabled=true
When CORS is enabled, CORS requests can be made to all endpoints under /activiti-app/api
.
Also, some additional properties are made available which can be configured to further fine tune CORS. This will make CORS available only to certain origins or to restrict the valid HTTP methods that can be used and headers that can be sent with CORS-enabled requests.
cors.enabled=false
cors.allowed.origins=*
cors.allowed.methods=GET,POST,HEAD,OPTIONS,PUT,DELETE
cors.allowed.headers=Authorization,Content-Type,Cache-Control,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,X-CSRF-Token
cors.exposed.headers=Access-Control-Allow-Origin,Access-Control-Allow-Credentials
cors.support.credentials=truecors.preflight.maxage=10
Property | Description |
---|---|
cors.allowed.origins | Specifies the hosts allowed in cross origin requests. By default, the value is set to * , which permits clients hosted on any server to access the resources. Alternatively, you can specify a host, for example, http://www.example.org:8080 , which will only allow requests from this host.Multiple entries or wildcards are not allowed for this setting. In general, it is recommended to restrict `` to only allow origins within your organization to make requests. |
cors.allowed.methods | Configures which HTTP requests are permitted. GET, POST, HEAD, OPTIONS, PUT, DELETE |
cors.allowed.headers | Specifies the headers that can be set manually or programmatically in the request headers in addition to the ones set by the user agent (for example, Connection). The default values are: Authorization Content-Type Cache-Control X-Requested-With Accept Origin Access-Control-Request-Method Access-Control-Request-Headers X-CSRF-Token |
cors.exposed.headers | Allows you to whitelist the headers that the client can access from the server. The default value exposes the following headers: Access-Control-Allow-Origin Access-Control-Allow-Credentials |
cors.support.credentials | Determines whether HTTP cookie and HTTP Authentication-based credentials are allowed. The default value is true . |
cors.preflight.maxage | Preflighted requests use the OPTIONS method to first verify the resource availability and then request it. This property determines the maximum time (in minutes) for caching a preflight request. The default value is 10 . |
To disable CORS set the following property in the activiti-app.properties
file:
cors.enabled=false
Cross-Site Request Forgery (CSRF)
Cross-Site Request Forgery, also referred to as CSRF, is one of the most common form of attacks plaguing web browsers. This type of attack results in a malicious request being submitted on a user’s behalf without their consent.
Typically, when the CSRF setting is enabled and an HTTP request against a web application is made, then the token values sent from the client to the server are validated to prevent unauthorized requests that were not generated by the server. The CSRF tokens are usually stored on the server and verified every time a request is sent. However, in Process Services, this feature has been implemented slightly differently, wherein, CSRF tokens are generated on the client instead of the server and placed in a cookie CSRF-TOKEN
and a header X-CSRF-TOKEN
. The server side then verifies if the header and cookie values match.
Where:
X-CSRF-TOKEN
= header valueCSRF-TOKEN
= cookie value
This provides extra security as the cookie that belongs to Process Services can only be accessed for pages generated or served by the Process Services domain.
Note: The CSRF protection is only available for resources used by the web application, such as the private REST API (not public REST API).
By default, the CSRF protection setting is enabled in Process Services, however to disable it, make the following changes:
- Open the
activiti-app.properties
file from the<ActivitiInstall>/tomcat/lib
folder. - Locate the
security.csrf.disabled
setting and then modify it totrue
. For example:security.csrf.disabled=true
License configuration
If you start up the application without a license, it will enter read only mode; however, you can upload a license from the user interface at a later stage. In this situation, use the following configuration properties to configure the license.
Property | Description |
---|---|
license.multi-tenant | If no license is available on first bootstrap this property decides if system will go into single or multi-tenant mode. The default value is false . |
license.default-tenant | If no license is available on first bootstrap this property decides the name of the default tenant. The default value is tenant . |
license.allow-upload | Decides if license uploads should be allowed in the system or not. The default value is true . |
Cookie configuration
Process Services uses an HTTP cookie to store a user session. You can use multiple cookies for different browsers and devices. The application uses a database table to store the cookie values (called tokens internally), to allow a shared persistent session store in a multi-node setup.
It’s possible to change the settings regarding cookies:
Property | description | default |
---|---|---|
security.cookie.max-age | The maximum age of a cookie, expressed in seconds. The max-age determines the period in which the browser will send the cookie with the requests. | 2678400 (31 days) |
security.cookie.refresh-age | The age of a cookie before it is refreshesd. Refreshing means a new token will be created and a new cookie will be returned which the browser will use for subsequent requests. Setting the refresh-age low, will result in many new database rows when the user is using the application.To avoid that a user is suddenly logged out when using the application when reaching the max-age above, tokens are refreshed after this period (expressed in seconds). | 86400 (1 day) |
By default, cookies will have the secure
flag set, when the request being made is HTTPS. If you only want to use the remember-me cookie over HTTPS (i.e. make the secure flag mandatory), set the property security.cookie.always-secure
to true
.
To avoid that the persistent token table gets too full, a background job periodically removes obsolete cookie token values. Possible settings:
Property | description | default |
---|---|---|
security.cookie.database-removal.max-age | The maximum age an entry in the database needs to have to be removed. | Falls back to the security.cookie.max-age setting if not found. This effectively means that cookies which are no longer valid could be removed immediately from the database table. |
security.cookie.database-removal.cronExpression | The cron expression determining when the obsolete database table entries for the cookie values will be checked for removal. | 0 0 1 * * ? (01:00 at night) |