Edge2Cloud guide

Owned by Kimberly Cruz (Unlicensed)
Last updated: May 13, 2024 by Ricky Villa
32 min read

This is a general guide for using Edge2Cloud.

Alternatively, for a quick getting started guide, click here: Getting started with Edge2Cloud.

Please note, Edge2Cloud isn’t suitable for kiosk style applications that require a user to be logged permanently into FIN. Please see Edge2Cloud’s frequently asked questions for more information.

 

Organizations

All users and devices (FIN instances) are grouped under an organization…

  • Organization: a company in the system. This could be a System Integrator, OEM, building owner, or any other company that represents a stake holder in the system. An organization has devices and users.

  • User: a user can belong to multiple organizations. A user’s primary organization typically represents their employer. A user can be invited to join other organizations. See Users, below, for more information.

  • Device (FIN instance): this represents a FIN install. Devices always belong to one organization only. See Devices, below, for more information.

  • Projects: each FIN instance can have multiple projects. This information is uploaded to Edge2Cloud when FIN connects or any changes are made.

  • Sites: each project can have multiple sites. A site is a building. This information is pushed to Edge2Cloud when FIN connects.

An organization can only be created by a user with OrgAdmin role, see Edge2Cloud Portal Admin for details
J2 distribution partner organizations are created as part of new partner onboarding process. If you have any questions about setting up organizations please contact J2 Sales (sales@j2innovations.com)

Organizations are a key part of Edge2Cloud and the whole FIN eco-system. They are used for creating and tracking licenses as well as managing devices.

Organization blue print

Structuring organizations so they can work together is important in Edge2Cloud. The typical recommended organizations in Edge2Cloud are…

  • Distribution partner: the FIN distribution partner/OEM for Edge2Cloud.

  • System Integrator: the FIN installer.

  • Building Owner: the owner of building who also typically owns the license.

It’s recommended that each building owner has their own unique organization with their own devices registered under them. An SI’s users can then be invited to join that organization and manage the devices on behalf of the building owner.

Users

Users belong to at least one organization.

  • A user’s primary organization is typically their employer.

    • A user’s primary organization can never be changed.

  • A user can be invited to join other organizations.

    • For instance, a user might have a service contract to manage multiple buildings on behalf of a building owner. Each organization can be represented in Edge2Cloud.

  • A user can have different level of authorization in different organizations.

    • For instance, a user could have a completely different set of permissions in one organization (where they just have access to some of the sites) compared to their own organization where they have administrative privileges.

Each user in Edge2Cloud requires their own unique email address.

A user also requires a cell phone number to be added for multi-factor authentication.

What is MFA (multi-factor authentication)?

When a user logs into Edge2Cloud, they are required to enter a user name and password. In some cases, they also may be required to enter a special code sent directly to the user’s cell phone via an SMS message.

By default, Edge2Cloud uses adaptive multi-factor authentication. Therefore, a user may only need to enter a special code sent to a cell phone when Edge2Cloud deems it necessary. For instance, if the system detects a suspicious log in pattern.

Adaptive MFA provides an extra layer of security from malicious users.

Roles

Each user in Edge2Cloud has a set of roles. Roles determine what a user can and cannot do in Edge2Cloud…

 

  • Device Manager: can register new devices with Edge2Cloud. See device registration for more information.

  • Device Op (operator): can view all the device, project and site information belonging to an organization.

  • Device Admin (administrator): can view, edit, and delete device, project, and site information belonging to an organization.

  • Remote Op (operator), Remote Admin (administrator), Remote Super User: the roles FIN uses when this user accesses FIN remotely. A user in FIN can be either an operator, administrator or super user. When accessing FIN remotely, your Edge2Cloud user is used to access FIN. These roles are used for the user in FIN.

  • User Op (operator): can view all the users in an organization.

  • User Admin (administrator): can view, edit, and delete users in an organization. This includes editing a user’s roles.

  • Organization Op (operator): can view all sub-organizations associated with this organization.

  • Organization Admin (administrator): can edit details about this organization. If the organization is a distribution partner or SI, new sub-organizations can be created.

Use cases

Please note, it is best practice to follow the principle of least privilege when configuring roles for users. Therefore users should have the minimum number of roles necessary.

Also note that it is recognized that in reality, these roles do cross over and change. For instance, a building owner could be fully trained to engineer FIN etc.

System Integrator

