Skip to content

Deployment Guide

Jump to bottom
jeremystokese2 edited this page Dec 3, 2021 · 12 revisions

Prerequisites

To begin, you will need:

  1. An Azure subscription where you can create the following kinds of resources:
    • App Service
    • App Service Plan
    • Application Insights
    • Function App
    • Key Vault
    • Search Service
    • SQL Database
    • SQL Service
    • Storage Account
  2. Permissions to create and configure AAD App Registrations
  3. The GovAddressBook repository downloaded: https://github.com/engagesquared/GovAddressBook
  4. Global Administrator access to a M365 tenant with Teams enabled - this will be the account used to deploy the teams app
  5. A shell terminal - Powershell or Azure Cloud Shell are recommended. Your terminal will need to have the following installed and configured:

Installation summary

Topic Description
Synopsis The deployment process of the app involves 3 main procedures, creating the Azure resources within the resource group, setting up the app registration and deploying the app manifest of the web-app-teams, web-app-external and func-app-refresh to the app services and function app within the resource group
Estimated Time to Complete 2 hours

Deployment steps

Stage 1 - Prepare

Create Azure Resource Group

  1. Open the Azure Portal and create a new Resource Group
  2. Name the Resource Group {{company-name}}-{{environment}}-directory-rg. For example: contosouav-production-directory-rg Note: Azure resources and their URL endpoints must be globally unique. You may run into issues with deployment if there is a naming conflict with another instance.
  3. Set the region, then submit to create your new Resource Group

Obtain your Azure Active Directory (AAD) Tenant ID

  1. Login to the Azure Portal

  2. Open Active Directory

  3. Note down the Tenant ID - it will be used in several steps throughout this guide.

Create the App Registration in the destination M365 tenant (Teams environment)

  1. Open the Azure Portal

    Note: If you are deploying GovAddressBook to an M365 tenant that is distinct from Azure tenant, you must log into that Azure account.

  2. Navigate to Active Directory > App Registrations

  3. Create a new App Registration with name govaddressbook-app. Leave the other fields as default

Keep this tab open as you will need several values from your App Registration when configuring your deployment

Edit your deployment file

  1. With the repository downloaded, open the / azure-resources folder in file explorer
  2. Open the main.tf file in a text editor, such as VSCode.
  3. Use the find tool to search for {{company-name}} and replace it with your organisation's name in lowercase, with spaces removed. For example: contosouav
  4. Use the find tool to search for {{environment}} and replace it with your target environment. For example: uat
  5. Use the find tool to search for {{db-password}} and replace it with a secure password.
  6. Use the find tool to search for {{db-user}} and replace it with "sqlAdmin"
  7. Use the find tool to search for {{reg-app-tenant-id}} and replace it with the Tenant ID found in your App Registration
  8. Use the find tool to search for {{reg-app-id}} and replace it with your App Registration's ID
  9. Use the find tool to search for {{self-external-api-key}} and replace it with a Unique GUID
  10. Save and close the file

Deploy your resources with Terraform

  1. Open your terminal program, such as PowerShell

  2. Open the azure-resources folder in the code repo in the terminal

  3. Run the following command to login to your Azure tenant, replacing <tenant-id> with your AAD tenant ID captured in the previous step.

    az login --tenant <tenant-id>

    You will be prompted to enter login to your Azure account.

    Once you have logged in, your terminal will return a list of all the Azure Subscriptions you have access to with this account. The Subscription that has IsDefault: true will be our target subscription. You can change your active subscription if needed.

  4. Run the below command to initialize the working directory containing Terraform configuration files:

    terraform init

  5. Run the below command to check whether the execution plan matches your expectations without making any changes to real resources or to the state:

    terraform plan

    If applied correctly, you should be creating 19 resources in your target Resource Group

  6. Run below command to deploy the resources to your Resource Group:

    terraform apply

    It should take approximately 10-15 minutes to finish creating your resources.

Stage 2 - Configure

Download your Key Vault Certificate

  1. Open the Azure portal and navigate to key vault within the resource group you created

  2. Go to Certificates and selected the Certificate that has been created.

  3. Select the Current Version of the Certificate, then Download the .CER file of certificate.

    Your browser may give a warning when trying to download this file. In some browsers, like Edge, you must right-click the download in your browser and click Keep.

