Skip to content

Using Mendix Apps in MindSphere

This documentation is meant for Mendix developers who want to deploy a Mendix app to the MindSphere platform.

Developing the Mendix App

Mendix apps must include specific modules and adhere to MindSphere styling to be deployed to MindSphere.

Use the MindSphere Starter App when developing a new Mendix app for MindSphere. This contains all building blocks required for deploying apps to MindSphere. All you need to do is to configure the CockpitApplicationName constant of the SSO module and optionally the App Information. The MindSphere Starter App must be selected when setting up a new project:

starting point

Alternatively, use the example appliation, which contains modules to call the MindSphere APIs, or integrate the MindSphere Theme Pack, the SSO module and the OS Bar module into an existing app.

Integrating the MindSphere Theme Pack

The MindSphere Theme Pack adjusts the styling of Mendix apps for use in MindSphere. Integrate it using the following steps:

  1. Open the App Store in the Mendix Desktop Modeler.
  2. Search for "MindSphere Theme Pack" and open the module details.
  3. Click Download.
  4. Click Import.

The module imports the following components:

Customizing the index.html

The MindSphere Theme Pack customizes the standard Mendix index.html file, which is located in the /theme folder of your app project: The login URI is adjusted to support Single Sign-on via MindSphere login and two scripts are added to make the MindSphere OS Bar work correctly, and to provide an XSRF token when sending requests to MindSphere.

The /theme folder is only accessible by checking out the app project locally.

Click here to display the index.html customizations
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!-- the following script is added within the `<head>` tags -->
<script>
// MindSphere specific part-1: OS Bar related code
(function(d1, script1) {
  script1 = d1.createElement('script');
  script1.type = 'text/javascript';
  script1.async = true;
  script1.onload = function() {
    _mdsp.init({
      appId : 'content',
      appInfoPath : "/rest/os-bar/v1/config",
      initialize : true
    });

// make sure that the mxui.js is loaded after osbar/v4/js/main.min.js to prevent problems with the height calculation of some elements
    (function(d2, script2) {
      script2 = d2.createElement('script');
      script2.src = 'mxclientsystem/mxui/mxui.js?{{cachebust}}';
      script2.async = true;
      d2.getElementsByTagName('body')[0].appendChild(script2);
    }(document));
  };
  script1.src = 'https://static.eu1.mindsphere.io/osbar/v4/js/main.min.js';
  d1.getElementsByTagName('head')[0].appendChild(script1);
}(document));
// MindSphere specific part-1: ends
</script>
1
2
3
4
5
6
7
8
9
<!-- The mindspherelogin.html file is used instead of the standard Mendix login, replacing the following lines

if (!document.cookie || !document.cookie.match(/(^|;)originURI=/gi))
      document.cookie = "originURI=/login.html";

with these lines: -->

if (!document.cookie || !document.cookie.match(/(^|;)originURI=/gi))
      document.cookie = "originURI=/mindspherelogin.html";
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
<!-- The following script is added to provide an XSRF token in the header of each request

<script src="mxclientsystem/mxui/mxui.js?{{cachebust}}"></script>
-->

<script>
    // Mindsphere specific: Use the XSRF-TOKEN on fetch requests.

    (function() {
        // Read cookie
        function getCookie(name) {
            match = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'));
            if (match) return match[2]; else return "";
        }

        var xrsfToken = getCookie("XSRF-TOKEN");
        if (window.fetch) {
            var originalFetch = window.fetch;
            window.fetch = function(url, init) {
                if (!init) {
                    init = {};
                }
                if (!init.headers) {
                    init.headers = new Headers();
                }
                init.headers.set("x-xsrf-token", xrsfToken);
                return originalFetch(url, init);
            }
        }

        var originalXMLHttpRequest = window.XMLHttpRequest;
        window.XMLHttpRequest = function() {
            var result = new originalXMLHttpRequest(arguments);
            result.open = function() {
                originalXMLHttpRequest.prototype.open
                        .apply(this, arguments);
                this.setRequestHeader("x-xsrf-token", xrsfToken);
            }
            return result;
        };
    })();
</script>

