System Overview

Version: 0.3

July 2025

Introduction

Purpose

The purpose of this document is to give an overview about the software system Layer2 ShArc regarding its structure and other technical aspects, such as security and scalability concerns.

Scope

The document contains a technical overview of the system and its interactions with other systems. It does not contain implementation details.

Audience

The intended audience for this document are administrators, technical consultants and security experts, interested in leveraging the system by integrating it in their infrastructure.

Application

Motivation

Enterprises which employ Microsoft SharePoint as a means of collaborating on documents and other files inevitably experience a growth of the amount of files over time, leading to an increase of storage demand. Even though the available licenses for Microsoft SharePoint do include a certain amount of storage, as soon as this quota is exhausted, further storage capacity needs to be purchased. At the time of writing, the pricing for additional storage capacity greatly exceeds the market rate of most storage offerings.

Layer2 ShArc seeks to alleviate the financial impact by offering a solution to offload file contents onto a different storage, with the following secondary goals in mind:

• Minimizing the impact on the user experience
• Minimizing the coordination between users, who want to keep access to their files, and administrators, who want to offload as many files as possible

Solution

At the core of the solution is the introduction of stub files. These are files kept as a placeholder in the respective SharePoint libraries, in place of the offloaded files. In many respects the stub file is the offloaded file, albeit modified regarding its content and name. The stub file is a URL file? which contains a link to the Layer2 ShArc onloading endpoint. As a users click on the file, they will be redirected to the onloading page, which informs them about the file being onloaded and as soon as the onload is finished, they will be redirected to the original file.

This approach has several advantages:

• As the offloaded file is not replaced, but rather only modified, a lot of its context is maintained, including
  • The ID of the file's list item in the library
  • All of the file's metadata
  • The location of the file inside of the library
  • The bulk of the name of the file (With the exception of the additional .url extension)
• The users experience is only minimally altered: They can still click on it to open it with only an intermediate step of the onload screen being shown
• The stub file can still be modified as if it was the original file regarding editing metadata, moving or deleting the file, etc.

Architecture

ShArc Server with optional Alert Rules

Azure Tenant

The entire system is intended to be deployed inside of a customers own Microsoft Azure tenant. The main reason is that this way, files which are offloaded will never leave the customers cloud environment. Additionally this allows for a fast transfer if all Azure resources are deployed in the same region and the customer keeps the freedom to adjust how the infrastructure is configured in terms of sizes, tiers, security, redundance and scalability.

ShArc Server

The server is the main component of the system. It consists of a containerized web application hosting a web frontend as well as a backend API, both of which are accessed through the HTTPS? protocol. The containerization model allows for maximum flexibility when it comes to hosting the application. The server backend is where the onloading and offloading is processed. It accesses both SharePoint and an Azure Blob Storage? instance to transfer the files between them. The ShArc server also includes a Log Analytics Workspace as well as alert rules and an action group. The Log Analytics Workspace is used to monitor and analyze the history of key operations such as offload, restore, etc. This enables administrators to gain insights into system usage and behavior. The alert rules and action group help proactively respond to issues.

ShArc Client

The client is a Single Page Web Application (SPA) which is served from the ShArc server but runs entirely inside the browser of the user. It represents the user interface for offloading and onloading files.

Azure Blob Storage

The Azure Blob Storage is the storage where offloaded files are kept. There are no special requirements demanded by the system as to how the Storage needs to be set up, other than there must be a blob container which can be configured through the ShArc Client.

Entra ID

The system uses Azure Entra ID to facilitate authentication and authorization on all parts of the system, including the client, the server and SharePoint

Security

All communication is channeled through the HTTPS? protocol, which ensures encryption of the data transferred.

Authentication and authorization are implemented using OAuth 2.0? with Entra ID? as the authentication server. The client performs the OAuth Authorization code with PKCE? flow, which is at the time of writing the most secure way of protecting SPAs. Through this OAuth flow, secure access token and refresh token are obtained, before a user can perform any interaction with the UI. As long as the user keeps interacting with the UI, the access token will keep being refreshed at least every hour by utilizing the refresh token. On prolonged inactivity, the user will need to re-authenticate.

Calls which are sent from the client to the server are expected to contain a valid access token, which will be ensured by validating the provided token on every server call. This prevents any direct calls to the server API without the caller being identified and proven to have permissions.

The UI is only accessible for users which are SharePoint administrators, specifically either SharePoint Administrator? or Global Administrator?. Only the onloading screen is allowed to be accessed by all users which have permissions to access SharePoint.

Scalability

The Layer2 ShArc system itself is build to be highly scalable including scaling out as well as scaling up: It is possible to spin up multiple containers hosting an instance of the ShArc server and there are several options for scaling Azure Storage.

When it comes to scaling, SharePoint is expected to be the bottleneck in most cases due to its throttling mechanism ?, which is highly dependent on the SharePoint licenses and current load. There are several ways to reduce the impact of throttling, which are implemented by Layer2 ShArc, including:

• Minimizing calls necessary for operation
• Decorating calls with our ISV identification in the user agent header
• Handling 429 (Too Many Requests)? and 503 (Server Too Busy)? error codes taking into account the Retry-After and RateLimit? response headers or using exponential back-off as a fallback

Glossary