This application provides a single page app to get a Mist PSK from the Mist Cloud. This App can use AzureAD, ADFS/SAML, Okta or Google authentication.

Copyright (c) 2021 Thomas Munzer

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

• Admin interface to configure:
  • the Mist integration
  • the Authentication method
  • the logo and colors
  • the translations
• AzureAD, ADFS/SAML, Google and Okta integration
• User self-service portal with Email and QRcode features

This Reference Application can be used as a standalone Application, or it can be deployed as a Docker Image (recommanded).

This application is available as a Docker Image. The Dockerfile is also available if you want top build it on your own.

docker create -v <path_to_config.js>/config.js:/app/config.js:ro --link <mongoDB_container_name>:mongo --name="<container_name>" -p 3000:80 tmunzer/mpss

Configuration can be done through the config file. An example of the config.js file can be found in src/config_example.js. Then, you just need to link the config.js file to /app/config.js in you container.

You can also use environment variables to configure the app:

This App is storing ADFS/SAML information used for the SSO process. You can use a permanent storage to keep the same settings even if the container is restarting. I will simply show the basic procedure here to use a permanent storage:

1. Create a data directory on a suitable volume on your host system, e.g. /my/own/datadir.

2. Start your app container like this:

$ docker run --name some-name -v /my/own/datadir:/app/certs -d tmunzer/mpss

The -v /my/own/datadir:/app/certs part of the command mounts the /my/own/datadir directory from the underlying host system as /app/certs inside the container, where Mpss by default will store the certificates.

This Reference APP is built over NodeJS.

• Install NodeJS LTS: https://nodejs.org/en/download/.
• Clone this repo.
• Configure the APP settings, in the src/config.js file. You will find an example in src/config_example.js. With Docker deployment, all the settings can be configured by using Environment Variables (see below)
• Install npm packages (npm install from the project folder).
• Start the APP with npm start from the src folder

If you want to use OAuth authentication, the application will need to use HTTPS. To do so, you can use a reverse Proxy (NGINX, Apache, ...) and manage the certificates at the reverse proxy level, or you can configure the app to enable HTTPS. In this case:

• Edit the config.js to enable HTTP
• Place you certificate and certificate key in the src/certs folder. The certificate and key must be name based on the names configured in the config.jsfile
• Start the APP with npm start from the src folder

It is very important to protect your Mongo DB from external access.

This application needs some critical information to be able to create/delete/retrieve the users' PSK. For example, the application need the Mist API Token, the Mist org_id and Mist site_id. These information can be used by afterward by malicious users to access your Mist Organization.

To protect your data, be sure to:

• Block all the external access to your Mongo DB
• Protect your Mongo DB with authentication

It is also possible to encypt most of the information stored by the application by setting the MONGO_ENC_KEY and MONGO_SIG_KEY configuration variables (or encKey and sigKey in the config.js file).

** WARNING: Be sure to backup your DB before starting the migration **

If you start to use the application without setting the encription and signature keys, the application already stored some data unencrypted.

You can use the encrypt_db.js node script to automatically encrypt the data in your DB. To do so, just configure the encyption and signature keys, start the script (node ./encypt_db.js from the src folder). If the script ended succesfully, you can start the app again (npm start) with the encryption settings set.