Reference13r3:Concept myApps

From innovaphone wiki
Revision as of 19:18, 29 November 2022 by Msc (talk | contribs) (→‎Redirect to the user's PBX)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
There are also other versions of this article available: Reference13r1 | Reference13r2 | Reference13r3 (this version) | Reference14r1 | Reference14r2

Applies To

This information applies to

  • innovaphone PBX from version 13r1

Overview

innovaphone myApps is the client software for innovaphone users and administrators. The base functionality is provided by a web application that is loaded from the PBX. Additionally there are installable versions for Windows, Android, macOS and iOS that come with an integrated browser and implement adaptations to the local operating system.

The purpose of myApps is to organize and run apps. All productive functionality is provided by additional apps that run inside myApps.

Requirements

Web version

For opening myApps in the web browser you need the most recent version of one of the following browsers:

  • Chrome
  • Firefox
  • Safari
  • or Edge

The following browser features are required and must not be disabled:

  • JavaScript
  • HTML5 Local Storage

Native versions

myApps can also run as native executables on Windows (myApps for Windows), iOS (myApps for iOS), macOS (myApps for macOS) and Android (myApps for Android). In this case, myApps platform services are available and provide additional features. The myApps Web version then runs in a web view window embedded in this native client. See myApps platform services overview for more information.

Licenses

  • No license needed for myApps itself
  • Apps might require licenses

Account

  • A user account (user object) on the PBX is needed in order to use myApps.

Reverse proxy

For access from the public internet, the reverse proxy must be configured to allow access to the following paths on the PBX.

/PBX0/APPCLIENT/appclient.htm
The myApps client itself
/PBX0/session
Needed for two-factor authentication using email
/PBX0/APPS
Needed for apps loaded from the PBX (e.g. softphone and chat) and for apps that use PBX APIs
/OAUTH2/oauth2_login
Needed for OAuth2 authentication


Features

myApps comes with the following features:

  • User login including two-factor authentication.
  • Display and set the own presence (on the home screen and when the focus app is shown).
  • List of all available apps.
  • Running apps (inside an iframe).
  • Apps can be pinned to the main window. Pinned apps are always running and can't be closed. They are also started automatically when the myApps client is loaded.
  • The "app focus" can be used to define a default app for the user. It is started and shown automatically when myApps is loaded. When closing other apps the app is shown instead of the home screen.
  • Detaching apps in myApps for Windows and myApps for macOS. Detached apps are opened in a separate window.
  • Home screen with user-selected apps and app items that can be organized in collapsible groups.
  • List of all myApps-Logins. Unused or suspicious sessions can be logged out remotely.
  • Color scheme selection (light, dark).
  • Configuration of standard apps for certain functions (like phone calls or chat).
  • Link to account specific settings provided by a separate app (profile).
  • Dialogue guidance in following languages: Čeština, Deutsch, English, Español, Français, Italiano, Nederlands, Polski, Português, Русский язык, Slovenščina

All other functionality is provided by apps. For example phone calls require a phone app. Chats require a chat app.

Details

Connecting to the PBX

The myApps web application is loaded from the PBX. The corresponding URL for opening myApps in a browser is

 https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm

The installable versions ask for the "server name" on the first startup. Enter the host name of the PBX to proceed to the login screen. You can change the server afterwards by logging out and clicking the "Change server" link on the login screen.

Supported URL Parameters

Some parameters can be specified with the URL in both the query string or fragment identifier. Those parameters are intended for internal use in the myApps launcher and automated testing. However they could be useful for special applications.

 https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de
 https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm#lang=it

Supported parameters:

lang
The two-letter code of the desired myApps language ("en", "it", "fr", "de", ...)
scheme
The color scheme ("light", "dark").
app
An app link to be started (e.g. "chat").
usr
The user name for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
pwd
The password for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
inactiveTimeout
Overrides the general timeout for the "auto appear offline" feature in browsers. Sets a timeout in milliseconds that shall be used before the user goes offline. Setting it to 0 disables the "auto appear offline". Browser version only. Available from 13r2 SR11.
phys
User defined physical location for Softphone Apps

Example:

 https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de&scheme=light&app=chat#usr=john.doe&pwd=secret

Redirect to the user's PBX

If the logged-in user is not on the current PBX, myApps will be redirected to the user's PBX (as configured in the pbx attribute of the user). The following rules apply:

Master-Slave scenario

  • Slave PBXes redirect to the master PBX.
  • The master PBX redirects to the correct slave PBX.

Note: If the current PBX has no registration to the redirect target PBX but knows the user, it will act as a standby and keep the connection, until the registration is up gain.

Standby scenario

See Reference13r3:Concept_myApps_Redundancy

Deployment of settings

The administrator can deploy some general settings to be used as a default by all myApps clients. This can be done in the admin UI on page PBX/Config/myApps. See Reference13r1:PBX/Config/myApps for details.

Authentication and security

For using myApps you need an account (user object) on the pbx with a password. For logging-in you need to enter the username (SIP-URI) or email address and the password.

Permanent sessions

On each successful login on a new browser or new device a permanent session is created that is defined by a session id and a session password. Those are stored both in the local storage of the browser and at the user object in the PBX. If the user closes myApps and opens it again, the stored session is used. Only when logging-out the session is deleted in both places and the login screen is shown again.

Note that the user password is never transmitted over the network or permanently stored in the browser.

The user can keep track of all his permanent sessions in the myApps menu under "Account security". Sessions that are not needed anymore can be deleted here. The corresponding browser or device is logged out on-the-fly.

Two-factor authentication

The purpose of two-factor authentication is to maintain an additional level of security that prevents attackers form logging-in even if they compromised a users password. Therefore we strongly recommend to use it.

It can be activated during installation of the PBX or in the admin UI under PBX/Config/Authentication. If activated, the password alone is not sufficient for logging-in but the user must also verify the new session by

  • Confirming it in a dialog displayed on any existing myApps session.
  • Clicking a link that is sent to the email address configured at the user object.

In both cases a security code is displayed that should be compared to the one that is shown on the login screen of the new session. If it is the same the user can be sure that he is confirming his own login but not the possible concurrent login of an attacker.

The email account for sending the verification emails can be configured during installation of the PBX, in the PBX Manager plugin "Email" or in the admin UI under PBX/Config/Authentication.

If a user is notified about a login attempt he did not do, it means that the user password is compromised. The following should be done in such cases:

  • Reject the session (email link or displayed dialog)
  • Inform the administrator
  • Change the user password

Using Windows passwords

Instead of using the passwords configured at the user object, the Windows account can be used.

OAuth2 (recommended)
See Reference13r3:Concept_OAuth2_Windows_Authentication for details.
NTLM
See Reference13r3:Concept_Netlogon_and_myPBX_Windows_Authentication for details.

Logging out

In the installable version a logout can be done in the myApps menu at "Account security" / "Current session".

Resetting passwords

If the user has forgotten the password, he or she can set a new one by clicking the "Forgot password?" link on the login screen and completing an email verification process. This function can be activated or deactivated by the admin by configuring the link at "PBX"/"Config"/"myApps"/"Reset Password Page" or - more conveniently - using the PBX manager plugin of the innovaphone Users App that provides the functionality to change the configuration by pressing OK and then Enable or Disable various options like the password reset option.

Brute force protection

myApps does several things to mitigate and detect brute force attacks on user accounts.

  • After an attempt to log-in using a wrong password, the corresponding user account is locked for 0, 0, 8, 16, 32, 64, 128, 256, 512, 1024 seconds. In that time no more user logins with that account are possible. Logins using sessions that have been established before, are not affected.
  • If there is a login attempt with a wrong password, the user is notified inside all existing myApps sessions. There the user can tell that it was him in order to reset the counters and unlock the account.
  • From the third login attempt with a wrong password, events are generated to notify the administrator.
    • Event Code 0x0002000b
    • Severity Major
    • Example Text: 3 rejected login attempts for user johndoe from 192.168.0.53

Apps

App runtime

All apps are web applications that consist of

  • An HTML page
  • Javascript files
  • An app icon

myApps starts apps by opening the HTML page in an iframe. All communication between the apps and the myApps client is done using HTML5 window messaging. For example if the user changes the color scheme, myApps sends a window message to all open apps, so they can also switch colors.

App objects

All apps that appear in the myApps client must be configured in the PBX. For apps that are loaded from the innovaphone App Platform or any other external server an App object is used that contains all the needed parameters.

Name
An ID that must be unique per PBX domain. The ID is only used internally to reference that app and is not shown to the user.
Long Name
The display name of the app.
Password
The shared secret between the app instance and the PBX. It corresponds to the password configured at the app instance. This secret is used when a user is authenticated against the app.
URL
The base URL of the app. myApps appends .htm to get the URL of the HTML page and .png to get the URL of the app icon.
Icon URL
If configured this URL is used for the app icon, instead of deriving it from the URL.
Hidden
Some apps don't have a user interface. Their only purpose is to provide functionality (Client APIs) for myApps or other apps using window messaging. They have the "Hidden" flag checked at the app object and are not shown to the user.
Plain website
Checked if the HTML page is not an actual app that requires login and processes the window messages used for apps, but if it is just a regular website. This flag can be used to integrate websites into myApps via iframe.
Please note that this feature is meant for having a possibility to create simple content pages and integrate them into myApps without the need to develop a full-fledged app.
Note: Most existing websites cannot be integrated in this way because they do not allow you to load them into an iframe. Check Cross-origin resource sharing and Cookies SameSite settings with the owner of the website. If you miss some configuration, you should see an error message in your browser console.
Websocket
Some apps need a websocket connection from the PBX. This can be used to exchange additional information or to use APIs on the PBX. Those apps need the Websocket flag checked.

Some other PBX objects also provide apps, like the Boolean object.

App permissions

In order to use an app the administrator must grant the permission to the user. This can be done using templates of at the specific user object ("Edit Object"/"Apps"). The same setting can be done in the PBX manager plugin "Templates". The user will find the apps he has access to in the "All apps" view in myApps.

Special case: phone apps

If a user has access to the "phone" or "softphone" app, it will not automatically appear in "All apps". Those apps need to be assigned to a device at the user object and will then be used for the registration on those devices. The admin can configure the app name at the individual devices in the admin UI. The user can assign the app during provisioning of phones in "Edit profile".

Client APIs and default apps

Some apps provide APIs that allow communication with other apps. An app providing an API is called an API provider. Communication is done using HTML5 window messages sent to the myApps client that dispatches them to the right app.

If there are many providers for the same API, the app can send messages to specific provider, to all providers or let the user decide. In the latter case, myApps displays a selection dialog to the user. The user can also mark an app as the default app for an API that will then be used without asking again.

Additionally the user can configure the standard apps in the myApps menu.

The default apps are stored locally on each browser / device. So the user can have a different setting on each device.

Special case: phone API (com.innovaphone.phone)

The phone apps provide a phone API that can be used by other apps to start calls. If a phone app is selected as the default phone app it has the following effects:

  • When dialing a phone number (in a contacts app) the default phone app will be used for the call.
  • On incoming calls the phone app is started and displayed automatically, to handle the call.

If no default phone app is selected on a device

  • The user will be asked what phone app shall be used when dialing (in a contacts app)
  • On incoming calls no phone app will be started

Regardless of the setting, the user can open any phone to start or receive calls.

The standard phone app can be also selected by longpressing the app tile on the home screen.

Home screen

The home screen contains tiles that represent apps or items from apps - generally speaking links to apps. For example the user can place his phone app next to a contact from a contact app. Those tiles can be organized in named groups that can be collapsed, if they are currently not needed.

The presentation of a tile contains an icon, the name of the app or item and optionally a presence and a badge count provided by the app.

There are two ways for the user to add new items to the home screen:

  • Click the home symbol at an app in the "All apps" view.
  • Click an attach icon at an item inside an app.

Apps can be removed again the same way or by longpressing the tile and clicking "Remove from home".

Storage and format

The home screen is stored at the user object in the PBX and is synchronized over all sessions of the user.

The admin can see and configure it in the admin UI at "Edit User"/"User"/"Home Screen Apps". It is a comma-separated string of app links.

The string is limited to 8KB. If the limit is reached no more items or groups can be added to the home screen.

Format: Items starting with a colon are groups. Items starting with two colons are collapsed groups.

For example :Apps,chat,users,::Contacts,users?id=jdo#d=John%20Doe&s=jdo.

corresponds to

  • Apps (group)
    • Chat
    • Users
  • Contacts (collapsed group)
    • "John Doe" from the app "users"

All apps

This page in myApps shows all apps that the user has access to (see: App permissions). Apps that are often used can be attached to the home screen.

Edit profile

An app for managing the user profile can be configured in the admin UI at "PBX"/"Config"/"myApps"/"Edit Profile App". Typically the profile app provided by the innovaphone Users app is used for that. If configured, a menu item "Edit profile" appears in the myApps menu.

Tutorials app

The administrator can define an app providing tutorials or other help for end users. That app will appear in the hamburger menu of myApps as "Tutorials".

Requirements:

  • Create an app object pointing to the corresponding web page (eg. https://www.innovaphone.com/myapps/tutorial.htm) via the Adv.GUI, PBX, Objects, create new App Object with a name (eg. Tutorials)
  • Give users access to that app, preferably using templates (eg. Conf Users).
  • Configure the app name in the admin UI "PBX"/"Config"/"myApps"/"Tutorial App" with the previous created name (eg. Tutorials).

Note: This configuration is synchronized with the client when the connection is established. So a restart of myApps is needed for the tutorials app to appear in the hamburger menu.

When installing a new PBX, a tutorial app provided by innovaphone is configured by default. It points to https://www.innovaphone.com/myapps/tutorial.htm and shows videos about the usage of myApps.

Privacy and Datastorage

myApps will store the following data on your local device:

  • appclient-username / appclient-password
Auth token from the user session on this device (This is not the password itself, only a random token).
  • appclient-model
Offline-files from myApps which contains the personal user data (eg. Home screen configuration and Push tokens).
  • appclient-config
URLs and credentials for local services (credentials will be new generated randomly on every startup)
  • appclient-usr-XXXXXXXXXXXXXXXXXXX
anonymized environment settings of all historical user sessions (eg. theme, element size of home screen elements, language)

Additionally, it is allowed to every App to create own offline files or create local settings which will be stored also.

The Chromium Cache and DOM Storage (myApps for Windows) will be stored in $USER\AppData\Roaming\innovaphone\myApps\chromium\cache

Idle Bandwidth

myApps

The myApps client opens a single Websocket connection to the PBX. When the connection is idle, the PBX sends just a Websocket PING/PONG every 60s. Note that the PING/PONG exchange prevents TCP KeepAlive Messages, so there is no additional load for it.

 Message     IP header   TCP header    TLS payload   Total bytes
 PING        20 bytes    20 bytes      31 bytes      71 bytes       
 PONG        20 bytes    20 bytes      35 bytes      75 bytes
 ACK         20 bytes    20 bytes      -             40 bytes
 ------------------------------------------------------------------
                                                    186 bytes / min
                                                 11.160 bytes / h
                                                267.840 bytes / d

Apps

Most apps also open a Websocket connection to the PBX or App Platform and also use the PING/PONG mechanism. So the idle load is identical to myApps.

 Message     IP header   TCP header    TLS payload   Total bytes
 PING        20 bytes    20 bytes      31 bytes      71 bytes       
 PONG        20 bytes    20 bytes      35 bytes      75 bytes
 ACK         20 bytes    20 bytes      -             40 bytes
 ------------------------------------------------------------------
                                                    186 bytes / min
                                                 11.160 bytes / h
                                                267.840 bytes / d

There are some apps - like the phone apps - send a Websocket message {"mt":"KeepAlive"} on application layer every 60s to the PBX to dectect connection problems faster. Note that sending the message both prevents PING/PONG by the server and TCP KeepAlive, so there is no additonal load for it. In that case the idle bandwith can be calculated like follows.

 Message     IP header   TCP header    TLS payload   Total bytes
 KeepAlive   20 bytes    20 bytes      53 bytes      93 bytes       
 ACK         20 bytes    20 bytes      -             40 bytes
 ------------------------------------------------------------------
                                                    133 bytes / min
                                                  7.980 bytes / h
                                                191.520 bytes / d

Troubleshooting

The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function console.log). In most browser this is available as Console after pressing F12.

The myApps platform services provide more elaborate tracing mechanisms. See Troubleshooting in Concept myApps platform services.

Related Articles

Known Problems

Known Problems