APPS ARCHITECTURE
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:
1. Store static artifacts and resources used by our apps (CSS, javascript, html content). Most KWizCom apps load some or all of their code from the CDN. This makes the publishing and deployment of new app versions a lot faster and easier and allows us to keep up with continuous updates that are being published to SharePoint Online by Microsoft and address changes as needed.
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
KWizCom Apps are implemented as SharePoint-hosted apps, coded in javascript, running in the client browser. Most of the code is not hard-coded in the app itself, but is downloaded from apps.kwizcom.com CDN (CSS, JS, Html content).
This way customers do not need to manually update their installation every time we publish changes and fixes. Products that require custom logic in the list item forms (such as New, View or Edit item forms) use JSLink functionality to enhance the experience based on the built in out of the box forms.
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.
Data Flow
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 appis aSharePoint-hostedapp, itisasubsitewithinyourSharePoint.
2. Thelandingpagedownloadsartifactsfromapps.kwizcom.comCDN(CSS,JS,Htmlcontent)
3. A request is made to the KWizCom Foundation app – to make sure the Foundation is installedcorrectly.
Information sent by the app: user context (for OAuth login, handled by Microsoft), and thecurrent site URL. At this point, all KWizCom Apps Foundation does is check if it has access to that site underthat user, toensureitwas
configured correctly.
4. Arequestismade tothe licensingservice. Information sent by the app: The site ID and username are sent to check if there is a license underthesite,userordomain.
*Wehavenotedarequesttoavoidsendingtheusername incaseswhereasitelicenseexists.
5. The user configures the app, the app pulls information from SharePoint using client-side objectmodel 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 sameAPIs.
6. Oncethe userisdoneconfiguringtheappandsaveschanges:
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 itrather thancreatea newone).
b. Theclientprovisionsa .jsfileto“SiteAssets”(usuallyasimpleloader/bootstrapfile)
c. The client makes a request to the KWizCom App Foundation to configure the application.Informationsentfromtheapptothe KWizComAppsFoundation:
1) Usercontext,siteURL– used byOAuthforauthenticatingthe app.Thisis apartof Microsoft’sprovider hostedappsarchitecture.
2) The product’s SKU, the list id. This information will tell KWizCom App Foundation whatneeds 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 runonall pagesneededforthis 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.
2. That .js file then loads any additional artifacts from apps.kwizcom.com CDN (CSS, javascript, Html content) that it requires to run.
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)
Next
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
2) Local JavaScript is reading the settings object and enforces these settings on the list forms as needed.
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.