An SI user will typically…

  • Register new devices (FIN instances) with Edge2Cloud so the Device Manager role is required.

  • Manage devices in an organization.

    • If the user is managing all the devices in an organization, they’ll require the Device Admin role. If they can view all the devices but not delete them from an organization then they should have the Device Op role.

    • If the user should view only some of the devices in an organization they should not have the Device Admin or Device Op role. Instead access groups should be used to configure their fine grained permissions.

    • If the user can remotely access FIN, they should have a Remote Op, Remote Admin or Remote Super User role.

      • Typically an SI user who is modifying FIN should have the Remote Admin role.

      • If an SI is just working with existing graphics and changing set points then the Remote Op role should suffice.

      • The Remote Super User role should be used rarely. If administrative access is required (commits are being made to FIN’s database) the Remote Admin role will suffice.

    • If the SI user is also managing access for other users in the organization, the User Admin role may be required. If the SI user is only viewing or referencing other users, the User Op role should only be required.

      • Please note, configuring users in access groups will require the the user to have User Op role so a list of users can be accessed.

    • An SI will typically want to create sub-organizations for their customers (building owners). In this case, the user should have the OrgAdmin role.

Company Administrator

A company administrator is someone who manages users in an organization but not any of the buildings or devices. In this case this user would just have the User Admin role and nothing else.

If the administrator only needs to view the users in the system but does not need to add or delete them, the User Op role should be used.

Please note, only a user who has the User Op or User Admin roles can view the organization’s audit log.

If the user needs to view (read-only) all the devices in the building including their project and site information, they could also have the Device Op role.

If the user needs to view (read-only) sub-organization details, they should have the OrgOp role.

Building Owner

A building owner has access to graphics for their sites and can change set points. They cannot view any buildings they do not own, nor can they engineer the system.

It is typical this user would only have the Remote Op role and nothing else. Fine grained access to the user’s sites is configured using access groups.

Managing Users

A user with the User Admin role can create new users in their organization or invite existing users from other organizations to join their organization.

Security and privacy

Managing users in an organization is a big responsibility and great care needs to be taken.

If you have received an email requesting access to your organization, can you authenticate who the user is? There is always a possibility that it could be a hacker attempting to gain remote access to your portfolio of devices. Some tips are:

  • Only add users to the system who you know.

  • Check the email address of the recipient. Please note, email is an old technology, and addresses can be faked, so do not use this as the only factor to check.

  • Call the user to ensure they are the person in question.

  • When contacting a user consider, asking them a question that only you and they would know the answer.

Always create users with the fewest number of roles possible. It is tempting to give a user all the user roles available, but this is a bad practice. Always give the least amount of privilege to users in your organization.

Respect the privacy of the users in your organization. Never unnecessarily divulge any personal identifiable information.

Creating new users

If a user has the User Admin role in an organization, this user can view the organization’s main page in Edge2Cloud and click ‘New’ to create a new user.

 

  • Name: the full name of the user.

  • Email: the user’s email address. Email addresses are special in Edge2Cloud and must be unique. Creating two users with the same email address should be unnecessary - remember that users can be invited to join other organizations.

  • Phone: the user’s cell phone number. See the section on multi-factor authentication to see how this is used. The phone number must start with the international dialling code. For instance, for the US this would be +1.

  • Locale: the user’s language settings. Currently this is set to English (en).

  • Roles: as described in user roles.

  • Access groups: The access groups this user should be included in. See access groups for more information.

After clicking ok, an email invitation is sent to the target user.

 

The new user is initially marked as Unregistered. The new user cannot do anything in the system until they’ve completed their user registration process. After the user is registered, they become Active.

When the new user receives an email asking them to complete the user registration process, the following should occur:

  • The user is asked to log into Edge2Cloud.

  • The user is given a temporary password in the email. When the user logs in for the first time:

    • The new user has to enter the temporary password.

    • After entering the temporary password, the user has to enter a strong password.

  • After the user has logged in, the user must click the register button and agree to the acceptable use policy/terms and conditions.

    • The user must scroll to the bottom of the conditions for the I Accept button to become enabled.

  • After the user has agreed and has clicked Continue, they are navigated to the portal and can start using the system.

 

Please note that even without any roles, a user can:

  • See all organizations to which they belong.

  • Can change their own name, phone number, and locale in the system.

Inviting Users

A user with the User Admin role can invite a user to join another organization. For instance, in order for a user admin to invite another user to join Acme System Integrators, the user admin must have the User Admin role in the Acme System Integrators organization.

On an organization’s main page, click New under Invites, to create an invitation.

 

The email address must be valid and already belong to a user in the system. When OK is clicked, the invitation is sent.

  • The invitation will expire in one week.

  • The invited user will receive an email. The user needs to click on a link in the email to complete the registration process.

  • The invited user may be asked to log in to complete the invitation process.

  •  

  • The invited user needs to click Accept to complete the invitation.

  • Once a user has accepted the invitation, the original user admin can assign roles to the newly invited user.

Viewing, editing and deleting users

A user can view their own details in any organization of which they are a member. A user who has the User Op or User Admin role can also view all user’s details in their organization.

A user’s details can be accessed from the user list on the organization’s main page in the portal.

 

  • A User Admin can edit and delete users in an organization.

  • If the user is viewing their own details, they can only edit their own details.

  • A User Admin can edit user roles in an organization.

  • If the user being deleted has a different primary organization (a.k.a. they have been invited), only the user’s invitation to the organization is deleted.

  • A User Op can only view user details. They cannot edit or delete.

