Course13:IT Advanced - 04 The Application Platform: Difference between revisions

From innovaphone wiki
Jump to navigation Jump to search
No edit summary
Line 1: Line 1:
{{#moodlebook: Master Templates / V13 Templates / Advanced | The Application Platform | 131 }}
{{#moodlebook: Master Templates / V13 Templates / Advanced | The Application Platform | 133 }}

Revision as of 15:02, 28 March 2023

More on the design of the AP. Stolen from the optional book found in the IT Connect training.

More on the design of the Application platform

In this book, we will look at the design, implementation and configuration of the App platform in more detail. To do so, we'll discuss a theoretical overview first and then setup an AP from scratch.

This first chapter will walk a little through the theory of Apps, App services and App service instances as implemented on the application platform.

If you have worked your way through the optional Design of the Application Platform book in the IT Connect training, it should sound familiar to you wink

myApps

As you have seen in the IT Connect course, the myApps client allows you to organize Apps conveniently (see also the link_intern.png Getting Started with myApps videos).


myApps itself is a web application (actually a web site hosted on your innovaphone PBX). It uses HTML5 (with DOM Storage) and JavaScript. As such, it runs inside a window (or tab) of a browser.


As long as this browser is a fairly recent one (so that it supports all the latest greatest tech stuff we use), this is all you need. For more details regarding the requirements, see fish-help.png Concept myApps. We are testing myApps and our own Apps on
  • Chrome
  • Firefox
  • Safari
  • and Edge
But other browsers may work too (subject to the requirements mentioned above).

Login

The first thing myApps will do is to log in to the PBX. For this, it will ask you for your credentials. However, it will do so only for the first time. The next time you start myApps in this browser, it will not ask again.

While this sounds (and is) convenient, the question is: how does that work? Does myApps store your credentials somewhere on your PC. The answer is: not really.

When you log in, myApps will use your credentials to request a so-called permanent session for you. This session will have a session id and a session password (which is different from your user password). These two are valid credentials for you just like your username and password is!

Session id and password are stored in your browser's DOM storage (this is like a little database your browser has). When myApps is started on the same browser again, instead of asking for your credentials, it will retrieve the permanent session properties from the local DOM storage and use them to log in to the PBX.

The PBX will store a limited number of permanent sessions per user (currently 8, but this may change) so you can have multiple browsers (like on your PC and on your mobile) which are logged in to the PBX with myApps. When more permanent sessions are created than can be stored in the PBX, the oldest one is silently discarded in the PBX. In this case, when you start the browser that used this session, the PBX will reject the permanent session id and myApps will ask for your credentials again.

Of course, neither the real user credentials nor the permanent session properties are sent over the wire in clear. Also, users can screenshot.png see the permanent sessions currently stored in the PBX for them and delete them if needed.

Login attempts are verified by the PBX against the passwords stored in the PBX user database by default. However, 3rd party Authentication providers (e.g. Active Directory) can be used based on fish-help.png OAuth2 or fish-help.png Netlogon.

How myApps talks to the PBX

The myApps HTML5 and JavaScript code of course is received with some HTTP GET requests. This is how browsers work.

However, once it is loaded and starts up, myApps will establish so-called WebSocket connections to the PBX. These are like normal HTTP connections initially (that is, they are initiated with an HTTP GET request) but upgraded to a bidirectional, asynchronous connection later on.


There is no need to understand in very much detail what a WebSocket connection is and how it differs from plain HTTP. But you should note that
  • it starts as HTTP (so it will use the same ports)
  • it is asynchronous (that is, messages can flow from the client to the server and vice versa at any time)
  • the message content is encoded in JSON format
  • your firewall may have a problem with it wink


Debugging myApps

When myApps doesn't start up properly it's time to debug what is going on.

Of course, you could use WireShark to sniff the network traffic. But myApps usually uses HTTPS, so you will see encrypted traffic which won't tell you that much. Fortunately, all these modern browsers have nice debugging tools built-in. In most of them, you can open those by pressing F12. The screenshots used in this book are taken from a Firefox browser but other browsers provide similar features.


When you press F12, your browser tab will be split and a bunch of tools are shown which allow you to debug.

The Network tab

We're initially interested in screenshot.png the Network tab to see if myApps is able to establish the websocket connection to the PBX. For this, we filter the traffic to be shown to WS (WebSocket) only. There should be a request from the browser towards https://hq.dvl-ckl2.net/PBX0/APPCLIENT/<some-number>/websocket (assuming your PBX's DNS name is hq.dvl-ckl2.net).
  • the domain name in the Request URL tells you if myApps knows the correct PBX name
  • the Remote address tells you if your DNS correctly resolves this name
  • the Status code: 101 Switching protocols tells you that the PBX recognized the request and upgraded the connection to websocket
To see what happens within this new connection, we switch to the Console tab.

The Console tab

In screenshot.png this tab, you can filter the messages shown by type. Select Logs and Requests for now.

myApps will log all incoming (recv from pbx) and outgoing (send to pbx) websocket messages along with their content for you. Fortunately, the JSON encoding is pretty self-explaining, so you can just read what is in the messages.

The first message is sent to the PBX and looks like {"mt":"Login", "type":"user", "userAgent":"myApps (Firefox)"}. JSON messages consist of a number of name/value pairs separated by a colon (:). So here we have
  • mt/Login
  • type/user
  • userAgent/myApps (Firefox)
The mt name stands for message type and you will see it in just any message that is sent or received. Here it is Login, so this is the begin of a fresh login (using the user's real credentials, a subsequent login using a permanent session looks a bit different).

The PBX responds with an Authenticate message (recv from pbx: {"mt":"Authenticate","type":"user","method":"digest","domain":"dvl-ckl2.net","challenge":"ec6af491ab3e622c"}). myApps now does a little voodoo based on the information in this message and your credentials and then sends a new Login message to the PBX which includes the result of the voodoo (send to pbx: {"mt":"Login", "type":"user", "method":"digest", "username":"ckl", "nonce":"36d5d54730485685", "response":"1a21e5f25622c16e7d6ca4675a94a396013d256ac5bbbf52ec84befbb2a8c871", "userAgent":"myApps (Firefox)"}).

Now the PBX is pleased and sends back a LoginResult message ({"mt":"LoginResult", "info": {"user": {"domain":"dvl-ckl2.net", "sip":"ckl", "guid":"c7fdf210727d5c0148250090334000b3", "dn":"Christoph Künkel", "num":"10", "email":"ckl@innovaphone.com"}, "session":{"usr":"67aba3887d21987e0b22c58d5e71bd6d18f034739acea7ba3c28d7424c6440fa", "pwd":"66930d771578eda5152c6261d6768ba8204b52728295bc"}}, "digest":"7910bdd91ac29816293cd46d786bf7eaba6d1908b991fbdd846f4565fcc9f328"}). This message includes the session property which contains the session id and session password for the new login.

If the login fails, the LoginResult message would look like so for example: recv from pbx: {"mt":"LoginResult", "error":2, "errorText":"Authentication failed"}.

For the next login (where the stored permanent session is used), the Login message would look like send to pbx: {"mt":"Login", "type":"session", "userAgent":"myApps (Firefox)"}, you can see that the type is set to session instead of user.

You might have observed that the Authenticate message received from the PBX included the method member set to digest. This is because the PBX used here uses digest authentication. Depending on the configuration, it could also use oauth2 or ntlm instead. The message details would be a bit different then but still, there would be a final LoginResult message with a good login.


Providing information for the innovaphone support

Browser trace

(Further Hints) When you run into problems with myApps and open a support ticket for this, you can simply copy the entire content of the Console tab and attach it to your ticket.

So
  • open the developer console with F12
  • clear the console window
  • reproduce the problem
  • save the complete content of the console tab into a file
  • attach the file to your ticket
More about creating a support ticket has been said in fish-help.png IT Connect - 11.1 How to create a support ticket as part of the IT Connect training.

    The launcher

    We already talked about the myApps launcher which provides some additional functionality.

    The launcher is an application that you install on your system just like any other application. It is currently available for Windows, iOS, Android and MacOS.

    Technically, the launcher is a screenshot.png separate program with a browser window internally. The myApps web code then runs in this window. Being a separate program (instead of just a website running in a browser) technically offers some more options. For example, the myApp launcher can listen to and handle keyboard events such as Hotkeys (for example to start a call when a phone number is selected in another application).

    In addition to that, there are screenshot.png several platform specific services such as
    • audio
      speaker/headset IO for the softphone
    • video
      native video (used instead of WebRTC video which is used if myApps runs without launcher)
    • ringer
      for ring tones
    • app sharing
      native app sharing supporting both sharing and viewing (used instead of WebRTC app sharing which is used when myApps runs without launcher only supports viewing)
    • outlook
      access to your local MAPI contact information
    More details about these platform specific services provided by the launcher can be taken from fish-help.png Concept myApps platform services.

    As you might already have guessed, the launcher screenshot.png talks to these services via websocket connections.

    On a Windows platform, the myApps launcher comes with its own browser (which is known as wikipedia.ico Chromium). On iOS and Android, the systems native browser is used.

    Providing information for the innovaphone support

    Browser trace
    On Chromium however, F12 does not work to open the developer console. Instead you would right click in the launcher and screenshot.png select Inspect.

    So
    • open the developer console with right-click on the myApps launcher window
    • clear the console window (right click on the console tab and Clear console)
    • reproduce the problem
    • save the complete content of the console tab in to a file
    • attach the file to your ticket
    myApps trace files
    If more information is needed, support may ask for "myApps trace files". There is a link Open trace file when video2.png you right click on myApp's tray icon. This will open myApp's working directory. You can simply zip all the files in there and attach them to your ticket.

    This is what is meant when the support guy says "can I have the myApps trace, please".

    Support may ask you to change the trace levels. This is done video2.png in the extended myApps settings. When you tick the Browser check-mark here, all log messages sent to the browser's developer console are also copied to the trace file. It should always be checked therefore.

    Apps

    The myApps client (either running in a web browser or in the launcher) does not provide any application functionality. Functionality is provided by so-called Apps.

    An App is a piece of web- and JavaScript code that is started by myApps and runs in the same browser tab as myApps does (for the HTML geeks: it runs in a separate IFRAME). It can communicate with the myApps client (using inter-window messaging in JavaScript).

    When an App is started, it can safely assume that the user is successfully logged-in to the PBX (as otherwise, it would not be started by myApps). This provides a convenient single sign on for all Apps running in myApps.

    The app can, in addition to being loaded from its App Service, establish a websocket connection to the App Service. With this connection it can exchange service specific messages with the App Service.

    Apps are loaded either from the PBX (then they are known as PBX Apps) or from an App Service. An App Service is a web service program running on the App Platform. The App Platform is a very light-weight, high performance Linux system running either on our latest gateway generation (IPxx11 or up) or in a Virtual machine (such as VMware or Hyper-V). Finally, Apps can talk to the PBX and/or their App Service using websocket connections.

    An App Service serves as a web server to download the App code from and also has a websocket interface that provides application related services.

    So here we have a screenshot.png fuller picture



    A single App Service can provide multiple Apps. You have already seen this with the Users and the UsersAdmin App. These are two different user interfaces provided by the same App Service (which makes sense, as both deal with the management of user information).

    App Instances

    Strictly speaking, Apps do not talk to App Services. Instead, they talk to App Service Instances. These are instances of the same service (that is, they provide the same HTML- and JavaScript-code as well as the same set of messages to be exchanged in their websocket connections). However, different App Service Instances work on different data. All persistent data (service data and configuration) of an App Service Instance is stored in a separate database on the App Platform (no files used).

    App Service Instances are identified by a domain name. Technically, this could be just any identifier. However, the Install creates all instances with a domain name that matches the domain name of your PBX (so it is dvl-ckl2.net in your case). But you could create additional instances from inside the App Platform manager (known as Apps in myApps). In normal installations you would rarely create multiple instances.


    Multiple instances can be used in multi-tenant installations, where a single App Platform may serve multiple customers. You would create one instance per App Service and customer and you would use the customer PBX's domain name to identify all the instances that serve a single customer.

    We have seen another application of multiple App instances before with the Files App. To avoid exponential growth of backup files, the install creates 2 instances of the Files App (called Files and Backup Files). The screenshot.png only configuration difference between those 2 instances is that Backup Files has the Exclude from overall backups check-mark set, so that the backups are not included as part of the next overall Apps backup.

    Domains in Devices
    Although you could do the same for the Devices App Service (create multiple instances as shown in the picture above), you normally would not. Instead, you would create multiple domains inside one single Devices Instances. This instance then knows about all devices of all tenants, which is convenient and also has improved performance (as multiple instances would also result in multiple databases used whereas the shared approach in Devices works with a single database (as only one instance is used)).

    The manager

    So far, we have seen that the Application Platform consists of a very light-weight Linux kernel where instances of App Services run. As you might expect, an App Service corresponds to a Linux process (note that an instance is not a process, all instances of a single service run in the same process). In addition to that, we also have 2 basic processes: a web server and the manager.

    The web server does what you would expect: it receives web requests and forwards them to the appropriate App Service.

    The manager is a bit like an App Service, except that it never has multiple instances and it already exists, when the bare Application Platform has been installed.

    It is responsible for installing, removing, starting and stopping of the App Service processes and instances. Also, it provides functions such as backup and restore of App Service instances. When an App Service is installed, the corresponding executable is copied to the system. When an instance is created, its database is created.

    So now we have a pretty complete picture of the screenshot.png App Platform's structure.

    You have access to the manager's user interface with the screenshot.png AP Manager App. You can also access the manager directly using your App Platform's IP address or domain name (for you, this would be http://apps.dvl-ckl2.net/ or http://172.31.31.12/ but it doesn't work yet, as we have not yet installed the AP). In this case, you will be asked for a password. By default this is simply pwd. Normally, the Install would replace it with the random password chosen during the install process. However, as you might recall, in our trainings, we run the Install in a somewhat special mode where the default passwords are kept. So for you, the password is still pwd.

    APIs

    As we said before, Apps communicate with the myApps client (using HTML5 Windows Messaging). Through windows messaging, myApps itself offers a number of service functions for Apps. A set of such functions is known as API and has a distinct name (for example, the API that myApps offers is known as com.innovaphone.client). Apps could connect to this API and send requests to this API and myApps would execute those on behalf of the calling App (for example, by sending a { mt: "SetAttachedToHome", reference: "id=13#s=doe&d=John%20Doe", attached: true } message to com.innovaphone.client, a link to an object managed by the calling app would be placed on the users home screen). A calling App is known as API consumer.

    Apps can register as API provider with myApps too. For example, myApps knows of an API called com.innovaphone.search. This API has some messages to search for users given a name (Search) and to return search results (SearchInfo). While the phone App registers with this API as a consumer, the users and contacts App register as provider. So when the phone App searches for a user, it would send a Search message to the com.innovaphone.search API which includes the search string. myApps would dispatch this message to both the users and the contacts App. Also, it would forward incoming results from both (SearchInfo) back to the phone App.


    Finally, Apps can also register their own APIs with myApps. This could be useful for a 3rd party App for example that wants to expose its services to other Apps.

    Access to APIs

    As an administrator, you do not need to care about APIs - except for one thing: access to API providers is user-based and must be granted to users just like access to Apps must be granted to users. It is not the App that consumes an API that needs access to the API provider. It is the user. And it is not the API the user needs access to. It is the API provider.

    When for example the phone App sends a Search message to the com.innovaphone.search API and the user has no access rights to the usersapis API provider, myApps would simply not forward this request to the usersapis API provider (which is part of the Users App) then the phone App would not be able to find any PBX user. Or, the other way round: the administrator must grant users access to API providers.