Question 1

Can I use two-factor (2FA) / multi-factor authentication (MFA) to secure my MyMalcolm account?

Accepted Answer

You can secure your MyMalcolm user account using two-factor authentication (2FA). To use this feature you will need a native MyMalcolm user account, that is you are not using Sign In with Google.

To turn 2FA on click the "Enable two-factor authentication" button in the Security tab of your profile. To access your profile click your name at the top of the screen where it says "Logged in as".

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/iermJcbNuB/screenshot-my.malcolm.app-2023.04.14-15_38_30.png (Enabling two-factor authentication in MyMalcolm)

You will then be shown a QR code you can scan in your choice of authenticator app. Alternatively there is also an option to be given a text code to enter into your authenticator app.

On the next screen, having added Malcolm! to your authenticator app, you will be asked to type in the current code. Once that code is accepted, as the final step of the process, you will be given some recovery codes which you should store safely and can be used to access your Malcolm! account if you are ever unable to use your authenticator app.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/6pXAu1iddP/screenshot-my.malcolm.app-2023.04.14-15_54_29.png (Recovery codes in MyMalcolm two-factor authentication setup)

Please note that if you lose access to your authenticator app and your recovery codes we will be unable to restore access to your account!

Question 2

What are Webhooks and how do I use them to receive notifications when Workflows are completed?

Accepted Answer

Webhooks allow you to set up your own integrations to Malcolm! Workflow.

Webhooks are endpoints on web servers you own. Whenever a Workflow is completed the configured Webhooks will be notified. The Payload will contain the completed Workflow Session, related Workflow and (optionally) the submitted Workflow Values.

Configuration

Webhooks are are configured in "Workflows > Edit > Configure > Webhooks" section of MyMalcolm.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/IWqLLH7kgn/Screenshot%202021-01-26%20at%2016.17.46.png (Screenshot 2021-01-26 at 16.17.46.png)

Webhook URL

The only requirement is to provide the URL of your Webhook. This is the URL Malcolm! will send the Payload to.

The URL should be a secure endpoint which means it should start with https://, although we do support http:// too. The endpoint should also be accessible which means hosted on a remote machine, not behind a firewall and not requiring Authentication.

Include the Workflow Values

There is an additional option to include the submitted Workflow Values in the Payload. This option is disabled by default for security reasons but available to use should you wish to enable it. By enabling the option you agree to the following terms -

(a) I would like the Workflow Values included in the Webhook Payload (b) the recieving web server is private and properly secured (c) I am aware the use of Webhooks can facilitate the transfer of end-user personal data to third party Data Processors and my use of Webhooks adheres to my responsibilities as Data Controller under applicable Data Protection Laws.

Secure your Webhook with a secret token

Webhook URLs can be called by anyone and are therefore insecure.

To ensure a request to your Webhook URL comes from Malcolm! a secret token known only by yourself and Malcolm! can be used to generate a Signature.

Malcolm! will take the Payload and the secret and create a Signature. This will be passed to your App as the request header X-Signature. Your App will use the same secret and the received Payload to generate a second Signature. If the Signatures match you know the request came from Malcolm! and not another source.

The secret token can be any string you like, but Malcolm! recommends using a random string of at least 36 characters. For example in a Terminal window run -

To validate the Payload from Malcolm! use the HMAC SHA-256 algorithm to create a hash using the Payload as the data and your secret as the key.

For example in PHP use the hash_hmac function to generate a binary hash.

Next encode the binary hash using a Base 64 encoder, in PHP this is the base64_encode function.

Finally prefix the encoded hash with "sha256=" and compare with the value of X-Signature. In PHP you can use the $_SERVER variable to access the headers.

Conditional settings

There are conditional controls available too. If you have a condition configured the Webhook will only be notified if the conditions at the end of the Workflow are satisfied.

Headers

The HTTP POST will contain the following Headers.

Payload

The Payload will be a JSON Body containing the Workflow Session.

Workflows are defined as -

Workflow Values are defined as -

Workflow Fields are defined as -

Example

Question 3

Can I pass secure values into Malcolm! Workflows via the URL?

Accepted Answer

Passing data into a Workflow via the URL is a feature we've had for a while - read more - but what if the data you want to pass is confidential?

Understandably, you wouldn't want to pass that straight in. Luckily Malcolm! understands how important protecting your data is so we've come up with a solution that allows values to travel safe and secure with minimal effort!

A beginners guide to encryption

Suppose you have a value, such as an account number, that you don't want anyone else to read. Encryption provides a way to scramble this value so only you and the people you share the password or secret key with can read it.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/FR8yDloV2d/encryption-diagram.png (encryption-diagram.png)

The sender uses the secret key to scramble the original value and the encrypted value is sent to the receiver. On receipt of the encrypted value the receiver uses the same secret key to unscramble the value back to the original.

And that's encryption in a nutshell!

Step 1: Generate a secret key

The secret key can be any string you like, but Malcolm! recommends using a random string of at least 36 characters. A simple ruby command can quickly generate one for you.

Keep your secret key safe - you'll need it later!

Step 2: Share your secret key with Malcolm!

