Mule – Credentials – Vault

Robert Whitmer

REVIEW

There is an age old question that people often ask; what is the single most valuable thing to society? Some of the top responses may be things like gold, silver, and money. Personally I believe that in the 21^st century the correct answer is information. Just as the gold in Fort Knox is protected and secured we must do the same with our sensitive data to keep it from falling into the wrong hands. The next question becomes how do we protect and store our sensitive data? The answer is encryption and MULE offers us a great way of encrypting and storing our data securely by using the MULE-Credentials-Vault. The MULE-Credentials-Vault is very flexible and offers us 19 different encryption algorithms by default!

REQUIREMENTS

To correctly secure a .properties file using MULE the following requirements must be meet:

• The Use Of A MULE-Credentials-Vault (an encrypted .properties files)
• A Global Security Property Placeholder Element
• An Encryption Key For Opening The Vault

HOW IT WORKS

When implementing the use of the MULE-Credentials-Vault our sensitive data such as user names and passwords are stored as key value pairs inside of a .properties file. Once a .properties file becomes encrypted the file is then referred to as a Credentials Vault. After a Credentials Vault has been implemented MULE uses a Secure Properties Placeholder (Global Element) to point to our Credentials Vault, decrypt the stored data, and return the stored data (only if it has the correct key to the vault). This process can be thought about in the same way as using a key to open your front door to your house to allow entry. The KEY to a MULE-Credentials-Vault gets stored in a user’s runtime memory (it is never written or stored to disk). KEY credentials are prompted and gathered when a MULE application starts. The KEY is then stored in memory for the complete lifecycle of the application. Once the applications session has ended the KEY is then cleared from memory and is thus forgotten.

WALKTHROUGH

Before we can begin to utilize the MULE-Credentials-Vault we first must have installed Anypoint Enterprise Security for Anypoint Studio. Start by opening your project application in Anypoint Studio.

• From the file menu bar select:
  • Help > Install New Software…

• Install the software shown above
  • The latest version and update site can be found at https://docs.mulesoft.com/release-notes/anypoint-enterprise-security-release-notes

• Anypoint Enterprise Security for Anypoint Studio will then begin to install.

• After the Anypoint Enterprise Security for Anypoint Studio process completes restart Anypoint Studio

• Next we must create a .properties file that will later become our Credentials Vault by:
  • (R-Click) src/main/resources > New > File from the Package Explorer

• Open the newly created .properties file with the Mule Properties Editor
  • (R-Click) *.properties file* > Open With > Other from the Project Explorer
    • Select Mule Properties Editor
      
• After opening the Mule Properties Editor :
  • (L-Click) Add Properties Button
  • Input field values:
    • Key
    • Value
  • (L-Click) Encrypt
    • Select your Encryption Algorithm & Key
• Your value will then be encrypted
  
  

• Next we must create our Secure Property Placeholder Global Element

• The Secure Property Placeholder Global Element is configured as show in the image above

FORCE MULE RUNTIME KEY

Once ready to move your application into production configure MULE to demand that a user enter a password key at runtime, you need to include the following in the system properties (the mule-app.properties file in the src/main/app folder)

• M-Dprod.key=uniquepassword -M-Denv=prod

• For development purposes the src/main/app/mule-app.properties file can be configured as shown above

RELATIONSHIP STRUCTURE

As previously stated there are 3 requirements that must be meeting to properly secure our sensitive data. There are many varieties these key ingredients based upon the use case of your application can be structured.  Typically an application will use one of three ways. The structure can be thought about in the exact same as a MySQL database table relationship. The relationships are as followed:

• ONE to ONE to ONE Relationship

• ONE to ONE to MANY Relationship

• (MANY) ONE to ONE to ONE Relationship
  

AP Studio Documentation Generation

Mark J. Norton

**This blog post has been updated. For an updated version of AP Studio Documentation blog post, please click here**

Documentation is something most programmers would willingly avoid given even the smallest chance.  Most see it as a distraction from what they do, which is write code.  If asked directly, however, programmers will usually admit the importance of documentation for the client, for team members, for those who follow and even (whisper it) themselves.  With a very little bit of extra effort, however, MuleSoft developers can take advantage of the built in documentation generation in AnyPoint Studio.