Adding the MindSphere Login Page

The MindSphere Theme Pack includes a mindspherelogin.html file, which is added to the /theme folder of your app project. This file is required by the Single Sign-On for MindSphere.

Click here to display the mindspherelogin.html
1
2
3
4
5
6
7
8
9
<!doctype html>
<html>
    <head>
      <title>MindSphereLogin</title>
        <script>
            window.location.assign("/sso/")
        </script>
    </head>
</html>

Adding the Permission Denied Page

The MindSphere Theme Pack includes a permission denied page, which is stored at /theme/error_page/403.html inside your app project. This page is required by the Single Sign-On for MindSphere. It is displayed if your app is called with an invalid token or with a token which does not include permission for accessing your app.

Permission Denied

Integrating MindSphere Single Sign-On

The MindSphere SSO module enables Mendix apps to support MindSphere Single Sign-On (SSO). It allows logged in MindSphere users to access the app without another login. In addition, the SSO module enables developers to test their app locally by setting up a valid user context for interactions with MindSphere APIs. Integrate the MindSphere SSO module using the following steps:

  1. Open the App Store in the Mendix Desktop Modeler.
  2. Search for "MindSphere SSO" and open the module details.
  3. Click Download.
  4. Click Import.

The module will be listed in your project's "App Store modules".

Configuring the MindSphere Single Sign-On

  1. Double click on the CockpitApplicationName constant.

    SSO

  2. Enter the name of your app as it was (or will be) registered in MindSphere.

Single Sign-On Constants

The MindSphere SSO module includes three MindSphere constants, which are required for accessing MindSphere APIs.

Constant Description
CockpitApplicationName Stores the name of your app as registered in the MindSphere developer portal, refer to Running a Cloud Foundry-Hosted Application.
MindGateURL Stores the base URL of the MindSphere Gateway, which is required for all requests to MindSphere APIs. E.g.: https://gateway.eu1.mindsphere.io.
PublicKeyURL Stores the URL to the public key which enables token validation during the login process, e.g. https://core.piam.eu1.mindsphere.io/token_keys.

Single Sign-On Microflows

The MindSphere SSO module includes three microflows: The RegisterSingleSignOn is required for the SSO workflow. The DS_MindSphereAccessToken obtains and refreshes the token required for accessing MindSphere APIs. The DS_MindSphereAccount obtains the user’s tenant name and e-mail address and makes them accessible for the app.

SSO2

Click here for detailed information about the RegisterSingleSignOn microflow

This microflow is set to be performed after startup. It is configured in the "Runtime" tab of the project settings as shown below.

microflow

Click here for detailed information about the DS_MindSphereAccessToken microflow

The DS_MindSphereAccessToken microflow populates the MindSphereToken entity, which is used to call MindSphere APIs. Its Access_token attribute must be passed as the Authorization header in REST calls to MindSphere APIs. token

When running on MindSphere, this microflow retrieves the access token from the environment variables. If it cannot retrieve a valid token, an error is returned.
When running locally, this microflow asks the user to sign on by providing their MindSphere credentials manually. This enables developers to test the app without deploying it to MindSphere.

The java action GetAccessToken refreshes the MindSphereToken before each call to MindSphere APIs, because tokens expire after a short time.

Click here for detailed information about the DS_MindSphereAccount microflow

The DS_MindSphereAccount microflow populates the Name attribute of the Tenant entity and the Email attribute of the MindSphereAccount entity with the user's MindSphere account details. These entities are extensions to the Mendix user object. They are required for creating multi-tenant apps.

multi tenant

Integrating the MindSphere OS Bar

The MindSphere OS Bar Connector integrates the MindSphere OS Bar, which is mandatory for every MindSphere app. It connects all MindSphere apps on a UI level, displays app information as shown below, routes back to the Launchpad, and logs the user out of MindSphere. OS Bar

Integrate the MindSphere OS Bar Connector using the following steps:

  1. Open the App Store in the Mendix Desktop Modeler.
  2. Search for "MindSphere OS Bar Connector" and open the module details.
  3. Click Download.
  4. Click Import.

