Signed deployment

Signed deployment is a mechanism that provides two-way verification of a deployment (an instance of an application). Applications and websites embedding the application can already verify the authenticity of the deployment by the usual web mechanisms: the SSL/TLS certificate is valid and the URL the application is deployed on is on the expected domain.

Secure deployments allow verification in the other direction. It allows the application server to verify that the application or website is allowed to embed the application.

What is encrypted data passporting?

The signed_deployment property is an encoded string that contains a serialised signed JWS message. A JWS message contains both the payload (the properties normally passed to mmob.init()) and the digital signature that verifies that the message is valid.

Properties passed via the signed_deployment property take percedence over properties passed directly to mmob.init(). As such, the properties passed via signed_deployment need not be passed again to mmob.init().

The following properties must be passed via signed_deployment if the signed deployment feature is enabled:

• deployer_id
• integration_id

The following properties must be passed via signed_deployment is the signed deployment feature is enabled and the property is in use. If a property is not needed it may be omitted from signed_deployment:

• data_passport
• encrypted_passport
• uid

The following property may be passed via signed_deployment but may also be omitted and passed directly to mmob.init() (it is however highly encouraged to include as many properties into signed_deployment as possible):

• owner_id

The following property that must not be passed to signed_deployment and must be passed directly to mmob.init():

• location

Example use case

Imagine you have created a credit rating report application and want to allow a client to embed it into their website. Because the service handles potentially sensitive data you do not want to allow other 3rd parties to embed it into their unauthorised websites or applications.

Using signed_deployment, you can ensure that only your client who posess the correct signing key can embed your application.

How signed deployment works

Snippet generation and placeholder values

Except for location. All the properties normally passed to mmob.init() should be signed using JSON Web Signature (JWS).

Example generated snippet

mmob.init({
  deployer_id: "your-deployer-id",
  integration_id: "your-integration-id",
  location: "#app-container",
  owner_id: "your-owner-id",
  uid: "user-123456",
  data_passport: {
	first_name: "{{YOUR-VALUE}}",
	last_name: "{{YOUR-VALUE}}",
	card_number: "{{YOUR-VALUE}}"
  },
});

In this case we need to pass all the values except location to signed_deployment:

mmob.init({
  location: "#app-container",
  signed_deployment: "{{SIGNED-VALUE}}"
});

Generating signed deployment value

The signed value must be generated on the server, not on the client. The reason for this is to prevent either sensitive data or the encryption key from being exposed to the internet.

The data to be signed should be stringified as JSON and then signed with JWS using the following configuration:

• alg (key encryption algorithm): ES512

All other headers should not be set.

The following is an example of generating the signed value in javascript (node.js) using the jose library:

import * as jose from 'jose';

async function generateJWS (body, privateKey) {
	const parsedKey = JSON.parse(privateKey);
	const key = await jose.importJWK(parsedKey);

	const signedData = await new jose.CompactSign(
		new TextEncoder().encode(JSON.stringify(body))
	)
	.setProtectedHeader({
		alg: 'ES512'
	})
	.sign(key);

	return signedData;
}