Overview

The Mendix Cloud Client Certificate Verification module uses request headers inserted by the Mendix Cloud to verify whether the certificate provided by the end-user is registered, linked to the user entity in the app, and allowed to be used. The end-user is only allowed to continue if all those requirements are met. If one of these requirements is not met, the request is blocked.

Documentation

• Client requests coming from the browser to the Mendix app
  • Although the the module will most likely work correctly with native mobile logins, the module has not been designed or tested to work with native mobile apps
• REST requests made to a published REST service
• OData requests made to a published OData service
• Web service requests made to a published web service

• Nanoflow Commons module
• Must be deployed in the Mendix Cloud

1. Import the Mendix Cloud Client Certificate Verification Module into your app.
2. Add the Administrator module role of the Mendix Cloud Client Certificate Verification Module to a user role in your app, if needed. End-users with a user role including the Administrator module role are allowed to view, add, edit and delete registered client certificates through the UI.
3. Add the RestUser module role of the Mendix Cloud Client Certificate Verification Module to a user role in your app, if needed. End-users with a user role including the RestUser module role are allowed to view, add and update registered client certificates through the REST APIs.
4. Add the ClientCertificate_Overview page to the navigation of your app, if needed. End-users with the Administrator module role can view, add, edit and delete registered client certificates through this page.
5. Add the appropriate verification microflows to your app. See Verification, below.
6. Configure your app to recognize which end-users are verified and which client certificates they are using. See Configuration, below.

• Verify the end-user’s client certificate in a custom authentication microflow — the preferred method
• Verify the end-user’s client certificate in the REST or OData operation microflow

• End-users with the Administrator module role can add and update registered client certificates via the UI.
• End-users with the RestUser module role can add and update registered client certificates via the REST API. For more information, see REST Operations, below.
• You can enable auto-update, to automatically register certificates and associate them with the end-user. See Auto-update, below.

1. Sign into your app with the Administrator role.
2. In your app, open the ClientCertificate_Overview page.
3. Click the New button.
4. Provide the following information:
   • User - The end-user the client certificate will be associated to
   • Serial (string) - The serial number of the client certificate
   • Thumbprint (string) - The thumbprint of the client certificate
   • Allowed (boolean) - This indicates whether the new client certificate can be used by the end-user (true) or not (false). 
5. Click Save to store the new client certificate. If you are adding a certificate with Allowed set to true , click Proceed to allow the use of this client certificate or click Cancel to leave the certificate marked as no allowed. This verification is added to prevent an administrator allowing a certificate by accident.
6. If you are adding a certificate with Allowed set to true  for an end-user who has other certificates active, click Yes to block all other certificates for the same end-user, making this certificate the only certificate they can use. Click No to skip this step; this might result in multiple certificates being allowed for a single end-user.

1. Sign into your app with the Administrator role.
2. In your app, open the ClientCertificate_Overview page.
3. Select the certificate that you want to update.
4. Click the Edit button. 
5. For the Allowed (boolean) parameter, select one of the following values:
   • True - The new client certificate can be used by the end-user
   • False - The certificate cannot be used 
6. Click Save.
7. If you are assigning a certificate where Allowed is currently set to false and you are now allowing it, click Proceed to allow the use of this client certificate or click Cancel to leave the certificate marked as no allowed. This verification is added to prevent an administrator allowing a certificate by accident.
8. If you are allowing a certificate for an end-user who has other certificates active, click Yes to block all other certificates for the same end-user, making this certificate the only certificate they can use. Click No to skip this step; this might result in multiple certificates being allowed for a single end-user.

• AutoUpdateClientCertificateForUser. Enables auto-update ( when set to  true) or not (when set to false ). See Auto-update, below for more information. Default value: false.

• HttpHeaderAuthorization: key of the HTTP header containing the credentials for basic authentication. Default value: Authorization.
• HttpHeaderKeyClientCertificateSerial: key of the HTTP header containing the serial number of the client certificate. Default value: Ssl-Client-Serial.
• HttpHeaderKeyClientCertificateThumbprint: key of the HTTP header containing the thumbprint of the client certificate. Default value: Ssl-Client-Fingerprint.
• LogNodeName: the name of the log node used to log messages. Default value: MendixCloudClientCertificateVerificationModule.

[ { "allowed": true, "serial": "01", "thumbprint": "ABC", "user": { "name": "user1" } } ]

{ "allowed": true, "serial": "01", "thumbprint": "ABC", "user": { "name": "user1" } }

[ { "allowed": true, "serial": "01", "thumbprint": "ABC", "user": { "name": "user1" } } ]

• Allowed (boolean) - Indicates whether the new client certificate can be used by the user (true) or not (false)
• Serial (string) - The serial number of the client certificate
• Thumbprint (string) - The thumbprint of the client certificate

{ "allowed": true, "serial": "01", "thumbprint": "ABC" }

{ "allowed": true, "serial": "01", "thumbprint": "ABC", "user": { "name": "string" } }

• allowed (boolean): indicates whether the new client certificate can be used by the end-user (true) or not (false). 

{ "allowed": true }

{ "allowed": true, "serial": "01", "thumbprint": "ABC", "user": { "name": "user1" } }