Audit trail

A User Op or User Admin can view an organization’s user audit trail. Entries in the audit trail will be automatically removed after one year.

The audit trail provides a list of all activity for the organization within Edge2Cloud.

Please note, it doesn’t provide the audit trail for FIN or remote access. FIN’s audit trail needs to be configured when it’s commissioned!

Hovering the mouse over the before and after columns will provide more details on a particular item.

Custom Roles

As a OEM customer, you can work with J2 Innovations to provide your users with pre-defined custom user roles that are specific to your application that’s based on the FIN framework.

If your company’s organization has been configured accordingly, you may also notice you can select a custom role for your user.

Devices

An installed instance of FIN is known as a device. Once FIN (5.0.6 or higher) is installed, it can be registered with Edge2Cloud and will appear in the portal.

Remote access for users is included for free for all instances of FIN that have valid maintenance.

Only users who have the Device Manager role can register new instances of FIN with Edge2Cloud. Please see the Getting started with Edge2Cloud for step-by-step guidance in registering FIN with Edge2Cloud.

Edge2Cloud in FIN

Open the Cloud App in FIN to view and configure Edge2Cloud. Your FIN user will require Super User permissions to view and configure the Cloud App.

 

  • Status: shows the current Edge2Cloud status.

    • Connected: FIN is connected successfully to Edge2Cloud.

    • Disconnected: FIN is currently disconnected from Edge2Cloud. Please note, FIN will automatically reconnect to Edge2Cloud when it is able to. No need to restart FIN!

    • Deleted: FIN has been deleted from Edge2Cloud. This happens when a user deletes FIN from Edge2Cloud. Please see re-registering FIN for what steps to take when this happens.

    • Maintenance out of date: FIN’s maintenance is out of date and needs to be renewed before FIN can connect to the Edge2Cloud services. Please contact support@j2inn.com for more information regarding maintenance if you are unsure.

  • Edge2Cloud Portal: a link to the Edge2Cloud portal.

  • Register with Edge2Cloud: click to register FIN with Edge2Cloud. This also shows the current registration status.

    • Registered: FIN has been already registered with Edge2Cloud. Assuming there’s an Internet connection and maintenance is up to date, FIN should be able to connect to Edge2Cloud.

    • Unregistered: FIN isn’t yet registered to connect to Edge2Cloud. A user needs to click this link and register this instance of FIN with an existing organization.

  • Registration QR Code: click to get a QR code. This QR code contains a link used to register FIN with Edge2Cloud. This is an alternative way to do device registration. Please see registering FIN without an Internet connection for more details.

  • Sync Device: FIN will automatically synchronize information with Edge2Cloud. A check is made every 2 minutes to see if any data has changed in FIN and needs to be resent.

    • The data synchronized with FIN is all project and site records. This is used to create the Cloud side navigation you see in the portal.

    • Because synchronization happens automatically you should never really need to click this command.

  • Diagnostics: some useful diagnostic information for Edge2Cloud.

Please note, even though the Cloud app is available per project, all settings apply to all projects. For instance, after FIN has been registered, all projects and sites will be synchronized with Edge2Cloud. Device registration only needs to happen once per instance of FIN.

Device registration

Device registration is the process of connecting FIN to Edge2Cloud. A device is always registered under an organization.

The user registering the device must be a Device Manager within that organization. If the user is a Device Manager in multiple organizations, the user will be presented with a choice.

Device registration is started by a user opening the Cloud App in FIN and selecting Register with Edge2Cloud…

 

  • The user is redirected to the Edge2Cloud device registration website.

  • If not already, the user is asked to log in.

  • The user has to select an organization for the device and confirm the device’s registration by clicking Register.

The device id is a special unique id assigned to the connected FIN instance during the registration process.

After a few minutes, FIN will automatically connect to Edge2Cloud. If FIN doesn’t connect please see firewall issues below.

Please note from FIN 5.1 onwards, if the registration process isn’t completed in one hour from the time the user clicks the Register with Edge2Cloud button (or Registration QR code), FIN will only check whether it can connect to Edge2Cloud services every 4 hours.

Registering FIN without an Internet connection

Commissioning FIN can happen in a variety of situations. In some cases, commissioning may even happen on site where there’s no available Internet connection yet. In this case, FIN can still be registered with Edge2Cloud via a QR code.

Clicking on the Registration QR Code from the Cloud App will load a QR code. A user can then take a photo of it using their smart phone.

 

The rest of the device registration can then be handled via the user’s smart phone. A smart phone (iOS or Android) will convert the QR code into a URL. Loading the URL in a web browser will take the user to the device registration web site as normal.

The QR code is valid for 3 days.

Re-registering FIN