The module will be listed in your project's "App Store modules".

Configuring the App Information (optional)

The app information is displayed if the user clicks on the app name in the MindSphere OS Bar. Configure the app information by following the instructions below. OS Bar App Information

  1. Double-click the string constant Config of the MindSphereOSBarConfig module.
  2. Enter the app information as a JSON object into the "Default value" field: OSBarConfig

    For a description of the available configuration parameters and a sample JSON object, refer to the MindSphere OS Bar documentation.

Integrating the Mendix App into MindSphere

Prerequisites

Creating a Mendix Deployment Package

  1. Open the app in the Mendix Desktop Modeler.
  2. Select Project > Create Deployment Package... Create Deployment Package
  3. Select the desired Development line and Revision and set the version number.
  4. (Optional) Add a description and adjust the path for the deployment package if desired. By default, the deployment package is created in the releases folder of your project.
  5. Click OK.

The location of the new deployment package will be displayed in an information window.

Uploading the Mendix App to MindSphere

It is recommended to host Mendix apps on Cloud Foundry. Follow the instructions on Running a Cloud Foundry Application and make sure to bind a PostgreSQL instance to your app to host your app on Cloud Foundry and deploy it to MindSphere.

Content Security Policy

Set the following content security policy to ensure that the MindSphere OS Bar and the Mendix Feedback widget are loaded correctly:

1
default-src 'self' 'unsafe-inline' 'unsafe-eval' static.eu1.mindsphere.io sprintr.home.mendix.com; font-src 'self' static.eu1.mindsphere.io fonts.gstatic.com; style-src * 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval' static.eu1.mindsphere.io sprintr.home.mendix.com; img-src * data:;

Info

Mendix applications hosted outside MindSphere must provide a mechanism which handles user credentials for accessing MindSphere APIs.

Creating an App Manifest

The manifest.yml required for handing your app over to an operator can be generated automatically as follows:

  1. Log into the CF CLI and navigate into the correct organization and space.
  2. Create the manifest using the following command:

    1
    cf create-app-manifest {appName}
    

For more information on the configuration of manifest files, refer to this How To.

Development Considerations

App Name

There are no limitations on what you call your app within Mendix. However, when you deploy the app to MindSphere, the app name registered in the Developer Cockpit must adhere to the constraints for naming Cloud Foundry applications.

If you want to keep your names consistent, you should bear these constraints in mind when naming your Mendix app.

Local Testing

User Roles

Do not use the demo users when testing different roles in your app. This does not populate the tenant and role information in MindSphere correctly. Instead, allocate the role to MxAdmin, redeploy, and log in again.

Credentials

When running your app locally, you have to start your app as MxAdmin. The first time the SSO module attempts to retrieve an access token, you are presented with a login screen as shown below.

Login Screen

The Client ID and Client Secret are app credentials, which are issued using the MindSphere Developer Cockpit as follows:

  1. Register the application and make sure the application name is equals the constant CockpitApplicationName.
  2. Open the Developer Cockpit.
  3. Navigate to the App Credentials page in the Authorization Management tab.
  4. Click Issue access to obtain a token.

    Issue Access

  5. Select the access level and click Submit.

    Access Level

  6. Make a note of the Client ID and Client Secret.

    Credentials

To ensure that the correct application credentials are requested, you have to set the following constants in the LocalDevelopment folder of the MindSphereSingleSignOn module.

Constants

Constant Description
CockpitApplicationVersion This is a valid version of the MindSphere app as registered in the Developer Cockpit under the name CockpitApplicationName.
HostTenant Specifies the name of the tenant where the app has been registered and the service credentials have been issued. It is displayed in the MindSphere OS Bar.
Host Tenant
UserTenant Specifies the name of the tenant who uses the app. If the app is registered on a developer tenant, this must be the same as above. If the app is registered on an operator tenant, you can enter a different tenant who has been granted access to the application to test multi-tenancy.

Multi-Tenancy

MindSphere apps are usually designed to be multi-tenant compatible, meaning that a single instance of the app serves multiple tenants. Access to tenant specific data is controlled by the MindSphere's Identity and Access Management.

