Headless V2 Installation - Akumina Community

Headless V2 Installation


The purpose of this document is to establish the base installation and configuration for Akumina Headless V2.


  1. Stack: .NET 6 (LTS)
  2. OS: Linux or Windows


The following are the prerequisites:

  1. Akumina Headless release file (.Zip format)
  2. Template files (.Zip format)
  3. AppManager 5.5 latest release
    • If upgrading from prior 5.5 (.1709)
    • /admin/db
      • Click on upgrade next to each option
  4. SharePoint site collection
  5. Azure Services – Headless Front End Runtine
    • Login to https://portal.azure.com
    • Select your subscription
    • Create Linux App / Service Plan (Windows App Service/ Service Plan), Log Analytics workspace, App Insight, Redis Cache, Storage Account, and Key Vault.  Please note that while creating App Service, make sure that the Publish, Runtime stack, and Operation System Is selected as shown below.
    • Identify Configuration
    • Scaling – P1V1 – Minimum – 1 CPU 3.5 GB RAM (GiB)


Azure App Service

Extract the zip, then upload the files to App Service ~/site/wwwroot using FTP.  You can download FTP credentials from Azure App Service.

Windows Server (Any cloud or on-prem)

Using Windows Server 2022/IIS 10 (ASP.NET Core Module v2)

  1. Install ASP.NET Core Runtime 6.0.2 (https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-aspnetcore-6.0.2-windows-x64-installer) 
  2. Create a website
  3. Extract the Zip to the site root




  “Logging”: { 

    “LogLevel”: { 

      “Default”: “Error”, 

      “Akumina”: “Error”, 

      “Microsoft.AspNetCore”: “Error” 



  “AllowedHosts”: “*”, 

  “ApplicationInsights”: { 

    “InstrumentationKey”: “”, 

    “ConnectionString”: “” 


  “AkAppSettings”: { 

    “MinWorkerThreads”: “50”, 

    “LogListener”: “AppInsight”, 

    “DataHubUri”: “”, 

    “TenantId”: “”, 

    “QueryKey”: “”, 

    “PrimaryRedisConnection”: “”, 

    “CdnVersion”: “”, 

    “ImplementationVersion”: “0.0”, 

    “CachePartitionKey”: “akfe:”, 

    “FetchUserPropertiesFromSharepoint”: false, 

    “TemplateUrlPrefix”: “”, 

    “PeopleSyncProperties”: “Department,UsageLocation,DisplayName,GivenName,objectId,JobTitle,Mail,MobilePhone,OfficeLocation,PreferredLocation,Surname,UserPrincipalName,BusinessPhones,City,State,Country,PostalCode”, 

    “CacheExpiration”: { 

      “Default”: “86400”, 

      “UserContext”: “3600”, 

      “SiteAccess”: “3600”, 

      “UserPersonas”: “600” 


    “AdminAccess”: { 

      “Emails”: “”, 

      “Groups”: “” 



  “AppSettings”: { 





Key Purpose
Logging Logging configuration section


Log Level, supported values are Verbose, Debug, Information, Warning, Error, Critical
ApplicationInsights This section is required for tracing


Instrumentation key from Azure Application Insight


Instrumentation Connection string from Azure Application Insight
AkAppSettings Akumina app settings


Preconfigures the number of min worker threads. DO NOT CHANGE


Supported values are “AppInsight”, “FlatFile”


SharePoint TenantId


AppManager Query Key


Required if you use more than one instance or more than one region.

If you leave this value empty, then the system will write caches into in-memory.



It is required if the Redis connection string is configured.

If you share your Redis across multiple applications, this will isolate key specifics to the current website.



Akumina setup and configuration engineer will provide this value


Static files hosted URLs (aka SharePoint Akumina Library contents); this can be the same as the headless host.

For more information, refer TemplateUrlPrefix section



Required to hard refresh static files from the external origin


Default is to read user properties from Directory synced data (aka PeopleSync Data); this may be required based on the attributes needed for your site. For better performance, leave it false (default).


Values required for directory control. The default values are “Department,UsageLocation,DisplayName,GivenName,objectId,JobTitle,Mail,MobilePhone,
Country,PostalCode” you can add any user synchronized properties
CacheExpiration CacheExpiration
CacheExpiration Default Default cache interval if specific cache interval is not provided
CacheExpiration UserContext UserContext cache interval
CacheExpiration SiteAccess Site access cache interval
CacheExpiration UserPersonas Persona object cache interval
AdminAccess Admin feature such as /admin/Debug or /admin/sitesettings
AdminAccess Emails Comma separate email address which needs to access debug or site settings
AdminAccess Groups Reserved for future release



Add New Azure Storage Container specific for the client (this will be done in the clients Azure)

Public Read

Cors Settings

Extract the files and copy to Any storage account, and provide the path in appsettings.json “TemplateUrlPrefix”. You can also extract to site root if you do not want to host externally. Please note hosting external may be required for better developer experiences and performance.



The entire “appsettings.json” content can be stored in a key vault secret. This is a preferred approach for high security and easy management when hosting applications in more than one region. To configure the headless web:

  1. Go to AppService, enable Identity
  2. Go to KeyVault and setup Access policy 
  3. Enable AppService Identity as Read Access to keys and secret
  4. Copy the secret Url (without the version)
  5. For AppServices (Linux or Windows) – Go to configuration then add a key name “AppSettingsSecretUri” and set the value as a secret Uri (without the version). 
  6. Stop/Start the web app


  • To enable Cors in AppManager, go to AppManager->Settings->AppSettings->Edit Origin to append the headless URL. (make sure https:// Is Included with no trailing slash)
  • TemplateURLPrefix hosted site must also be cors enabled for headless URL

Headless Config


You must complete Site Configuration in AppManager before visiting this section

To load sites in headless, configure sitesettings:

  1. Navigate to admin/sitesettings
  2. Add a default site (required)


Debugging page is viewable by Admin users (refer AppSettings->AdminAccess), once you logged in as configured admin user then navigate to ~/admin/debug


Front End Storage Configurations

This section explains how to configure the FrontEnd Storage settings In Tenant Config Settings. This configuration is required for following functionalities when AppManager is running in OAuth/Service-Provider Mode:

  • AppManager > Management Apps > View Manager
  • FrontEnd View Template Editing
  • Site Deployer for deploying the View Template’s


Following section has been added in Tenant Config Settings:

KeyVault Uri OR Storage Connection String

This field is optional and supports either KeyVault Uri or Storage Connection String.

KeyVault Uri

When you are using KeyVault Uri, ‘TemplateUrlPrefix’ field is not required and it will become disabled.

Make sure you have your configurations stored in the vault in following format.

Key Purpose
TemplateUrlPrefix This is a required configuration which must be specified up to container name, template prefix is optional.

Valid Examples:

  • https://[storage-acc].blob.core.windows.net/myfiles
  • https://[storage-acc].blob.core.windows.net/myfiles/v1
  • https://[storage-acc].blob.core.windows.net/myfiles/v1/fe

*myfiles is your container name

FrontEndStorageConnectionString This is required and must be a valid Azure Storage Account Access key

Storage Connection String

When you are using the Storage Connection String, you must specify the valid Azure Storage Account Access key


This field is required only when you are using the Storage Connection String. This field is not required when you are either not specifying the any value In ‘KeyVault OR Storage Connection String’ or using the KeyVault Uri

Make sure you specify the TemplateUrlPrefix upto container name, following are few valid examples:

  • https://[storage-acc].blob.core.windows.net/myfiles
  • https://[storage-acc].blob.core.windows.net/myfiles/v1
  • https://[storage-acc].blob.core.windows.net/myfiles/v1/fe

*myfiles is your container name


Updating the FrontEndSettings

When you are using the KeyVault Uri for storing the FrontEnd settings make sure you have Health Check enabled on AppManager App Service with following configuration.

When you update the new KeyVault Uri in Tenant Config Settings, Health check will propagate the changes across the App Service node

Alternatively, if you don’t want to use the Health Check, you must restart the AppService to reflect the new FrontEnd Settings.

This is not required when you are using the FrontEnd Storage Account Access Key and TemplateUrlPrefix in Tenant Config Settings instead on KeyValut Uri.

Granting Access to KeyVault

When you configure headless settings into Key Vault, make sure you enable Headless Identity with  “Get, List” permissions to Key Vault.

  1. Enable Identity to Headless Web App (Go to Headless Web App > Identity > Enable)
  2. Copy the value then go to Headless AppSettings Key Vault from the access policies enable “Get and List” for the above Service Principal.

Manual Configurations

Note: This is only required if you have granted Sites.FullControl and AllSites.FullControl permissions to the Azure AD application.

You need to have the site collection admin permission to perform this action on standalone/central delivery.

For the lists below, we need to add “Everyone” group with “Contribute” permission.

  • FormsSubmissions_AK,StepPlannerInstances_AK

And for the lists below, we need to add “Contribute” permission to the “Visitor” group.

  • PageWidgetsAK,PageData_AK,WidgetProperties_AK,DashboardDragDrop_AK,AppDisplayOrder_AK ,Comments_AK, MyDashboard_AK,NewIntranetFeedback_AK,IntranetSurvey_AK,NewsComments_AK


Account Mode

Headless offers multiple ways to connect back-end systems. In this case, SharePoint Rest APIs, the supported connection modes are:

  • SigninAccount
  • ServiceAccount
  • MixedAccount

Configured using “QueryAs” property from appsettings.json


SigninAccount is the Out of the box Mode, which runs on logged-in users’ delegated access. If the user has access, then returns the data; otherwise, access is denied.


In this mode, the logged-in user is different than the user querying the back-end store; In this case, SharePoint Rest Apis. It needs a list of pre-configured username and password credentials or AAD Application secret stored in credentials.json or a key vault URI.


If your headless needs to evaluate the current users’ license and attach only when the user doesn’t have a license, then It Is the best option. The headless Instance will run a license check and then attaches the context of SiginAccount or ServiceAccount.

For a mixed-mode account, license configuration Is required; otherwise, It will automatically change all users to the service account. To configure the SharePoint license, go to Settings–>TenantSettings, then update the following key with:

cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46,05e9a617-0261-4cee-bb44-138d3ef5d965,cdd28e44-67e3-425e-be4c-737fab2899d3,b214fe43-f5a3-4703-beeb-fa97188220fc,3b555118-da6a-4418-894f-7df1e2096870,dab7782a-93b1-4074-8bb1-0e61318bea0b,f245ecc8-75af-4f8e-b61f-27d8114de5f3, ac5cef5d-921b-4f97-9ef3-c99076e5470f,18181a46-0d4e-45cd-891e-60aabd171b4e,6634e0ce-1a9f-428c-a498-f84ec7b8aa2e,6fd2c87f-b296-42f0-b197-1e91e994b900,4b585984-651b-448a-9e53-3b10f069cf7f 



ServiceAccount Limitations

At this time, the following features are disabled when the headless renders in service account mode:

  • Tray Removed (hidden)
  • Add Page
  • Quick Content Edit
  • Permission Management in Discussions
  • Document upload in DMS/DocViewer
  • Ability to see Employee Profile from Streams
  • Like/Share in FS3/FS4
  • Add Comments in FS3/FS4
  • Profile Events in FS3/FS4

ServiceAccount Credential Configurations

  1. Navigate to Azure Active Directory and create a new App, then configure as shown below:

  1. Permissions required by Service Account Apps (if UseAppId is set to true) 
  2. Create a JSON text in the following format


UseAppId Description
False Individual licensed userId/Password sets must be configured as part of the Credential account. Please note Certificate is not required.
True In this case, the [USER ID] is your AppId, and [PWD] is your App Secret.

If a certificate is used, then [PWD] is the certificate password.

To avoid throttling, you may need to configure multiple apps; in this case, please use the same certificate and password for all apps.

To setup a certificate please refer Creating a Self Signing Certificate – Akumina Community

  1. Store them in any file that ends with credential.json (for testing purposes only) or Key Vault Uri. Please note when using Key Vault, thre is a size limitation of 254 KB; hence slice the file content into multiple files and refer to them as comma-separated. All files must retain the format.
  2. Go to tenant settings and update the field “ServiceAccounts”
Note: For file credentials provide fully qualified path ex.,c:/akumina/akumina.com-credential.json

For Key Vault Uri enter the Uri (refer to the previous step)

Views: 145