Very rarely it may be necessary to repeat the device registration process. For instance, registering the device under a new organization. To re-register a device…

  • Ensure the device is deleted from Edge2Cloud.

  • Stop FIN.

  • Delete this file: yourFinInstallPath/var/etc/finEdge2Cloud/cloud.ks

  • Start FIN.

  • Register device with Edge2Cloud.

This process is intentionally onerousness and can’t be done via remote access because it’s transferring device ownership to another organization. Performing this operation requires local access to the device running FIN and its file system.

Finding newly registered devices

It is best to find the sites and the project the device relates to and then navigate back to the device. If this isn’t available then go to Devices in the portal and sort by the Registered date to see the newest registered devices. Clicking on the device will take you to the device details summary page.

 

Viewing and deleting devices

In the portal, Devices shows a list of all the available devices for a user from all organizations of which the user is a member.

  • If the user is a Device Op or Device Admin in an organization, all devices from that organization will be shown in the list.

  • Alternatively, if the user is part of an access group, all devices available to that user from the access group will be shown.

Clicking on a device will show its details.

 

  • Delete: deleting a device will completely remove the device from Edge2Cloud. This option is only available if the user is a Device Admin within the device’s organization.

    • Deleting a device will cause it to disconnect from Edge2Cloud.

    • Deleting a device will require the device to be re-registered to join Edge2Cloud again.

    • Nothing on FIN will be deleted. Deleting this device only removes it from Edge2Cloud.

  • Refresh: refresh the device’s details.

  • Remote access: remotely access the device. The user must be a Remote Op, Remote Admin, or Remote Super User to remotely access this device in an organization.

  • Sync: sends a command to the device telling it to sync with Edge2Cloud. Please note, this happens automatically and should not need to be used. A user must be a Remote Admin or Remote Super User in order to view and invoke this button.

The details view shows a list of all projects belonging to this device.

Projects

A device (FIN instance) can contain many projects. Projects are created in FIN and contain sites.

It is recommended that unique project names are chosen to avoid any portfolio conflicts.

Click Projects in the portal to show a list of all available projects. All projects from all available organizations the user is a member of are shown.

  • If the user is a Device Op or Device Admin in an organization, all projects from that organization will be shown in the list.

  • Alternatively, if the user is part of an access group, all projects available to that user from the access group will be shown.

 

Clicking on a project shows its details…

 

  • Delete cached: if the user is a Device Admin, the user can delete the project data held in Edge2Cloud. Next time the device is synced (from FIN or from the device details page), the project may appear again if it still exists.

    • This will not delete the project from FIN. It only deletes the project data from Edge2Cloud.

  • Refresh: refreshes the details.

  • Remote access: remotely access the device. The user must be a Remote Op, Remote Admin, or Remote Super User to remotely access this device in an organization.

  • Sync: sends a command to the device telling it to sync with Edge2Cloud. Please note, this happens automatically and should not need to be used. A user must be a Remote Admin or Remote Super User in order to view and invoke this button.

The breadcrumb trail shows the device to which this project belongs.

Tags

A list of tags cached in Edge2Cloud for the project. This originates from the project record held in FIN’s database.

Sites

A list of sites for the project. A user can click on this list to view a site’s details.

Totals

A summary of totals of various record types for the project in FIN. These are calculated when a device (FIN) is synched with Edge2Cloud.

Remote summary

A live view of information for the project that is refreshed every 30 seconds.

This will only appear if the device is connected at the time and the user is a Remote Op.

Sites

A device (FIN instance) can contain many projects. Projects are created in FIN and contain sites.

It’s recommended that unique site names are chosen to avoid any portfolio conflicts.

In Haystack, each site represents a building.

Click Sites in the portal to show a list of all available sites. All sites from all available organizations the user is a member of are shown.

  • If the user is a Device Op or Device Admin in an organization, all sites from that organization will be shown in the list.

  • Alternatively, if the user is part of an access group, all sites available to that user from the access group will be shown.

 

Clicking on a site shows its details.

 

  • Delete cached: if the user is a Device Admin, the user can delete the site data held in Edge2Cloud. Next time the device is synced (from FIN or from the device details page), the site may appear again if it still exists.

    • This will not delete the site from FIN. It only deletes the site data from Edge2Cloud.

  • Refresh: refreshes the details.

  • Remote access: remotely access the device. The user must be a Remote Op to remotely access this device in an organization.

  • Sync: sends a command to the device telling it to sync with Edge2Cloud. Please note, this happens automatically and should not need to be used. A user must be a Remote Admin in order to view and invoke this button.

The breadcrumb trail shows the device and project to which this site belongs.

Tags

A list of tags cached in Edge2Cloud for the project. This originates from the site record held in FIN’s database.

Totals

A summary of totals of various record types for the project in FIN. These are calculated when a device (FIN) is synched with Edge2Cloud.

Remote summary

A live view of information for the site that is refreshed every 30 seconds.

This will only appear if the device is connected at the time and the user is a Remote Op.

