Security
Introduction
The previous section was about fine-tuning the Frank!Framework. You learned about the DTAP stage and about setting properties. This section continues about fine-tuning the Frank!Framework. You will learn how to restrict access to the Frank!Console. On your production environment this is important, because you want to protect the integrity of your data and you do not want unauthorized users to read customer data.
When you use Apache Tomcat as your application server, you configure security by editing the Apache Tomcat configuration files. You do not need a manual deployment of Apache Tomcat to practice. Instead you will use the Frank!Runner which installs Apache Tomcat automatically, and then you will change the Apache Tomcat files manually. Please do not take this approach for your production environment. The Frank!Runner sometimes overwrites your security edits.
Tutorial on setting up security
Please set up security as follows:
We recommend that you create a new directory to do this section. You are going to tweak files managed by the Frank!Runner. and you do not want your existing configurations to break. Let us call your directory
security
.On a command prompt, please change directory to
security
and clone the Frank!Framework as follows:security> git clone https://github.com/ibissource/frank-runner
You can work with the example configurations of the Frank!Framework, so you do not need
build.properties
. Please change directory to your Frank!Runner checkout and start the Frank!Framework as follows:security\frank-runner> start.bat
The Frank!Runner will download Apache Tomcat and the Frank!Framework. If you are using Windows, it will create a new command window to start Apache Tomcat. When you see the message
INFO: Server startup in <n> ms
with<n>
some number, then press ctrl-c to stop the Frank!Runner again. You need to do this in the new command window. Alternatively, you can runstop.bat
in the original command window.Please check that you have the following directory structure:
security |- frank-runner |- build.xml |- start.bat |- stop.bat |- examples |- build |- apache-ant-1.10.7 |- apache-tomcat-7.0.100 |- h2 |- openjdk-8u232-b09 |- tmp ...
The file build.xml
is an ANT script that is used by start.bat
to start the Frank!Framewok. By changing build.xml
, you can control the version of the Frank!Framework you are using. By default, you always use the latest version. The examples
directory contains Frank configs that you can use out-of-the-box. You are using them because you did not provide build.properties
. In the directory build
, you see a subdirectory apache-tomcat-7.0.100
with your Apache Tomcat installation.
Warning
When you are reading this, you may be using later versions of Apache Ant, Apache Tomcat and the JDK. The directory names will be slightly different in this case. Please check the directory names you have. Use your directory names instead of the directory names you see in the reminder of this section.
Please open file
security\frank-runner\build\apache-tomcat-7.0.100\webapps\ROOT\WEB-INF\web.xml
in a text editor. Scroll down until you see the following:<!-- When a security-constraint element is present Tomcat will autenticate the user for all url's whereas WebSphere does this only for the url's mentioned in the security constraint(s). The PublicAccess security constraint will make Tomcat behave the same as WebSphere. --> <!-- security-constraint> <web-resource-collection> ... </security-constraint -->
Uncomment the
security-constraint
, resulting in:<!-- When a security-constraint element is present Tomcat will autenticate the user for all url's whereas WebSphere does this only for the url's mentioned in the security constraint(s). The PublicAccess security constraint will make Tomcat behave the same as WebSphere. --> <security-constraint> <web-resource-collection> ...
At the bottom, uncomment the closing tag to arrive at:
<role-name>IbisTester</role-name> </security-role> </web-app>
Close the file you edited,
web.xml
Open file
security\frank-runner\build\apache-tomcat-7.0.100\conf\tomcat-users.xml
.The file has a lot of comments. The only non-commentary tags are the opening
<tomcat-users>
and the closing</tomcat-users>
. Between them, add a new user. Please insert the following XML:<user username="frank" password="frank" roles="IbisObserver"/>
You create a user with username
frank
and passwordfrank
. This user gets roleIbisObserver
. The possibilities for the roles will be explained later in this page.
With security enabled, users should connect to your Apache Tomcat server through https. You need a dummy certificate for this and you need to enable https traffic in your server.xml
file. Please do the following:
To create the dummy certificate, change directory to
security\frank-runner\build\openjdk-8u232-b09\bin
. Execute the following command there:security\frank-runner\build\openjdk-8u232-b09\bin> keytool -genkey -alias tomcat -keyalg RSA
To enable https, edit
security\frank-runner\build\apache-tomcat-7.0.100\conf\server.xml
. Uncomment the following piece:<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />
Now you can start the Frank!Runner.
Please change directory to
security\frank-runner
and executestart.bat
.Browse to http://localhost.
Your browser shows a message that your site is not secure. This is true, because your certificate was not signed by a Certificate Authority. For your production environment, you need a real certificate from a Certificate Authority. Every browser hides an option to carry on nevertheless. Apply this option to continue.
A dialog appears asking you to login, see below:
Enter username
frank
and passwordfrank
, the credentials you configured intomcat-users.xml
. You should now see the Frank!Framework as shown below. You see an error that something is wrong with your security certificate, but you do enter the Frank!Console.In the main menu, click “Testing” to expand it (number 1 in the figure below):
Click “Test Pipeline” (number 2). You see the page shown below:
Select adapter “Example1Adapter” (number 1). Enter some dummy text in the Message field (number 2). Press “Send” (number 3).
To the top-right, the following message appears:
This message will normally be removed in about five seconds. You can see it longer by hovering over it.
Warning
Restricting access to the Frank!Console is not sufficient in itself to implement security. You also need to restrict access to your Apache Tomcat configuration and installation files, and you need to restrict access to your Apache Tomcat server. If you have an external database, you also have to implement security on that. All this is beyond the scope of the Frank!Manual.
Overview of security roles
With the above tutorial, you learned how security is configured. Now we explain what options you have to restrict access to the Frank!Console. Your options follow from the roles that are defined within the Frank!Framework. See the following list:
- IbisWebService
Can call an Ibis WebserviceListener.
- IbisObserver
Can look in configurations, statistics and log files.
- IbisDataAdmin
Can browse message logs, message stores and error stores, see section Processed Messages. Can resend or delete the messages in them. Can reload configurations and start and stop adapters. Has all IbisObserver permissions too.
- IbisAdmin
Can do a full reload and has all IbisDataAdmin permissions.
- IbisTester
Can execute jdbc query, send jms message, test a service and test a pipeline, has all IbisAdmin and IbisWebService permissions too.
Note
“What is ‘Ibis’?”, you might ask. WeAreFrank! used this brand before they acquired their name. Before, the company was called “Integration Partners”. In that time, they used the brands “Ibis” and “Ibis Adapter Framework”. These names have not all been replaced by their Frank! equivalents.
You can assign these roles to users, as you did when you edited tomcat-users.xml
. You assign a value to the roles
attribute that is a comma-separated list of roles. Each role should be taken from the list.