Headless V2 Installation

Overview

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

Runtime

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

Prerequisites

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)

Environments

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

Configuration

AppSettings

{ 

  “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”: { 

  } 

} 

AppSettings – Tenant Configuration UI

With the AppManager release of 6.0, the entire AppSettings can be managed through the KeyVault (System Level Config) using “AppSettings–>ConfigSection” and TenantSettings (Instance Level Config) for all other settings.

1. To configure the KeyVault, create the JSON attributes with values using the following format:

{ 

  “Logging”: { 

    “LogLevel”: { 

      “Default”: “Information”, 

      “Akumina”: “Debug”, 

      “Microsoft.AspNetCore”: “Warning” 

    } 

  }, 

  “AllowedHosts”: “*”, 

  “ApplicationInsights”: { 

    “InstrumentationKey”: “”, 

    “ConnectionString”: “” 

  }, 

  “AkAppSettings”: { 

    “MinWorkerThreads”: “50”, 

    “LogListener”: “AppInsight”, 

    “PrimaryRedisConnection”: “”, 

    “GraphGroupLimit”: 125, 

    “TenantId”: “”, 

    “ConnectionConfig”: { 

      “RemoteStorageConnection”: “” 

    } 

  } 

} 

2. Copy the Secret URI to headless AppSettings (refer to KeyVault section below) and store the key using AppSettingsSecretUri

3. Navigate to ~/tenant/config to configure the remaining app settings properties

4. After clicking save, the settings will be generated and stored in the following format, which the runtime will load.

{ 

  “AuthMode”: “OAuth2”, 

  “DataHubUri”: “”, 

  “TenantId”: “”, 

  “QueryKey”: “”, 

  “QueryAs”: “SigninAccount”, 

  “UseDefaultCredentials”: false, 

  “SitePrefix”: “sites/”, 

  “CdnVersion”: “local”, 

  “FrameworkVersion”: “local”, 

  “ImplementationVersion”: “0.0”, 

  “PeopleSyncProperties”: “Department,UsageLocation,DisplayName”, 

  “FetchUserPropertiesFromSharePoint”: true, 

  “SiteType”: “Hive”, 

  “TemplateURLPrefix”: “”, 

  “DataHubLoginUri”: “”, 

  “SkipSharePointUserProperties”: true, 

  “ModernSite”: true, 

  “CacheExpiration”: { 

    “Default”: “86400”, 

    “UserContext”: “3600”, 

    “SiteAccess”: “3600”, 

    “UserPersonas”: “600” 

  }, 

  “AdminAccess”: { 

    “Emails”: “”, 

    “Groups”: “” 

  }, 

  “AppInsightName”: “”, 

  “TrackingInstrumentationKey”: “”, 

  “TrackingAppId”: null 

} 

TemplateUrlPrefix

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 them to any storage account, and provide the path in appsettings.json “TemplateUrlPrefix”. You can also extract to the site root if you do not want to host externally. Please note that external hosting may be required for better developer experiences and performance.

Note – If you are using the Akumina Mobile app, then additionally add the DELETE in allowed methods.

KeyVault

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

Cors

• 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

SiteSettings

To load sites in headless, configure sitesettings:

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

Vanity URL

Vanity URL Is a concept to add a custom domain to your SharePoint site.  When In headless, the default site will have custom DNS, but the other sites will use the same DNS prefix and suffix with “sites/<YOUR SITE>”, using a vanity URL, you can define custom DNS for every suffix “sites/<YOUR SITE>” 

Pre-Requisites:

1. Define a domain (a subdomain in onakumina.com or any custom domain) 
2. Update DNS service to have record set 
3. Update the IIS/Web APP with hostname (host headers) 
4. Update Front Door entries  
5. Grant CORS access to the hostname in AppManager 

Configuration:

As an admin user, navigate to ~/admin/sitesettings to update the following highlighted section “Host name using host headers” 

Debugging

Debugging page is viewable by Admin users (refer AppSettings->AdminAccess). Once you log in as configured admin user, 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 the 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 Templates

Configuration

The 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, the ‘TemplateUrlPrefix’ field is not required and it will become disabled.

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

Storage Connection String

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

TemplateUrlPrefix

This field is required only when you are using the Storage Connection String. This field is not required when you are either not specifying 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 the 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.

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 and enable “Get and List” for the above Service Principal.

Manual Configurations

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 the “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

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.

ServiceAccount

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.

MixedAccount

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:

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

For a complete list of supported and unsupported features click here

ServiceAccount Credential Configurations

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

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

4. Store them in any file that ends with credential.json (for testing purposes only) or Key Vault Uri. Please note when using Key Vault, there 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.
5. Go to tenant settings and update the field “ServiceAccounts”