We do this via the Workflow Builder. Any question field that supports URL query values can now be secured with your secret key - e.g. text fields, hidden fields, number fields, email address fields, etc.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/g6hGpX1dvl/Screenshot%202021-11-10%20at%2013.43.37.png (Screenshot 2021-11-10 at 13.43.37.png)

Here's a simple example which starts with a text field renamed to "Account number".

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/b4uJV41azB/Screenshot%202021-11-10%20at%2013.51.53.png (Screenshot 2021-11-10 at 13.51.53.png)

To enable URL values open up the edit window, scroll to the bottom and turn on "Allow a value to be set in URL query". Malcolm! will automatically generate a query name for you but you can change it to something different if you prefer.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/7OhxX21Mdq/Screenshot%202021-11-10%20at%2013.52.01.png (Screenshot 2021-11-10 at 13.52.01.png)

Next turn on the "Secure the query value" and paste in your secret key.

Hit save and that completes the configuration!

Step 3: Encrypting values

Malcolm! uses OpenSSL and the "aes-128-gcm" cipher to decrypt values.

Passed values need to be encoded and made up of three parts -

The Initialisation Vector used during the encryption
The Authentication Tag resulting from AEAD ciphers
The encrypted string

Initialisation Vectors are generated using the OpenSSL rand function. For our chosen cipher these need to be exactly 12 bytes long. If using PHP you can use the openssl_random_pseudo_bytes function.

Why 12 bytes? This just happens to be the required length for our chosen cipher. In PHP you can verify this by using the openssl_cipher_iv_length function.

This will output -

Next use the OpenSSL enc function to create the encrypted string. Here's an example using the PHP openssl_encrypt function.

This will assign an Authentication Tag to the $tag variable (passed by reference) and an encrypted string to the $ciphertext variable.

Note - in PHP we pass OPENSSL_RAW_DATA to generate binary data.

Complete the process by concatenating $iv, $tag and $cipertext into a single string - Malcolm! needs all three for the decryption process!

As we're passing this value via the URL we need to first encode it. Use a Base 64 encoder followed by a URL encoder to ensure all the characters are sent correctly. In PHP this is the base64_encode function and urlencode functions respectively.

This is the final encoded string!

For simplicity all the steps from above can be put in a single function.

And that's all there is to it ;)

Question 4

How is the removal of Company Personal Data handled?

Accepted Answer

What is personal data?

Personal data only includes information relating to natural persons who:

can be identified or who are identifiable, directly from the information in question; or
who can be indirectly identified from that information in combination with other information.

What is Company Personal Data?

When you use Malcolm! to collect information from your customers, suppliers, staff or others that information may include personal data. In this context, Malcolm! acts as your data processor and the personal data we may process on your behalf is referred to as Company Personal Data. You can read more about this here.

Removal of Company Personal Data

There are two tiers of data removal. The first is a recoverable delete, known also as a soft delete. The second is a permanent delete or purge. Malcolm! supports both types of data deletion.

Soft deletion

Soft deletion means data is deleted enough to make it no longer visible or discoverable but not quite enough should it need to be recovered.

For example if you delete a Malcolm! Workflow in MyMalcolm then the Workflow and everything related to that Workflow is soft deleted. This means it'll all disappear from MyMalcolm and our APIs but should you realise the deletion was a mistake it could still be fully recovered (on request).

Purging

Purging is a permanent or secure delete. This could be either a physical delete (e.g. uploaded files on disk) or a nullification of stored values in a database. Once data has been purged it is no longer recoverable.

Rest assured, Malcolm! will never purge your data whilst your Instance is active!

What happens after my trial finishes?

After your 14 day trial period comes to an end your Instance will be disabled. From that point you'll have 30 days to subscribe to one of the plans. If no subscription is in place by then your Instance data will be soft deleted and after 120 days all Company Personal Data will be purged in accordance with our Data Processing Addendum.

What happens if my subscription lapses?

Subscriptions could lapse for a number of reasons but the most likely cause is an expired credit card. We'll keep you Instance active for 14 days to give you time to fix the problem.

If the problem is not fixed your Instance will be disabled but you'll still have a further 30 days to subscribe to a new plan should you wish to. If no subscription is in place by then your Instance data will be soft deleted and after 120 days all Company Personal Data will be purged in accordance with our Data Processing Addendum.

What happens after I delete my Instance?

You can request to have your Instance deleted and purged in Settings > Instance > Delete Instance. After 30 minutes of requesting the deletion your Instance data will be soft deleted and after 120 days all Company Personal Data will be purged in accordance with our Data Processing Addendum.

Can I request just a Workflow data delete and purge?

Yes you can! Within MyMalcolm you can create a Workflow data deletion request. The Workflow data will be first be soft deleted and then 30 days later it will be purged.

See How do I delete data submitted to a Workflow? for more information.

For more information...

For more information please read the Data Processing Addendum.

Can I use two-factor (2FA) / multi-factor authentication (MFA) to secure my MyMalcolm account?

What are Webhooks and how do I use them to receive notifications when Workflows are completed?

Can I pass secure values into Malcolm! Workflows via the URL?

How is the removal of Company Personal Data handled?

Upgrade your content

Hey there!