This topic will cover installation of the AppManager and supporting resources in a new Azure webapp using Microsoft PowerShell scripting to automate much of the setup, significantly reducing the installation times.
The installation script will automatically:
- Create a resource group in Azure which contains the following:
- App Service Plan
- App Service (the AppManager web app)
- Storage Account
- Key Vault
- Create and configure the Graph API Connection for Azure AD
- Install the AppManager files AND configure it to access the Azure Storage Account using the secure Key Vault URL
- Optimize the web app settings for best performance
After the PowerShell script is run, there are just a few short steps to add the AppManager to your SharePoint site.
Step 1: Download the required files to your local machine
- Download the Akumina AppManager files to be installed
- For example:
- Unzip the files into a local directory
- For example:
- Download the PowerShell installer scripts
- The scripts can be found here: https://github.com/akumina/automation
- Unzip the files into a local directory.
Step 2: Get the O365 Tenant information
- The O365 Tenant ID and Subscription ID under which you want to install are required.
- If you do not already have these ID’s, then do the following:
- Log in to your Azure Portal
- Launch a CloudShell window
- Type “dir” at the prompt to get the ID’s
Step 3: Run the PowerShell Installation Script
- On your local machine, search for and launch “Windows PowerShell ISE” as an adminstrator (advanced users can run from the command line, but still need to update the Run.ps1 file as outlined below)
- In the PowerShell client, open both the “Run.ps1” and the “Common.psm1” downloaded files from the local “ampowershellinstall” directory
- If this is the first time running a PowerShell script locally to access Azure, item #2 should be executed, and item #4 will likely be needed
- The installation script will prompt for the Azure geographic location on which to install. It will default to eastus2, but you can get a list of all Azure server locations by logging into your Azure portal, opening a CloudShell and running the command “Get-AzureRmLocation”
- In the Run.ps1 file, set the path to the folder location of the PowerShell files that you will be running:
#Edit the following to point to your working directory that contains the ps file
- Save the Run.ps1 file, then run it
- The script will prompt you for the following inputs
- Enter TenantID
- Enter SubscriptionID
- Enter App Name: The name for the new webapp (LOWERCASE characters ONLY and do NOT use spaces or any special characters in the name)
- Enter Location: The Azure location you want to install into (defaults to eastus2, or you can add your desired location)
- Enter resource group name: If you want the new app to go into an existing Resource Group, enter the resource group name. If you leave blank, a new resource group will be created based on the App Name
- Enter Local app directory: The local directory location for the AppManager files
- Although this is optional, a great deal of time can be saved by having the script upload the files for you
- Example: C:\temp\4.0.1802.0171-Core-4.0.1802.0157-Sitecreator-4.0.1802.0171-InterChange
- Enter email address to set alert notfications: If you want Azure notifications to be setup for the newly created app, enter the email address to which the notifications should be sent. Leaving this blank will not setup notifications.
- Provision App Gateway: Normally this will be false. If you wish to setup see later in this document
- Provision Redis Cache: Normally this will be false. If you wish to setup see later in this document
- Provision Traffic Manager: Normally this will be false. If you wish to setup an App Gateway see later in this document
- Finally, it will prompt you to log in to the Azure Portal before executing
- Note: Warnings will be displayed during the execution of the script. This is normal and can be ignored.
- When the script is complete, it will provide you with some key information for the components and locations which have just been installed. Copy this information as you will need it going forward.
- AD App Name, ID and Secret – these are for the Azure AD Graph API App
- Storage ConnectionString – this is the unsecured string to access the associated Storage Container that was created. This is for your information only as it is not used directly in any of the AppManager configuration files
- Secret Id Uri – This is the URL for the ConnectionString which is stored securely in the associated Azure KeyVault
- AzureWebSite URL – the URL for the newly installed AppManager
- FTP Host, User, Password – ftp server and credentials for the newly installed AppManager
- BackgroundProcessorKey – value to use when configuring the Background Processor
- Values in this example have been obscured for security
AD App Name: ad-akdoc10
AD App ID: 5a37f5XX-XXXX-XXXX-XXXX-XXXXXXXXXXX
AD App Secret: v1yFXXXXXXXXXXXXXXXXXXXXXXXXXXXX=
Storage ConnectionString: DefaultEndpointsProtocol=https;AccountName=akdoc10;AccountKey=rVXXXXXXXXXXohw==
Secret Id Uri: https://akdoc10.vault.azure.net:443/secrets/StorageConnectionString/ea7f71XXXXXXXXXXX
AzureWebSite Url: https://akdoc10.azurewebsites.net
FTP Host: ftp://waws-prod-XXXXXXXXX.ftp.azurewebsites.windows.net/site/wwwroot
FTP User: akdoc10\$akXXXXX
FTP Password: TLppuXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Step 4: Grant Permissions on the Graph API App
- Access your Azure Active Directory portal
- Select “App registrations” and find the newly created app (AD App Name from above)
- Click on the app, select “Settings” and then “Required Permissions”
- At the top of the Required Permissions panel, click on the “Grant Permissions” button. This will finalize the setting up of the Graph API App.
Step 5: Create the AppManager Entry in the SharePoint App Catalog
Installing On the O365 SharePoint Root Site
If you are going to deploy the Akumina Digital Workplace on the root SharePoint site of your O365 tenant there are additional steps required before proceeding. Expand the following section and following the steps outlined. If not on the root site, proceed to setting up the App Catalog entry.
1. Turning on Custom Scripts on O365 Settings
The Root O365 SharePoint site does not allow content to be written to the Style library unless the “Custom Script” setting of SharePoint is set to “Allow user to run custom script on self-service created sites”.
On your O365 tenant, navigate to:
- Admin > SharePoint > Settings.
- Scroll down and select the highlighted in yellow radio button.
You may have to wait up to 24 hours for this change to take effect.
2. Convert the Root Team Site to a Publishing Site
- Site Settings > Site Collection features
- Activate – “SharePoint Server Publishing Infrastructure”
- Activate – “Workflows”
- Site Settings > Manage site features
- Activate – “SharePoint Server Publishing”
3. VERIFY the Root Site Has Been Converted to Publishing Site
After Turning On Publishing, on the Site Settings Page, under “Look and Feel” verify you see “Design Manager”, if you do not then Deactivate “Publishing” in both the “Manage site features” and “Site collection features”, then turn them back on in this order – “Site collection features” and then “Manage site features”. The evidence of “Design Manager” proves the site has been converted to a publishing site correctly.
4. Turn on Navigation for the Site
- Site Settings > Navigation
- Set Global Navigation = Managed Navigation….
- Set Current Navigation = Managed Navigation…..
- Managed Navigation: Term Set click on “Create Term Set”
- Manage Navigation: Default Page Settings – Unclick “Add new pages to navigation automatically”
Wait 24 hours before adding AppManager to the root Site Collection and deploying the Digital Workplace.
Creating the Client ID and Client Secret for the App Catalog
A Client Identity and Client Secret must be created for the new incoming APP – AppManager. AppRegNew.aspx will be used to generate those items.
- Login as Administrator into your SharePoint Admin Center.
- Click on apps in left column.
- Click on App Catalog.
Note the URL backspace to apps/_layouts/15/ and append AppRegNew.aspx
- Navigate to
- The App Information page will be displayed, where input field to create the Client Identity will be displayed:
Set the following fields:
- Client Id: – Click the Generate button and SharePoint will generate the Client ID.
- Client Secret – Click the Generate button and SharePoint will generate the Client Secret.
- TITLE – This name must start with “Akumina Interchange”. It is recommended that you include the Client Secret expiration date in the Title of the app as another reminder of when a new AppReg will need to be generated (example: “Akumina Interchange Exp012318”). This title can be viewed in Site Settings/Site app permissions/.
- App Domain – This is the value you got for AzureWebSite URL from the output of the script, minus the https://
- Example: akdoc10.azurewebsites.net
- Redirect URI – This is the full value you got for AzureWebSite URL from the output of the script
- Example: https://akdoc10.azurewebsites.net
- Click on the Create button
- Verify that the Identifier was generated successfully.
- Click on the OK button
Customizing the “Akumina.InterChange.App.app” File
Browse to the location where your Akumina AppManager files are located and find the “Akumina.InterChange.App.app” file
- RIGHT click on “Akumina.InterChange.App.app” and select “COPY” from the dropdown menu.
- RIGHT click on your mouse and PASTE the file.
- You will see the file “Akumina.InterChange.App – Copy.app”.
- Right Click on “Akumina.InterChange.App – Copy.app” and from the dropdown list select “RENAME”
- Change the name from “Akumina.InterChange.App – Copy.app” to “Akumina.InterChange.App.zip”
- You will get this confirmation popup select “YES”
- Right Click on “Akumina.InterChange.App.zip” and click on “Extract All…” from the dropdown menu
- The following files/folder will appear in the extracted folder:
- Right click on “AppManifest.xml” and click “Open with > Notepad” (or any other text editor).
- There are 2 items that need to be changed
Changing the Start Page
- Change the URL for the <StartPage> to your AppManager AzureWebSite URL that you have from the script. For our example: https://akdoc10.azurewebsites.net
Changing the ClientId
Change the ClientId to the value that was generated in the previous step Creating the Client ID and Client Secret for the App Catalog
Below is the updated file with the redirect and Client ID values highlighted:
Repacking the .app file
- On the Notepad top menu, click “File” and from the dropdown menu, click “Save”.
- On File Explorer Select all files in folders in the C:\Akumina\Apps Directory.
- Right Click from the dropdown select “Send to > Compressed (zipped) folder”.
- Rename the file to App.zip
- Move App Zip up one folder level
- Rename your original “Akumina.InterChange.App.app” to “Original.Akumina.InterChange.App.app
- Rename your “App.zip” to “Akumina.InterChange.App.app”
- When you rename the popup will appear click “Yes”
Installing AppManager into the App Catalog
Once you customize the Akumina AppManager App File, it needs to be installed on your 365 SharePoint Site in the App Catalog.
- On The SharePoint admin Center page, click “apps” in the left column Navigation.
- The SharePoint Admin “apps” page will display.
- In the right pane under “apps” click on “App Catalog”.
- On the “App Catalog” page select left column Navigation “Apps for SharePoint”.
- On the Apps for SharePoint select “+new”.
- In the Popup window “Add a document” click on “Browse”
- In the file explorer window navigate to the location of the Akumina.Interchange.App.app file and select it, then click OK
- When the App upload is complete you will see the a new entry in the list which displays the Product ID for this APP. Verify that there are not errors. The app will now be available for adding to your SharePoint Sites
Step 6: Update the AppManager Web.config file
- Using the FTP information provided as an output from the PowerShell script, access the “web.config” file that is part of the AppManager installed files.
- Open the web.config file for edit using a text editor
- Search for the term “SharePointURL”
- Below, this section of the web.config will be highlighted. This is where you will set 3 things
- Set the SharePointURL to the SharePoint server URL (leaving off the /sites/sitename) where you will be installing AppManager. In our example it will be set to this URL: https://awemind.sharepoint.com
- Set the Client ID and the Client Secret that were generated in the previous step Creating the Client ID and Client Secret for the App Catalog
- Next, search for the “customHeaders” parameter
- Set your SharePoint URL for the value of “Access-Control-Allow-Origin”
- Uncomment the “Access-Control-Allow-Credentials”. Leave the value as “true”
- To optimize the response time for the front end site pages, add the following line into the customheaders section if it is not already there (this will cache the preflight OPTIONS request calls to AppManager )
<add name=”Access-Control-Max-Age”value=”1600″ /> (value is in seconds and can be set to your desired duration)
- Example of all changes:
- Finally, ensure that the following section of code exists and is set as follows. This allows for larger file sizes to be handled by IIS for the aadusers.xml file (the users synchronization file with AzureAD)
<requestLimits maxAllowedContentLength=”104857600″ />
- Save the web.config file and close it
- Copy the edited web.config file back to the ftp site to replace the existing file
Step 7: Add the AppManager app to the SharePoint Site Collection
- Access the Site Collection
- Navigate to the “Site Contents” page using the gear icon
- On the Site Contents page Click on the “New” button and “App”. If using the “Classic” view, click on “Add an app”
- On the “Site Contents > Your Apps” page, click on Left column Navigation under “Your Apps”, “From Your Organization”
- You will see an entry for the Akumina app you added to the App Catalog
- Click on the entry to add it
- The dialog box “Do your Trust Akumina AppManager” will appear
- Click on “Trust It”.
The “Site Contents” page will display where you will see your newly added App “Akumina AppManager”.
Additional Steps for IE Browser Support
Due to variations in the IE Browser family (as compared to browsers such as Chrome and Firefox), there are additional settings required if your users are going to use IE browsers in an O365 installation.
Add URLs to “Trusted Sites”
With the IE browsers (10, 11 or Edge) the AppManager URL, front-end site URL AND the Microsoft login URL must be added to the “Trusted Sites” in order for the Akumina Framework, your front-end site and certain widget functionality (such as My Apps) to operate properly.
- Access Internet Options/Security/Trusted Sites and click on the “Sites” button
- Add the AppManagerURL, the URL for the home of your intranet site, and the Microsoft login (https://login.microsoftonline.com) to the Trusted Sites list
Enable Cookies for AppManager website
Cookies MUST be enabled in the browser for the AppManager website.
- Access Internet Options/Privacy tab
- Click on the “Sites” button in the Settings section
- Add your AppManagerURL in the website address field and click “Allow”
Enabling “My Apps” Functionality for IE Browsers
If your organization is going to enable the “My Apps” functionality, there is an additional setting required:
Access the “DigispaceConfigurationIDS_AK” list and set the “LOADER_STEPS_ENABLE_FETCHSPGROUPS” key to “true”