Access Control by MindSphere Gateway

A authorization HTTP header is passed in every MindSphere API call. The MindSphere Gateway verifies that the user has permission to obtain the requested data.

Control within a Mendix App

Mendix apps support persistent entities which can be accessed by all users (subject to access granted by their user role). Thus, an additional access control is required to make Mendix apps compatible with the multi-tenant concept in MindSphere. The following instructions explain how to use the tenant name provided by the MindSphere SSO module to enable multi-tenancy in Mendix apps.

  1. Make all persistent persistent entities which have a TenantId attribute a specialization of the MindSphereSingleSignOn.TenantObject entity.
    This ensures that they are associated with the user's tenant.
  2. Every action on this object must have the following XPath constraint:
    [MindSphereSingleSignOn.TenantObject_Tenant/MindSphereSingleSignOn.Tenant/MindSphereSingleSignOn.MindSphereAccount_Tenant='[%CurrentUser%]']
    This ensures that the user can only access tenant specific entities with their tenantId.

Tip

For consistency, it is recommended to always access persistent entities with a TenantId attribute using a sub-microflow which contains the XPath constraint. This enforces multi-tenant security.

Info

Currently, it is not possible to apply these access restrictions automatically.
They are only required for persistent entities which have a TenantId attribute.

Example

You have some assets that you need to store persistently in the database. You then want to get a list of all your assets.

  1. Create the domain model with the Asset entity being a specialization of MindSphereSingleSignOn.TenantObject. create domain model
  2. Implement a sub-microflow which returns a list of all assets.
  3. Apply the XPath constraint to the Retrieve Objects action of the microflow. access token
  4. When you want to retrieve the list of assets, call this microflow instead of using the retrieve objects action. This ensures that tenant-based security is applied.

Cloud Foundry Environment variables

You can only set or change the value of Cloud Foundry environment variables using the CF CLI.

  1. Use cf set-env {appName} {environmentVariableName} {value}
  2. Restart the app to apply the new value using cf restart {appName}

Info

Restarting your app will cause it to be temporarily unavailable.

Validation

Your app must at least meet the requirements listed at Get your Application Ready for Productive Use.

Local User Passwords

Do not create local users for your MindSphere app.

When a new user is identified during SSO, the SSO process generates a random password of a fixed length for the user. The password policy for your app must accept these passwords.

Password Policy

This policy is set up as the default in the MindSphere starter and example apps and should not be changed.

Roles and Scopes

When a user opens your Mendix app in MindSphere, the SSO module automatically assigns them their Mendix user roles. This makes the user's access permissions available to the app.

The SSO module reads the user token and maps the application scopes to Mendix user roles during the login process. The mapping is done by a case-insensitive comparison of the scope and role names. For example, an application scope {appName}.customScope1 the user would be assigned the Mendix roles CUSTOMscope1 and/or customscope1.

In the starter app the Mendix user roles Admin and User are preconfigured.

multi tenant2

In MindSphere the application scopes should be defined as shown below:

multi tenant

Limitations

The following limitations apply to Mendix apps which are deployed to MindSphere.

If these limitations affect the design of your app, you can still create a Mendix app to use MindSphere APIs from outside MindSphere. However, you cannot easily integrate it into the MindSphere launchpad or use single sign-on.

Binary File Storage

MindSphere does not currently have a compatible file service available to its Cloud Foundry stack. Therefore, you cannot use any Mendix features which rely on having a file service. This means that you cannot any specializations of the System.FileDocument entity, which includes all specializations of the System.Image entity.

You can store small amounts of binary information in persistable entities. However, the database management system has strict limits on the size of binary attributes and using them as a replacement for FileDocument entities can lead to performance issues.

Roles and Scopes

MindSphere currently only supports two roles. This should be taken into account when designing security within your Mendix app.

Logout from MindSphere

When the user logs out from MindSphere, the Mendix app will not delete the session cookie. If another user reopens the app in the same browser on the same computer before the cookie has expired, the session from the previous user is picked up.

Logout

Cloud Services Platform

Mendix apps can currently only be deployed to MindSphere in region Europe 1.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.