The purpose of this document is to establish the base installation and configuration for Akumina Headless V2.
The following are the prerequisites:
Extract the zip, then upload the files to App Service ~/site/wwwroot using FTP. You can download FTP credentials from Azure App Service.
Using Windows Server 2022/IIS 10 (ASP.NET Core Module v2)
For AppManager 6.0 and above, please refer to the next section "AppSettings - Tenant Configuration UI" to configure AppSettings using the UI.
{
"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 |
| Logging.LogLevel
Akumina |
Log Level, supported values are Verbose, Debug, Information, Warning, Error, Critical |
| ApplicationInsights | This section is required for tracing |
| ApplicationInsights
InstrumentaionKey |
Instrumentation key from Azure Application Insight |
| ApplicationInsights
ConnectionString |
Instrumentation Connection string from Azure Application Insight |
| AkAppSettings | Akumina app settings |
| AkAppSettings
MinWorkerThread |
Preconfigures the number of min worker threads. DO NOT CHANGE |
| AkAppSettings
LogListener |
Supported values are "AppInsight", "FlatFile" |
| AkAppSettings
TenantId |
SharePoint TenantId |
| AkAppSettings
QueryKey |
AppManager Query Key |
| AkAppSettings
PrimaryRedisConnection |
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. |
| AkAppSettings
CachePartitionKey |
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. |
| AkAppSettings
CdnVersion |
Akumina setup and configuration engineer will provide this value |
| AkAppSettings
TemplateUrlPrefix |
Static files hosted URLs (aka SharePoint Akumina Library contents); this can be the same as the headless host.
For more information, refer TemplateUrlPrefix section |
| AkAppSettings
ImplementationVersion |
Required to hard refresh static files from the external origin |
| AkAppSettings
FetchUserPropertiesFromSharePoint |
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). |
| AkAppSettings
PeopleSyncProperties |
Values required for directory control. The default values are "Department,UsageLocation,DisplayName,GivenName,objectId,JobTitle,Mail,MobilePhone,
OfficeLocation,PreferredLocation,Surname,UserPrincipalName,BusinessPhones,City,State, 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 |
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.
{
"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
If migrating from an existing system, the user must be part of the Admin group or contact Akumina Support to acquire a temporary access token to navigate to this page.
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
}
Note: If migrating to a UI based config from the existing system, make sure to remove all redundant keys from the previous AppSettings.config and KeyVault secret.
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.
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:
You must complete Site Configuration in AppManager before visiting this section
To load sites in headless, configure sitesettings:
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:
Please note if the domain is not "onakumina.com", you MUST contact Akumina Engineers to update your domain.
When the App Manager and Headless URLs have different top-level domains, cross-domain communication is subject to Intelligent Tracking Protection (ITP). ITP is a privacy protection in many browsers to block requests for cross-website tracking including third-party cookies blocked, cookies blocked, or when a user has multiple AD accounts.
For this reason, it is strongly recommended to have the Headless site and App Manager URL be on the same top-level domain, to prevent such issues with Safari and other browsers.
Configuration:
As an admin user, navigate to ~/admin/sitesettings to update the following highlighted section “Host name using host headers”
Debugging page is viewable by Admin users (refer AppSettings->AdminAccess). Once you log in as configured admin user, navigate to ~/admin/debug
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:
The following section has been added in Tenant Config Settings:
This field is optional and supports either KeyVault Uri or Storage Connection String.
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.
| Key | Purpose |
|---|---|
| TemplateUrlPrefix | This is a required configuration which must be specified up to the container name, template prefix is optional.
Valid Examples:
*myfiles is your container name |
| FrontEndStorageConnectionString | This is required and must be a valid Azure Storage Account Access key. |
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 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
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.
This is not required when you are using the FrontEnd Storage Account Access Key and TemplateUrlPrefix in Tenant Config Settings instead of KeyValut Uri.
When you configure headless settings into Key Vault, make sure you enable Headless Identity with "Get, List" permissions to Key Vault.
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 the "Everyone" group with "Contribute" permission.
And for the lists below, we need to add "Contribute" permission to the "Visitor" group.
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:
For a complete list of supported and unsupported features click here
| 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 is your AppId, and is your App Secret.
If a certificate is used, then 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 |
Note: For file credentials provide a fully qualified path ex.,c:/akumina/akumina.com-credential.json
For Key Vault Uri enter the Uri (refer to the previous step)