
[[_securitymanager]]
= Security Manager

IMPORTANT: Starting with JDK17, the Java Platform has deprecated the Security Manager for removal; consequently, this {PRODUCT} feature may become unsupported in the future. +
For more information: https://openjdk.org/jeps/411

The KIE engine is a platform for the modelling and execution of business behavior, using a multitude of declarative abstractions and metaphors, like rules, processes, decision tables and etc.

Many times, the authoring of these metaphors is done by third party groups, be it a different group inside the same company, a group from a partner company, or even anonymous third parties on the internet.

Rules and Processes are designed to execute arbitrary code in order to do their job, but in such cases it might be necessary to constrain what they can do.
For instance, it is unlikely a rule should be allowed to create a classloader (what could open the system to an attack) and certainly it should not be allowed to make a call to ``System.exit()``.

The Java Platform provides a very comprehensive and well defined security framework that allows users to define policies for what a system can do.
The KIE platform leverages that framework and allow application developers to define a specific policy to be applied to any execution of user provided code, be it in rules, processes, work item handlers and etc.

[[_howtodefinekiepolicy]]
== How to define a KIE Policy


Rules and processes can run with very restrict permissions, but the engine itself needs to perform many complex operations in order to work.
Examples are: it needs to create classloaders, read system properties, access the file system, etc. 

Once a security manager is installed, though, it will apply restrictions to all the code executing in the JVM according to the defined policy.
For that reason, KIE allows the user to define two different policy files: one for the engine itself and one for the assets deployed into and executed by the engine.

One easy way to setup the environment is to give the engine itself a very permissive policy, while providing a constrained policy for rules and processes.

Policy files follow the standard policy file syntax as described in the Java documentation.
For more details, see:

https://docs.oracle.com/javase/6/docs/technotes/guides/security/PolicyFiles.html#FileSyntax

A permissive policy file for the engine can look like the following:

.A sample engine.policy file
====
[source]
----
grant { 
    permission java.security.AllPermission;
}
----
====


An example security policy for rules could be:

.A sample rules.policy file
====
[source]
----
grant { 
    permission java.util.PropertyPermission "*", "read"; 
    permission java.lang.RuntimePermission "accessDeclaredMembers"; 
}
----
====


Please note that depending on what the rules and processes are supposed to do, many more permissions might need to be granted, like accessing files in the filesystem, databases, etc.

In order to use these policy files, all that is necessary is to execute the application with these files as parameters to the JVM.
Three parameters are required:



.Parameters
[cols="1,1", frame="all", options="header"]
|===
| Parameter
| Meaning

|

-Djava.security.manager
|Enables the security manager

|

-Djava.security.policy=<jvm_policy_file>
|Defines the global policy file to be applied to the whole application, including the engine

|

-Dkie.security.policy=<kie_policy_file>
|Defines the policy file to be applied to rules and processes
|===

For instance:

`java -Djava.security.manager -Djava.security.policy=global.policy -Dkie.security.policy=rules.policy
        foo.bar.MyApp`



[NOTE]
====
When executing the engine inside a container, use your container's documentation to find out how to configure the Security Manager and how to define the global security policy.
Define the kie security policy as described above and set the `kie.security.policy` system property in order to configure the engine to use it.
====

[NOTE]
====
Please note that unless a Security Manager is configured, the `kie.security.policy` will be ignored.
====

[NOTE]
====
A Security Manager has a high performance impact in the JVM.
Applications with strict performance requirements are strongly discouraged of using a Security Manager.
An alternative is the use of other security procedures like the auditing of rules/processes before testing and deployment to prevent malicious code from being deployed to the environment.
====
