KWIZCOM APPS GENERAL ARCHITECTURE
All KWizCom apps for SharePoint/SharePoint Online are implemented the same way, utilizing KWizCom’s Apps framework. This framework includes the following ingredients: KWIZCOM CDN
The KWizCom CDN is at apps.kwizcom.com, located on AZURE, serving all KWizCom apps for several purposes:
2. License service. Used to check for user license when a user visits a page which is configured with KWizCom apps. The site ID and user login will be sent to this endpoint, via SSL:
a. If a site collection license exists, the username will not be sent.
b. If a site collection license was not found, a second attempt containing the username will be made to look for a domain or user license.
KWIZCOM APPS FOUNDATION
KWizCom Apps Foundation is a vendor-hosted app that provides services to all KWizCom apps to enhance their feature set. This app has no end-user interface, it is a utility app, providing services to other KWizCom apps "behind the scenes". This web application is hosted on azure and available in multiple geo-locations.
The web application authenticates to SharePoint in one of 2 ways:
1. Using Azure AD authentication This is the new authentication model, allowing a tenant admin to grant access to KWizCom apps without the need to install or update a package. Trust is granted tenant-wide to all SharePoint sites.
2. Using a SharePoint provider hosted app model (ACS) This is the legacy authentication model, which requires a SharePoint admin to install a SharePoint app into the app catalog and deploy it either on an entire tenant, or to a specific site collection.
The apps foundation web application is used to provide services to our apps, such as:
1. Provisioning and configuration: perform setup tasks that cannot be made using client-side code.
a. User-initiated configurations will always authenticate the user first and run under the user’s authentication token.
b. Automatic provisioning operations, such as provisioning pages that run on the application context do not accept user input, and independently validate and verify the configuration needed.
2. Host event handlers that might be needed by some products logic.
a. Event handlers are triggered by SharePoint and the event information is verified.
b. Since event handlers run on the application context, the event handler does not accept any input parameters (if any are sent they are ignored), and instead the event handler independently verify what operations are required to do.
c. For example: Configuring a status field to be set to “New” when an item is created in a list
i. An item is created and an event handler is called
ii. The event handler will access the site to load the configured actions for the list
iii. The event handler will find an action to update a status field
iv. The action will be processed as configured, the status field will be set to “New”
d. This prevents attackers from being able to actively ask to run an action (such as update a field) by accessing the endpoint.
i. The event handler will fail to validate
ii. The attacker will have to have gained access to the site and be able to create a configuration file for the action he wishes to perform, meaning the attacker would have to have write access to the site already
HOW KWIZCOM APPS ARE BUILT
SharePoint Classic Experience
SharePoint Modern Experience
KWizCom Apps rely on SPFx packages to expose capabilities to the site. Products that require custom logic in the list item forms (such as New, View or Edit item forms) will replace the built in out of the box forms with KWizCom custom forms page to provide the added functionality. All KWizCom apps interacts with KWizCom Apps Foundation and with the KWizCom license service modules.
This section describes what requests are made and what data is passed during the various usage events, after the KWizCom app is installed.
END-USER VISITS app settings page to configure the app
1. Since KWizCom app is a SharePoint-hosted app, it is a sub site within your SharePoint.
2. The landing page downloads artifacts from apps.kwizcom.com CDN (CSS, JS, Html content)
3. A request is made to the KWizCom Foundation app – to make sure the Foundation is installed correctly.
Information sent by the app: user context (for OAuth login, handled by Microsoft), and the current site URL. At this point, all KWizCom Apps Foundation does is check if it has access to that site under that user, to ensure it was configured correctly.
4. A request is made to the licensing service. Information sent by the app: The site ID and username are sent to check if there is a license under the site, user or domain.
* We have noted a request to avoid sending the username in cases where a site license exists.
5. The user configures the app, the app pulls information from SharePoint using client-side object model between the user browser and the SharePoint server directly, not going through KWizCom’s servers. This is the same approach that SharePoint itself is running under, using the exact same APIs.
6. Once the user is done configuring the app and saves changes:
a. The client creates a JSON settings file and uses SharePoint API to upload it to the parent site’s “Site Assets” library (it would first try to load this file if already exists to apply changes to it rather than create a new one).
b. The client provisions a .js file to “Site Assets” (usually a simple loader/bootstrap file)
c. The client makes a request to the KWizCom App Foundation to configure the application. Information sent from the app to the KWizCom Apps Foundation:
1) User context, site URL – used by OAuth for authenticating the app. This is a part of Microsoft’s provider hosted apps architecture.
2) The product’s SKU, the list id. This information will tell KWizCom App Foundation what needs to be configured on which list. KWizCom App Foundation confirms the requesting app is installed on that site and registers the .js file that was uploaded to “Site Assets” to run on all pages needed for this list.
END-USER VISITS THE LIST WHICH WAS CONFIGURED
In classic experience
1. The app’s .js file is loaded from “Site Assets” and running from the client PC.
In modern experience
1. The user is redirected to KWizCom’s custom form page.
2. The form page uses an SPFx package to register and call KWizCom forms logic which is hosted on KWizCom’s CDN (apps.kwizcom.com)
1. All code executes on the client’s browser, and no information is sent through KWizCom servers. The client’s browser communicates directly with SharePoint’s server-side API.
2. A request is made to try to load the settings file for this list/product, according to the following logic:
a. File does not exist? Do nothing.
b. File exists?
1) The settings file is loaded from “Site Assets” into the browser, parsed as a JSON object
3) A request to apps.kwizcom.com license service is made to check for user license. The response of this request is cached in an in-memory-cookie so it won’t be made again until the browser closes.
Note: at this stage, apart from downloading some JS/CSS files from apps.kwizcom.com, all code and logic is running on the user’s browser and uses SharePoint client-side object model to communicate directly with SharePoint.