Dashboard

Clicking Home loads the main portal dashboard. The map shows all the sites available to the user in the system.

In order for a site to appear as a record on the map, the site record in FIN must contain the latitude and longitude.

 

Clicking on a point shows the site pop up.

 

Clicking on the title navigates the user to the site details.

If the user is a Remote Op, Remote Admin, or Remote Super User, in the organization and has access to the device, the user will be able to click on the Remote access button. This will open a new tab with remote access to the device.

Dynamic site markers

Starting from FIN 5.1 onwards, the color of the markers can be changed from FIN using the finCurSiteStatus tag on a site record.

The finCurSiteStatus is a transient string tag that can have one of the following values…

  • disabled: the site is disabled (grey).

  • down: the site has a communication or network problem (yellow).

  • fault: the site has a configuration or hardware problem (orange).

  • alarm: the site is in alarm (red).

  • overridden: the default state of the site has been overridden (purple).

  • noncommissioned: the site is not yet commissioned (pink).

  • maintenance: the site requires maintenance (blue).

  • ok: the site is ok (green).

  • unknown: the current state of the site is unknown (white).

The default status of a site is ok (green). This is different from the original darker red value used for map markers.

The tag is not automatically updated by FIN. Instead this tag value can be updated via an Axon function or program.

For instance, to update all of the site’s finCurSiteStatus tags to ok, the following Axon function could be used…

readAllStream(site).each(s => diff(s, {finCurSiteStatus: "ok"}, {transient}).commit())

Please note, how the Axon function updates the value transiently. Just like a point’s curVal, the value isn’t permanently written to FIN’s database. The finCurSiteStatus tag should never be written permenantly to FIN’s database.

FIN will check whether it needs to write any new finCurSiteStatus values to the Cloud every two minutes. Also the portal’s map UI will automatically update its map markers every two minutes.

Cloud dashboards

By default a simple table is displayed when map marker is clicked in FIN. A user can change this behavior by loading a graphic or some custom application from FIN remotely instead of the table.

In order to use this feature, a user must have remote access (at least RemoteOp) to the site in question.

Loading a dashboard

A dashboard builder application is available from FIN 5.1 onwards. When creating a dashboard, a user can select an option for it to be a cloud dashboard. This adds the finE2CMapDefault marker tag to the dashboard record.

Please note, ideally the dashboardOn filter should be set to filter for a site or all sites. Remember that a Cloud dashboard is always relative to a site.

Tip: all dashboard records are tagged with the finDashboard marker tag.

Loading a graphic

Please note, this works with all versions of FIN connected to Edge2Cloud.

To load a site graphic in the pop up, the site graphic record (not the site record) must have the finE2CMapDefault marker tag added to it.

There are some limitations to what the graphic can do when loaded in this way. For instance, magic bubbles are not currently supported.

Tip: all graphic records are tagged with the fin5 marker tag. Additionally default graphics are tagged with the default tag.

Loading an application

Instead of a graphic a custom application’s UI can be loaded. To do this, add the finE2CMapUri Uri tag to the site record (not graphic). The tag’s value must have a relative URI that will load the application. For instance, /foo/bar/index.html.

Handlebars syntax can be used to replace parts of the URI dynamically. For example…

/pod/finDashboardExt/index.html#id=@p:demo:r:27ca7d9e-24132349&target={{siteRef}}&projName={{projName}}

At runtime, siteRef and projName will be replaced with the site ref and project name.

The following find and replace keys are available…

  • projName: the project name.

  • siteRef: the site’s ref.

  • projRef: the project’s ref.

Developer notes

On a technical note, all UI content that’s loaded lives in a sandboxed cross domain iframe. As such there are some security imposed limitations. Any JavaScript running in the application will not have access to window.top.origin or window.parent.origin. Any attempt to access these properties will result in a DOM exception being thrown.

One technique to workaround this issue is to check whether the application has access or not via…

function isTopAccessible() { try { window.top.origin return true } catch (err) { return false } }

Ideally window.postMessage should be used for communcation between frames.

Customizing the the hyperlink for a site

By default, clicking the remote access button on a site will navigate to the site’s graphic. This can be customized by adding a finE2CViewUri Uri tag to the site record. The value of the tag must be a relative hyperlink. For example, this will load a custom application a site is hyperlinked to…

Handle bars syntax can be used to find and replace elements of the hyperlink…

  • projName: the project name.

  • siteRef: the site’s ref.

  • projRef: the project’s ref.

For example…

After making this change to the site record, a ‘sync’ may be required in FIN in order for the site record changes to be sent up to Edge2Cloud. Please note, this should happen automatically after a minute.

