The purpose of this document is to establish the base installation and configuration for Akumina Headless V2.
- Stack: .NET 6 (LTS)
- OS: Linux or Windows
The following are the prerequisites:
- Akumina Headless release file (.Zip format)
- Template files (.Zip format)
- AppManager 5.5 latest release
- If upgrading from prior 5.5 (.1709)
- Click on upgrade next to each option
- SharePoint site collection
- 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)
- 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)
- Create a website
- Extract the Zip to the site root
|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”|
|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 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)
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:
- Go to AppService, enable Identity
- Go to KeyVault and setup Access policy
- Enable AppService Identity as Read Access to keys and secret
- Copy the secret Url (without the version)
- 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).
- 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
To load sites in headless, configure sitesettings:
- Navigate to admin/sitesettings
- 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.
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.
|TemplateUrlPrefix||This is a required configuration which must be specified up to container name, template prefix is optional.
*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:
*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.
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.
- Enable Identity to Headless Web App (Go to Headless Web App > Identity > Enable)
- Copy the value then go to Headless AppSettings Key Vault from the access policies enable “Get and List” for the above Service Principal.
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.
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
Headless offers multiple ways to connect back-end systems. In this case, SharePoint Rest APIs, the supported connection modes are:
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
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
- Navigate to Azure Active Directory and create a new App, then configure as shown below:
- Permissions required by Service Account Apps (if UseAppId is set to true)
- Create a JSON text in the following format
|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
- 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.
- Go to tenant settings and update the field “ServiceAccounts”
For Key Vault Uri enter the Uri (refer to the previous step)