The concept of documentation embedded in code has been around for quite some time.  Since MuleSoft uses Java extensively in developing their own products, most MuleSoft developers are familiar with JavaDoc, a documentation generation utility introduced in 1995 (https://en.wikipedia.org/wiki/Javadoc).  JavaDoc generates high quality documentation for Java interfaces, classes, and objects formatted as a set of HTML pages.

MuleSoft AnyPoint Studio provides documentation generation in a similar manner.  Once code is complete, select the AP Studio project and use the file menu to select Export Studio Documentation.

You will be prompted for a location to save the results.  To illustrate the results, a simplistic application was created with three elements:  an HTTP listener, a database request, and a data formatter, which is included in the illustration above.

The result is an index.html page that looks like this:

All flows are listed on the left.  There is only a single flow in this example, but if there were more, they would be included here.

At the top right,  a graphical representation of the example flow is shown, the same one you would see in AP Studio. Each element is then broken out below for further detail.  Section 1 in the blue box shows one of these elements, a database operation that fetches records based on a simple query.  The element is labeled as part of the “get_persons_Flow”, along with the label specified by the developer, “All Persons” in this case.  Note the text at the bottom of the section that reads “To protect privacy …”.  This information was added by the developer using the Notes tab of the element in AP Studio:

This is very similar to the annotations supported by JavaDoc that allows additional information to be included in the code to further clarify the documentation generated later.

Element in the documentation includes a clickable link that reveals the XML associated with it.

This also illustrates how the description note is included in the XML definitions.

Overall, the results are clean and professional looking.  While all of the important information is included, there is room for improvement.  For example, error handling does not have any documentation generated, though it can be viewed by viewing the whole flow XML.  I would love to see additional resources included, even if just as a list.  These could include POM files, schemas, API definitions, property files, etc.  Finally, there should be an option to generate for specifically for PDF so that it can be printed and/or distributed.  Fields can be expanded manually and the page printed to PDF, but these extra steps shouldn’t be needed.

While not perfect, documentation generated by AP Studio is a quick and easy solution for documentation required by a client.  A little descriptive work by the developer results in a doc set that describes the application, how it is broken down, and (roughly) how it works.

Database Connection Check

Mark J. Norton

I was recently given the task to create a uniform approach to checking the status of all running applications.  These checks use an HTTP listener to provide status information back to the caller. Currently, this information is returned in JSON format, but a shared formatter flow is called to provide a global method to transform it into another form, such as HTML.

The basic application check information includes a timestamp, the name of the application, what host, port, and cluster id it is running on, etc.  Additionally, checks are made for the status of any third party resources being used, such as a database, a REST or WSDL service, message queue, or others.  In particular, I’d like to share how the database connection check works.

The usual way to check to see if a particular database connection is up and running is to run a query against it.  Perhaps something like this:

<db:select config-ref=”MySQL_Configuration” doc:name=”Database”>

            <db:parameterized-query>

                          <![CDATA[select sysdate();]]>

            </db:parameterized-query>

</db:select>

If the connection is down, an exception is thrown that can be caught and status rendered appropriately.  However, there are times when this approach will fail even though the connection is up and running.  Databases containing sensitive information, such as those protected by HIPAA, may disallow select operations.  A more general approach can be developed by accessing the database connector object directly.

The simplest way to access the database connector object directly is to define it as a bean in a Mule global configuration file or a domain configuration file.

<spring:beans>

   <spring:bean id=”Connector” name=”conName”

                    class=”org.apache.commons.dbcp2.BasicDataSource”>

         <spring:property name=”driverClassName”    

                   value=”oracle.jdbc.driver.OracleDriver” />

         <spring:property name=”url” value=”${db.url}” />

         <spring:property name=”username” value=”${db.username}” />

         <spring:property name=”password” value=”${db.password}” />

   </spring:bean>

</spring:beans>

Once the bean is defined, we can access existing methods such as isClosed() to determine if the connection is open or closed.  An active database connection must be open to be used.  This example shows how to capture the database connector status using a MEL statement.

<set-variable doc:name=”isClosed”

value=”#[app.registry.conName.getConnection().isClosed() ? ‘Down’ : ‘Up’]”

variableName=”isClosed”/>

Depending on the database driver you are using, the method name might be slightly different.  Still, this is a more reliable and consistent way to determine if a database connection is viable