Reference13r3:Concept myApps
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.