User and Namespace Administration Guide

This guide is intended to be used by VANTIQ administrators and covers how to authorize users to access a VANTIQ installation and how (and why) to create VANTIQ namespaces to perform development tasks and deploy applications. The organization of this guide is somewhat task oriented, but it is intended to serve as a reference guide. For a more directed introduction to the topics covered here please refer to the User and Namespace Administration Tutorial. All of the tasks described here are performed in Modelo using Operations Mode.

Concepts and Terminology

The following terms are used throughout this guide and it is assumed that the reader is familiar with them:

There are a few system configuration options that can influence exactly what the user sees when managing namespaces and users. While these are outside the scope of this document, we did want to highlight them so you are aware of their impact. In each case this document assumes that the configuration matches the configuration of the VANTIQ cloud.

Authentication

VANTIQ can be configured with one of 2 different authentication mechanisms – internal or OAuth. This choice is made at deployment time and cannot be changed without re-installing the VANTIQ node from scratch. Vantiq recommends that central nodes be configured to use OAuth. The use of internal should be reserved for VANTIQ edge nodes. How to configure these options is outside the scope of this document.

The choice of authentication option influences many of the tasks described in this document. Rather than discuss each option for all tasks, we will only cover the “internal” option for tasks that we expect to be performed on VANTIQ edge nodes. Otherwise, it should be assumed we are using the OAuth configuration.

Sending Invitations

Many of the tasks described in this document involve having VANTIQ send an “invitation” to the person who will complete the task. By default these invitations are sent using the GenericEmailSender source which is part of the default VANTIQ configuration. In the VANTIQ cloud this source is configured to send email from VANTIQ Operations. It is also possible to send invitations using either an EMail or SMS source defined in the local namespace. When using an SMS source, you will use the user’s phone number and not their email address, as described in this document.

Self-Administration Tasks

Self-Registration

VANTIQ requires that all users be known to the system and have an associated set of authorizations. For most users this means being part of an organization and being granted authorizations by the org admin (see Organization Administration Tasks). However, some users may choose to self-register in order to perform an evaluation of the VANTIQ platform. The self-registration process is automatically triggered when a user who is unknown to VANTIQ attempts to access the system without an invitation code. When this happens the user will be presented with the following page:

        Self Register

Once the user has provided the requested information they will be authorized to access a personal namespace. This will let them experiment with building a VANTIQ application.

Update Account Info

When configured for OAuth, VANTIQ delegates management of all user profile information to the OAuth provider. For the VANTIQ cloud based systems, that provider is Keycloak. To access the user profile, bring up the “user info pop-up” by clicking on the user’s name in the upper right hand corner of Modelo:

        User Info Popup

From there click on the user name at the top to launch the Account Information pane:

        Account Info

From here the user can update their preferred username, add a VANTIQ specific password, link to other OAuth providers, and configure multi-factor authentication.

System Administration Tasks

Authorizing the Initial System Admin

The initial sys admin should be established immediately after deploying a new VANTIQ node. How this is done depends on how the node is configured to perform authentication.

Internal Authentication

The initial sys admin is created as the well-known user system with a default password of fxtrt$1492. The password should be changed immediately after deployment, before the VANTIQ node is made available to any other user.

OAuth Authentication

When the VANTIQ server is started for the first time, it will print an authorization code to its log file (this code will only be printed once, so it should be recorded immediately). Here is an example of the code:

        System Authorization Code

Once the code has been recorded the intended sys admin should navigate to the root URI for the VANTIQ node. This will trigger authentication via the configured OAuth system and then will present a page where the authorization code can be entered:

        Authorization Code Entry

Submitting the correct code will result in the user being authorized as the sys admin.

Creating a New Organization

To create a new organization launch Modelo in Operations Mode, open the organizations pane, and click the + icon in the title bar. This will bring up the following editor:

        New Organization

From here you can choose to either make yourself the administrator of the new organization or you can choose to invite someone else to take on that role. In the latter case you will enter the email address of the person you wish to invite. When that person receives the email it will include a link which, when followed, will authorize them to be the organization admin. This person may or may not already be a VANTIQ user. If they are not, then processing the invitation will result in creating a new user with the organization namespace as its home. If the user already exists, then processing the invite will add the necessary privileges to that existing instance.

Organization Administration Tasks

Adding a New User to an Organization

To add a new user to an organization launch Modelo in Operations Mode, open the users pane, and click the + icon in the title bar. This will bring up the new user editor:

        New User

Enter the email address of the person you wish to add to the organization. By default the user will be assigned the “User” privilege level. You may or may not want to change this depending on what role the user will play within the organization. The potential roles are:

If you decide you want to use a non-default authorization for the user, click on the “pencil” icon next to Authorizations. This will bring up the following sub-editor:

        Edit Namespace Authorization

This will let you change the authorization for the organization namespace. You can also use this to add authorizations to other, existing namespaces, which can be useful when adding a new application admin or user for an already existing application.

Creating a New Application Namespace

