Integrating a WebGME Design Studio with CPS-VO¶
An integration between a WebGME design studio within CPS-VO simply means that a link to the design studio is available from a group on CPS-VO. Additionally the user’s identity at CPS-VO is forwarded to the WebGME server. By disabling the option for users to register on your WebGME deployment, you can ensure that only people with user-accounts on CPS-VO (and access to your particular group) are able to logon to your deployment.
In order for this to work properly this documentation will guide you through the necessary steps on how to host such a WebGME deployment (most of these steps apply regardless of whether or not the deployment is integrated with CPS-VO.)
The steps are as follows:
- Enabling authentication on your WebGME server
- Allowing CPS-VO to authenticate users in WebGME.
In addition to these steps you need to setup a secure deployment. Notes on that can be found in the previous section.
Step 1: Enabling authentication on your WebGME Server¶
Before turning on authentication you must generate a set of RSA Keys.
These are used to encrypt (the private key) and decrypt (the public key) the tokens containing the users identity.
Sharing the private key with CPS-VO allows it to forward the users identity to WebGME. (One way of doing this is to set
the token query when navigating to your WebGME site, e.g.
- Create a new directory, e.g.
mkdir token_keys, next to your checked out repository. (It’s important that these keys are outside the cwd of the running WebGME server.)
- Using openssl (available for windows here) a private key is generated with:
openssl genrsa -out token_keys/private_key 1024
- The public key is generated from the private key with:
openssl rsa -in token_keys/private_key -pubout > token_keys/public_key
With the keys generated the next step is to configure WebGME to enable authentication/authorization. Since you probably want to have a different configuration for deploying the server then when you’re developing your application it’s advised to create a new configuration that appends to your default configuration.
Create a new file in your repository at
this section describes how to make sure it is being used.
Read through the section here and add the content to your new file.
// you can remove this line once you know this file is picked up console.log('### using webgme config from config.deployment.js ###'); // require your default configuration var config = require('./config.default'); // enable authentication config.authentication.enable = true; // by default non-authenticated users are authenticated as 'guest' this can be disabled config.authentication.allowGuests = false; // this allows users created via the cps-vo route to create new projects // which may or may not suite your deployment (but most likely you want this enabled) config.authentication.inferredUsersCanCreate = true; // disable user registration config.authentication.allowUserRegistration = false; // this assumes the keys are placed outside the webgme-app folder, // as mentioned in the key generation section ../../token_keys directory config.authentication.jwt.privateKey = __dirname + '/../../token_keys/private_key'; config.authentication.jwt.publicKey = __dirname + '/../../token_keys/public_key'; // finally make sure to export the augmented config module.exports = config;
The full list of all available configuration parameters regarding authentication is available here.
It’s always a good idea to have a site-admin account for your deployment which allows you to create, delete and manage access level of users, etc. from the WebGME profile page interface.
Since WebGME version 2.25.0 you specify an admin account to be created (or ensured to exist) at server startup.
The following addition to the
config.deployment.js above will create a user
admin with password
// The password defined here will be visible so make sure to change it once the server has // been run at least once. config.authentication.adminAccount = 'admin:password';
You should now be able to login to the profile page at
<host>/profile/login, once logged in make sure to change the password from the WebGME profile interface.
Alternatively, or if you should forget the admin password, you can change the password from using the following command
(make sure to set the correct environment variable for the configuration by setting
node node_modules/webgme-engine/src/bin/usermanager.js passwd admin newPassWord
For more details about authentication and authorization in WebGME these tutorials have a dedicated section.