Firewall configuration

  • FIN always makes an outgoing connection to Edge2Cloud.

    • Never directly expose FIN onto the Internet. Edge2Cloud alleviates the need for this.

    • No VPN is required in order to use Edge2Cloud. Again Edge2Cloud is designed so VPNs do not have to be configured for remote access.

  • If FIN uses Java 8, port 8883 (secure MQTT) and 443 (HTTPS) are used to make an outgoing connection to Edge2Cloud.

  • If FIN uses Java 11, port 443 (HTTPS) is used to make an outgoing connection to Edge2Cloud.

It’s recommended to use Java 11 with FIN to avoid having to configure a firewall for port 8883 (secure MQTT).

All ports use TCP.

Before FIN creates a connection to the Edge2Cloud services, it makes various calls to HTTPS end points. This includes:

  • A call to https://cert.e2cloud.io to look up the public certificate FIN should use.

  • A call to https://config.e2cloud.io to look up MQTT end point and brand information.

  • After these calls have been successful, FIN will attempt to connect to its MQTT end point.

  • When a tunnel is created, FIN will open a web socket connection (HTTPS) to an Edge2Cloud endpoint.

  • Please note, other HTTPS calls will be made during FIN’s lifetime. All of these endpoint calls will be made to the https://*.e2cloud.io subdomain.

Access Groups - fine grained access control

Access groups are used to provide fine grained authorization for remote access in Edge2Cloud.

For instance, say you want to allow a user access to just one site and not all the sites in an organization. An access group is used to associate users and sites together.

Only a Device Op user can view all access groups in an organization. A Device Admin user can create, delete, and edit access groups in an organization.

Navigate to an organization’s main page to view all access groups.

 

Creating new access groups

To create a new access group click New. The new command is only available to a Device Admin user.

 

 

  • Access group name: The display name for the access group.

  • Users: the users to which this access group applies.

    • Typically these users will just have the Remote Op, Remote Admin or Remote Super User role. Remember that Device Op and Device Admin users have access to all devices, projects and sites in an organization. So, these are not typically used for users added to an access group.

  • Application access: the applications the users have access to.

  • Project filter: a haystack filter used to determine what projects the user has access too.

    • For example, for a user to only have access to the test project:

      • name == “test”

  • Site filter: a haystack filter used to determine what sites the user has access to.

    • For example, for a user to only have access to all the sites in the city of Diamond Bar…

      • geoCity == “Diamond Bar”

    • Note how in the above screen shots, the second image doesn’t include Chino Airport. This is because the site filter is limiting everything to the city of Diamond Bar.

  • Other filters: all other filters are used to filter for specific record types in FIN via a haystack filter.

The projects and sites shown on the right hand side of the dialog will change as you type in a project or site filter. This is a preview to show you the results of your filter before you click OK.

When a user remotely accesses a site, the access group will be used and will limit the data the user can see in FIN remotely. For instance, a user will only have access to sites that are in Diamond Bar. This will all be handled in the UI.

It should be noted that users can be added to multiple access groups.

Access group modelling

Region

A typical use case for access groups is filtering by geographical region. For instance, a site filter for…

…will ensure only sites that are located in Diamond Bar will work for the users.

Building type

An alternative approach would be to use marker tags. Marker tags are simple names that can be added to a site record in FIN.

For instance, say in FIN, the marker tag ‘museum’ is added to all sites that are museums. The site filter for limited user access to just museums would be:

Multiple conditions can be used in a haystack filter when the access is dependent on multiple marker tags:

Viewing, editing, and deleting access groups

Click on an access group to view its details.

 

  • Refresh: refresh the data shown in the view.

  • Edit: edit an access group.

    • This button will only be available for Device Admin users.

  • Delete: delete an access group.

    • This button will only be available for Device Admin users.

The lower half of the view shows the projects and sites to which the access group provides access.

Access Tokens

Please note: access tokens are currently in early access. They are not available to use by default! Talk to your FIN distributor for more information.

Users are a way for human beings to get remote access to systems. Access tokens are a way for machines to get remote access to systems. Access tokens enable third party applications to make secure REST API calls into Edge2Cloud.

Here are some use cases regarding how this could be used…

  • A developer wants to write some software that securely pulls history logs for a multiple points from Edge2Cloud and into their analytics application.

  • An SI wants to use FIN’s Haystack Connector (not available until FIN 5.1) with a Cloud connected instance of FIN.

  • A user wants to integrate FIN with a third party Cloud service.

How do they work?

When an access token is created, they user is given a secret code. This code is used to make HTTPS requests to remote Cloud connected systems…

The above diagram shows a third party application making a remote call to a Cloud connected instance of FIN…

  • The third party application makes an HTTPS call to the device’s URL.

  • The device’s URL is same one used when remotely connecting to a system.

  • The API is calling the Haystack about API on a project called ‘myProject’.

  • The HTTP request made by the third party application has an additional Authorization HTTP header. The value is in the format of ‘Bearer accessTokenSecretCodeGoesHere'.

  • The Cloud connected instance of FIN receives the request and sends a response back that’s received by the third party application.

Managing access tokens