Configure the App Registration in the destination M365 tenant (Teams environment)

  1. Navigate to the Authentication page in your new App Registration and select Add a platform.

  2. Select Web under Web Applications

  3. Add in the redirect URI as the URL of the Teams app service from the resource group you created earlier. For example: https://contosouav-uat-directory-teams.azurewebsites.net.

    You can retrieve this from the Overview page of the app service

  4. Leave the Front-Channel Logout URL as blank.

    Enable the Access tokens and ID tokens checkboxes then press configure.

  5. Navigate to the expose an API page

    Click the Set link to set your Application ID URI

    A dialog will appear with an App ID URL already set. It will look something like

    api://{GUID}

    for example: api://a5f925fd-c103-464d-8cd4-8dc5539c52d6

  6. Insert the URL of the teams app service (without https://) after api://. Do not remove the existing GUID value

    E.g. api://contosouav-uat-directory-teams.azurewebsites.net/{GUID}

  7. Save the App ID URI to close the dialog

  8. Click the Add a scope button

  9. Add a scope with the following details:

    • Scope name = access_as_user
    • Who can consent? = Admins and users
    • Admin consent display name = Access as user
    • Admin consent description = Allows the app to read user-profiles and send Teams Activity Feed notifications
    • State = enabled

  10. Click the Add scope button to save your changes

  11. Click the Add a client application button

  12. Add the following Client ID and enable the checkbox next to the authorized scope

    1fec8e78-bce4-4aaf-ab1b-5451cc387264

  13. Click Add application button to save your changes

  14. Repeat Steps 14 – 16 with the following Client ID:

    5e3ce6c0-2b1f-4285-8d4b-75ee78787346

  1. Navigate to the API permissions page
  2. Click the Add a permission button and then select Microsoft Graph as the type of API
  3. Select Delegated permissions and enable the following permissions:
    • Directory.Read.All
    • User.Read (Should already be enabled)
    • User.Read.All
  4. Select Application permissions to change the type of permissions, the enable the following:
    • MailboxSettings.Read
    • TeamsActivity.Send
    • User.Read.All
  5. Select the Add permissions button to save your changes.
  6. Select the Grant admin consent button. The Configured permissions table should look like this:

  1. Navigate to the Certificates & secrets page
  2. Select the Upload certificate button. Upload .CER certificate file you downloaded from key-vault within the resource group you created

Create Database Schema

  1. Open the db-scripts folder from the code repo in file explorer

  2. Open dbTables.sql in a text editor and copy the contents of the script file.

  3. Open the SQL Database from the Resource Group and navigate to the Query editor page

  4. Login to the database with sqlAdmin as the username, and the password you set in the main.tf file

    If you are asked for a certificate, click OK to give it the default certificate.

  5. You will receive a login error because your IP is restricted. Click the Whitelist link below the login form to whitelist your IP, then click OK to complete the login process.

  6. Paste the contents of the script file you copied previously into the Query editor text field, then select the Run button.

    If successful, an alert will appear at the bottom of the page, and if you expand the Tables icon, you will see several database tables have been generated.

Configuration and Compile app code

If you aren't still logged into Azure with your terminal from the previous steps, make sure to run az login again to target your Azure subscription

Teams App Configuration and Compile

  1. Make a duplicate of the example.env file within the web-app-teams folder in the code repo, and rename it to .env. Use your text editor to update the following values:

    • Replace {{company-name}} with the value set in the main.tf file. For example: contosouav

    • Replace {{environment}} with the value set in the main.tf file. For example: uat

    • Replace {{db-password}} with the password value set in the main.tf file

    • Replace {{azure-search-key}} with the Primary Key found in the Azure Search service in your Resource Group, on the Keys page

    • Replace {{reg-app-id}} with the ID of the govaddressbook-app App Registration. You can obtain this value from the Overview page of the App Registration

    • Replace {{reg-app-tenant-id}} with the Tenant ID of the govaddressbook-app App Registration. You can obtain this value from the Overview page of the App Registration

    • Replace {{reg-app-cert-thumbprint}} with the Thumbprint of the Certificate you previously uploaded to the govaddressbook-app App Registration. You can obtain this value from the Certificates & secrets page of the App Registration

  2. Save your changes to the file

  3. cd into the common folder and run npm i to install common project dependencies

  4. cd into the web-app-teams folder and run the following commands:

    • npm i to install web-app-team dependencies
    • npm i -g gulp-cli to install gulp
    • gulp build to build the app
    • gulp manifest to create the app package
    • npm prune --production to tidy unused files

  5. Navigate to the web-app-teams > package folder in your terminal

  6. Archive dist, node_modules, package.json as a zip file, named web-app-teams.zip

External API App Configuration and Compile

  1. Make a duplicate of the example.env file within the web-app-external folder in the code repo, and rename it to .env. Update the following values:
    • Replace {{company-name}} with the value set in the main.tf file. For example: contosouav
    • Replace {{environment}} with the value set in the main.tf file. For example: uat
    • Replace {{db-password}} with the password value set in the main.tf file
    • Replace {{azure-search-key}} with the Primary Key found in the Azure Search service in your Resource Group, on the Keys page
    • Replace {{reg-app-id}} with the ID of the govaddressbook-app App Registration. You can obtain this value from the Overview page of the App Registration
    • Replace {{reg-app-cert-thumbprint}} with the Certificate Thumbprint from the Certificate uploaded to your App Registration. You can obtain this value by opening the govaddressbook-app App Registration, then navigating to the Keys page.
    • Replace {{reg-app-tenant-id}} with the Tenant ID of the govaddressbook-app App Registration. You can obtain this value from the Overview page of the App Registration
    • Replace {{self-external-api-key}} with the unique GUID you generated when configuring the main.tf file.
  2. Save your changes to the file
  3. Run the following commands:
    • npm i to install dependencies
    • npm run build to build the app
    • npm prune --production to tidy unused files
  4. Navigate to the web-app-external > package folder in your terminal
  5. Archive dist, node_modules, package.json as a zip file, named web-app-external.zip

Function App Configuration and Compile

  1. Duplicate the example.settings.json file within the func-app-refresh folder in the code repo, and rename the copy to local.settings.json. Update the following values:
    • Replace {{company-name}} with the value set in the main.tf file. For example: contosouav
    • Replace {{environment}} with the value set in the main.tf file. For example: uat
    • Replace {{db-password}} with the password value set in the main.tf file
    • Replace {{azure-search-key}} with the Primary Key found in the Azure Search service in your Resource Group, on the Keys page
    • Replace {{reg-app-cert-thumbprint}} with the Certificate Thumbprint from the Certificate uploaded to your App Registration. You can obtain this value by opening the govaddressbook-app App Registration, then navigating to the Keys page.
    • Replace {{reg-app-id}} with the ID of the govaddressbook-app App Registration. You can obtain this value from the Overview page of the App Registration
    • Replace {{reg-app-tenant-id}} with the Tenant ID of the govaddressbook-app App Registration. You can obtain this value from the Overview page of the App Registration
  2. Save your changes to the file
  3. Run the following commands:
  • npm i to install dependencies
  • npm run build to build the app
  • npm prune --production to remove unnecessary files
  1. Archive the following files into a zip folder called func-app-refresh.zip: dist, node_modules, funcCompleteUserProfileNotification, funcDeleteUser, funcUpdateUserOOF, funcUserInfoFullMigration, funcUserInfoSync, proxies.json, host.json, package.json

Configure and compile Teams app manifest

  1. In a text editor, open the manifest.json file, found in the code repo > web-app-teams > package folder
  2. Update the following values:
    • Replace {{reg-app-id}} with the ID of the govaddressbook-app App Registration. You can obtain this value from the Overview page of the App Registration
  3. Save your changes to the file
  4. Zip the contents of the manifest folder and call the new file govaddressbook-app.zip

Stage 3 - Deploy

Teams Webapp Deployment

  1. cd to the web-app-teams folder
  2. Run az login --tenant <your tenant id> in your shell terminal to login to your tenant
  3. Using the zip folder you created previously, run the following command in your shell terminal to deploy the web app: az webapp deployment source config-zip -g {{company-name}}-{{environment}}-directory-rg -n {{company-name}}-{{environment}}-directory-teams --src <replace by full local path of .zip package>

External Webapp Deployment

  1. cd to the web-app-external folder
  2. Run az login --tenant <your tenant id> in your shell terminal to login to your tenant
  3. Using the zip folder you created previously, run the following command in your shell terminal to deploy the external web app: az webapp deployment source config-zip -g {{company-name}}-{{environment}}-directory-rg -n {{company-name}}-{{environment}}-directory-external --src <replace by full local path of .zip package>

Function App Deployment

  1. cd to the function-app-refresh folder
  2. Run az login --tenant <your tenant id> in your shell terminal to login to your tenant
  3. Using the zip folder you created previously, run the following command in your shell terminal to deploy the function app: az functionapp deployment source config-zip -g {{company-name}}-{{environment}}-directory-rg -n {{company-name}}-{{environment}}-directory-refresh --src <replace by full local path of .zip package>

Teams Manifest Deployment

  1. Deploy the Teams app using the tools provided within the Teams Admin Centre.

Known issues with deployment

Use of Free SKUs

The Terraform deployment is currently configured to deploy resources with a 'free' or 'basic' SKU where possible. Some of these SKUs, such as free App Services, have limitations.

You may need to modify the main.tf deployment configuration to accommodate your specific Azure subscription constraints.

We expect to update the default resource configuration in a future release.

Soft-delete of Key Vaults

By default, Key Vaults are soft-deleted when they are deleted from your Azure Subscription. If you hit an error in deployment with a code VaultAlreadyExists, you may still have a previously soft-deleted Key Vault that must be purged before continuing with the deployment

Clone this wiki locally