To deploy a VANTIQ application in the organization, the org admin will need to create a new namespace to contain the application’s resources. This is known as an application namespace. Before creating the namespace make sure you know who you intend to act as the namespace admin. There are 3 options:

To create a new application namespace launch Modelo in Operations Mode, open the namespaces pane, and click the + icon in the title bar. This will bring up the following editor:

        New Namespace

Set the “Authorization Level” to Namespace Admin and choose who to authorize. When creating the new namespace the org admin can choose to either make themselves the namespace admin or delegate that privilege to another user. To authorize another user as a namespace admin, enter their email and send them an invitation. In most cases the user you choose should already have been added to the organization as described in the previous task. The only exception to this is if the application that will be deployed in the namespace will be used by users outside the current organization.

Authorizing User to Access Namespace in Organization

The org admin can authorize users to access any namespace that is part of the organization. There are 2 ways to accomplish this.

Authorize User to Namespace

This approach works for users regardless of their home namespace. To authorize a user for a given namespace launch Modelo in Operations Mode, open the namespaces pane, and click on the namespace you wish to authorize to bring up the namespace editor:

        Edit Namespace

From here click on Manage Authorizations to bring up the Edit Authorized User dialog:

        Edit AuthZ Users

This shows all users current authorized in the namespace and their current privileges. To authorize an additional user, click on Authorize User which will bring up the Send Invite dialog:

        Send Invite

Here you can provide the user’s email and select what privileges to grant them.

Update User Privileges

This approach is only available for users whose home namespace is the organization namespace. Start by launching Modelo in Operations Mode, open the users pane, and click on the user you wish to authorize to bring up the user editor:

From here click on the pencil icon next to Privileges in the upper right hand corner. This will bring up a complete list of all of the namespaces in which the user is authorized. From here you can add or remove namespaces and set the privilege levels as you desire.

Creating a Developer Namespace for the Organization Administrator

Sometimes the org admin will also want to do VANTIQ development work. In this case they should create a developer namespace in which to do the work (and from which they can create other developer namespaces). To do this launch Modelo in Operations Mode, open the namespaces pane, and click the + icon in the title bar. This will bring up the new namespace editor as in the previous task. At this point set the “Authorization Level” to Developer and check the Make Me The Administrator checkbox, like so:

        New Dev Namespace for Org

This will create a new developer namespace owned by the org admin.

Application Administration Tasks

Authorizing Users to Access the Application

To authorize a user to access the application, launch Modelo in Operations Mode, open the namespaces pane, click on the namespace to bring up the namespace editor:

        Edit Namespace

From here click on Manage Authorizations to bring up the Edit Authorized User dialog:

        Edit AuthZ Users

This shows all users current authorized in the namespace and their current privileges. To authorize an additional user, click on Authorize User which will bring up the Send Invite dialog:

        Send Invite

Here you can provide the user’s email and select what privileges to grant them. For an application namespace you can choose to grant either User or Namespace Admin privileges. Additionally, if your application includes custom profiles then Custom will also be an available choice.

Adding a New User to the Application Namespace

When managing an application being used by users who are not part of the organization, it can sometimes make sense to add these users directly to the application’s namespace. Remember that in doing this, the application namespace becomes the home namespace for these users. This means that if the application namespace is deleted, those users will lose all of their VANTIQ authorizations (which may or may not be what you want).

To add a new user to an application namespace, launch Modelo in Operations Mode, open the users pane, and click the + icon in the title bar. This will bring up the new user editor:

        New User

By default the new user will have the User authorization level.

If you decide you want to use a non-default authorization for the user, click on the “pencil” icon next to Authorizations. This will bring up the following sub-editor:

        Edit Namespace Authorization

Here you can choose the privileges to grant – User, Namespace Admin, and possibly Custom (if there are non-default profiles available).

Developer Tasks

Creating a New Development Namespace

Whenever a VANTIQ developer needs to work on a new application or on updates to an existing application they should create themselves a new namespace in which to do the work. Each namespace provides an isolated environment in which the developer can work without fear of having their work collide with that of another developer. To create a new namespace the developer should launch Modelo in Operations Mode, open the namespaces pane, and click the + icon in the title bar. This will bring up the following editor:

        New Dev Namespace

As a developer, the only choice for who to make the admin of the new namespace is the developer themselves, so this is the option that will be chosen.

Authorizing Other Users to Access A Development Namespace

There will be times when a developer needs to let other users access the contents of one of their namespaces. This could be to allow someone to test or preview a new feature that they are working on or in order to get help or feedback from another developer. This involves granting authorization to the other user (who must already be a known VANTIQ user) to a specific namespace. Start by launching Modelo in Operations Mode, open the namespaces pane, and click on the namespace to be authorized. This will bring up the namespace editor:

        Edit Namespace

To authorize an additional user, click on Authorize User which will bring up the Send Invite dialog:

        Send Invite

For a developer namespace you can choose to grant either User or Developer privileges. Additionally, if your namespace includes custom profiles then Custom will also be an available choice.