Please note: access tokens are not enabled for an organization by default. They have to be enabled by J2! Please contact your FIN distributor for more information!

In order to create an access token, a user must have the Device Admin role. For read only access, a user must have the Device Op role. An access group must also be selected.

Access tokens are managed from the Access tokens tab under an organization…

This view shows all access tokens for an organization including a usage report.

Creating, editing and deleting an access token

Click the New button to create a new access token…

  • Name: the name of the access token.

  • Description: a detailed multi-line description of what the access token will be used for.

  • Expiration: by default, access tokens expire after one year. Once an access token has expired, it can no longer be used after which a new access token will need to be created.

  • Roles: the remote access role the access token will use when communicating with FIN remotely. This is the same role used by a user for remote access.

  • Access group: the fine grained authorization used to limit the access of what an access token. For more information, please see access groups.

Once an access token is created, the user will be presented with the secret code…

  • Clicking on the code will copy it to the clipboard.

  • The secret code is presented only once when an access token is first created. If it’s lost the access token will need to be deleted and then created all over again.

  • The secret code is not stored in Edge2Cloud. Therefore technical support cannot supply it if lost!

  • The secret code must be kept in a secure location. See Access token secret best practices below for more information.

  • Clicking ok will load the summary page for the access token…

The summary page shows all the information about an access token including…

  • A clue for the secret.

  • If the user has the Device Admin role, buttons for editing or deleting an access token will be available.

  • A data usage report for the access token.

    • This shows all the devices (FIN instances) that are using the access token within a given time period.

Deleting an access token is permanent. It will no longer be used by the system and an associated secret will become invalid.

Creating, editing and deleting an access token is audited in an organization’s audit log.

Tracking access token usage

The amount of data an access token uses is tracked.

  • Under an organization, click the Access tokens tab to see a report for all access token usage.

  • Click on an access token to view its summary and view all the devices using an access token.

  • Click on a device and view all the access tokens using the device.

Each report view shows the amount of data used by month. This includes data in the request and response of the API call.

The report can be downloaded as a CSV file that contains details of the usage.

Access token usage limits

Currently there is a free limit of 1 gigabyte per device per month when using access tokens. This limit may change over time. There is no limit on the number of access tokens used - just the device limit.

What happens if the free limit is exceeded?

Access tokens are currently in early access so currently nothing happens. After early access, J2 may charge for data usage beyond this limit.

Getting started with access tokens

The easiest way to get started using access token is by using CURL. This common utility provides a simple way to make HTTPS calls to a remote end point.

Before proceeding…

  • Ensure you have the Device Admin user role in your organization

  • Ensure access tokens are enabled for your organization!

  • You have an access group added under your organization.

  • You have a device (FIN instance) registered under your organization you can remotely connect too.

Now follow these steps…

  • In the portal, navigate to your organization’s main page and click the Access tokens tab.

  • Click new to create a new access token.

    • Remember to select an access group.

    • Select ‘Remote Op’ as the role.

  • Make a note of the access token secret.

  • Open a common prompt or shell and use the following CURL command (remember to replace everything in the braces)…

If it works, you should receive a response similar to the following…

Discovering device end points

As well as directly connecting to end points, an access token can also be used to discover what devices, projets and sites (FIN instances) are available…

For more information, please see the API docs (you’ll need to log in with your Edge2Cloud user account).

  • If you have devices already registered in your organization, you can run the APIs from the documentation.

  • Click ‘Authorize’ and copy and paste in an access token’s secret. You can then try out one of the APIs.

https://remote.e2cloud.io/api-e2cloud-docs/

Calling Haystack APIs

The FIN framework implements all of the standard Haystack REST APIs plus more. Access tokens can be used to invoke any REST API in FIN remotely including Haystack.

Haystack Core and Client are TypeScript libraries developed by J2 Innovations that makes it easy to work with Haystack data at both the client and server level. You can use Haystack NClient to talk to a remote end point…

Calling JSON REST APIS without a supporting library

If you want to call JSON REST APIs without a supporting library (such as haystack-nclient), you can use a vanilla fetch call. To ensure the response is JSON, you need to use the HTTP Accept header.

For example…

Using the Haystack Connector

Please note: access tokens are currently in early access. They are not available to use by default! Talk to your FIN distributor for more information. This feature is only available to use from FIN 5.1 onwards.

Access tokens can be used to with FIN5 and the Haystack Connector. This enables any FIN instance to talk to another other FIN instance providing both are connected to Edge2Cloud…

This architecture enables a variety of use cases…

  • Connect any FIN instance to any other FIN instance in the world without any VPNs.

  • Aggregrate the data from a number of Cloud connected FIN instances into a central FIN instance to create a central Cloud dashboard.

To configure FIN’s Haystack Connector to use access tokens…

 

Again please note that with access tokens…

  • The access token role will be used when accessing the data (Remote Op, Remote Admin or Remote Super User).

  • The access token’s access group will be used for authorization (i.e. what sites, points etc can be accessed).

Access token secret best practices

It’s critical the secret code generated for an access token is kept secret…

  • Never store secrets in source control.

  • Never hard code secrets into your source code.

  • Never use access token secret codes from a web browser.

    • It’s pretty easy for a hacker to use the browser’s a developer console and try to access any secret codes you’re using client side.

  • Never store secrets as plain text.

Cloud backups

Backups can be streamed, stored and downloaded using Edge2Cloud.

To find out more information regarding this feature, please click here.

Problem solving

User timeouts

After a few minutes of user inactivity, a user’s web browser is redirected to a user timeout screen.

This happens for security reasons and cannot be turned off.

The timeout can be changed for an organization (1, 5 or 10 minutes). J2 support can change this for an organization.

Please note, this makes Edge2Cloud unsuitable for kiosk style applications.

Logging

To view all the logs for Edge2Cloud in FIN, ensure this file exists in your FIN install.

Ensure this entry exists in config.props

Now restart FIN and view in the finEdge2Cloud log in FIN.

Alternatively, you can query the log for Edge2Cloud with the following Axon query:

If using the Folio app, please copy and paste the text after you’ve clicked Zinc rather than send a screen shot. This will have more information for support to work from.

Remember to set debug=false after you have finished acquiring all of the detailed debug logs.

Connecting

If FIN is having trouble connecting to Edge2Cloud:

  1. Log on to FIN locally as a super user, go into any project and select the Cloud app.

    1. Does the Status say Connected? If so, FIN is successfully connected to Edge2Cloud.

    2. Does Register with Edge2Cloud say Registered?

  2. If FIN is not registered, then attempt to register FIN using the device registration process. A high level walkthrough is provided in Getting started with Edge2Cloud.

    1. If you have already registered the device but FIN indicates it is still unregistered, then check the firewall configuration. FIN has to make some HTTPS calls out to some Cloud services before it attempts to connect to its MQTT end point.

  3. If FIN is registered but not connected then check the following:

    1. Ensure the machine running FIN has an Internet connection.

    2. See the section on firewall configuration to ensure all relevant ports are open.

Edge2Cloud Security Overview

All OWASP best practices and latest guidelines from NIST are followed for Edge2Cloud’s approach to security. In particular defence in depth and secure by default is followed throughout all layers of the product.

A standards based approach to security is always used. Where possible Edge2Cloud relies on well established and secure AWS services.

Edge2Cloud is regularly PEN tested.

Connectivity

Edge2Cloud offers secure end to end connectivity between a device (FIN), the Cloud and a user.

  • TLS 1.2 is used throughout the entire product.

  • Where possible, the most restrictive policies are used. For instance, TLS 1.2 that only includes ECDHE (PFS) and SHA256 or stronger (384) ciphers.

  • Certificates are all handled in the Cloud and automatically renewed by AWS.

  • FIN connects to AWS IoT Core using certificate based authentication.

    • The certificate is created via a CSR (certificate signing request) that is made when a device is registered with the Cloud.

  • Restrictive MQTT device security policies are used to lock down the MQTT topics a device can subscribe and publish too.

    • A device can only publish and subscribe to topics for itself.

For a list of what ports are required to be opened, please see the firewall section.

Users

A standards based approach to authentication is always used. OpenID Connect is used to for user identity and authentication. All user identity and password management/storage is delegated to AWS Cognito. All advanced security features in AWS Cognito are enabled including…

  • Risk-based adaptive MFA. When an unusual sign-in activity pattern is detected, a risked based score is used to decide whether a user is prompted for additional verification. Users can verify their identities using an SMS message.

  • Protection from compromised credentials. When the system detects users have entered compromised credentials that have been compromised elsewhere, it prompts them to change their passwords.

  • Supports multiple compliance programs: AWS Cognito meets multiple security and compliance requirements, including those for highly regulated organizations such as healthcare companies and merchants. Amazon Cognito is HIPAA eligible and PCI DSS, SOC, and ISO/IEC 27001, ISO/IEC 27017, ISO/IEC 27018, and ISO 9001 compliant.

Edge2Cloud uses role based access control for users. By default, new users are configured with the minimal amount of permissions required.

Storage

Encryption at rest is used throughout the product for storing any sensitive information.

Operational security

Security is an integral part of our operations. This includes regular vulnerability and malware scanning. Best practice AWS tools and procedures are used to help protect Edge2Cloud.

All infrastructure is managed as code and is fully automated. This significantly lowers the risk of accidently exposing sensitive information publically.

Security hardening best practices

  • Users should always be created with the minimum number of permissions. In particular, careful use over the user admin role should be taken since a user with these permissions can change the permissions of all users within an organization.

  • There’s no need to expose FIN onto the Internet or any unsecure network to use Edge2Cloud. FIN will securely call out to the Edge2Cloud cloud services once it’s been registered.