Azure Function App for the Office for the Internal Market

CONTENTS

OVERVIEW

DEPLOYMENT PREREQUISITES

INSTALLATION STEPS

OVERVIEW

This repository holds the source code for the Office for the Internal Market Azure Function. The main components are:

• Azure Function App C# source code

DEVELOPMENT ENVIRONMENT

Before cloning this repository the following prerequisites must be installed on the development PC:

• Visual Studio 2019

Debugging on local machine

In order to debug or run the Function App locally you will need to:

• have access to a SharePoint library formatted for the submissions data
• App registration to access SharePoint see Deployment Prerequistes below
• The certificate generated by the above process must be installed on the development PC
• create a local.settings.json file in the root source folder. This needs to be configured with all the environment variables required by the Function App see Create Azure Function App below

DEPLOYMENT PREREQUISITES

• PREREQUISITE 1: Create Certificate
• PREREQUISITE 2: Create Azure App Registration and configure App permissions
• PREREQUISITE 3: Create Azure Function App

Each prerequisite is described in more detail below.

PREREQUISITE 1: Create Certificate

NB: this description uses a PowerShell script to create a certificate, over methods can also be utilised.

1. Create a PowerShell Script (E.g. CreateAzureCertificate.ps1) with the following contents:

   $certCommonName = "SPAccess"
   $certValidYears = 2
   $certOutputPath = "C:\Temp"
   
   # Install PnP PowerShell module if not already installed
   if (!(Get-Module SharePointPnPPowerShellOnline -ListAvailable)) {
       Write-Host "Installing SharePoint PnP PowerShell Module"
       Install-Module SharePointPnPPowerShellOnline -Scope CurrentUser
   }
   
   # Generate Certificate paths
   $certCerPath = Join-Path -Path $certOutputPath -ChildPath "$certCommonName.cer"
   $certPfxPath = Join-Path -Path $certOutputPath -ChildPath "$certCommonName.pfx"
   $certCsvPath = Join-Path -Path $certOutputPath -ChildPath "$certCommonName.csv"
   
   # Request certificate password from users
   $certPassword = Read-Host -Prompt "Enter a password for the generated PFX file" -AsSecureString
   
   # Generate Certificate
   Write-Host "Generating Certificate CER and PFX files"
   $cert = New-PnPAzureCertificate -CommonName $certCommonName `
       -ValidYears $certValidYears `
       -OutCert $certCerPath `
       -OutPfx $certPfxPath `
       -CertificatePassword $certPassword
   
   Write-Host "Generating Certificate CSV file"
   $cert | Export-Csv -Path $certCsvPath -NoTypeInformation

   If required, edit the $certCommonName, $certValidYears and $certOutputPath variables to suit.

2. Execute the PowerShell Script. During execution, the PowerShell script will:

   • Install the 'SharePoint PnP PowerShell Online' online module. This requires an active internet connection. If an active internet connection is not available; the module will need to be installed manually prior to executing the script; the MSI Installer (SharePointPnPPowerShellOnline.msi) can be downloaded from https://github.com/sharepoint/pnp-powershell/releases
   • Prompt the user for a password for the generated PFX file.
   • Create a certificate and save it as a .cer and password protected .pfx file
   • Save the certificate as text (.csv)

3. Securely store the password and files

PREREQUISITE 2: Create Azure App Registration and configure App permissions

1. Logon to the Azure Portal with an administrative account

2. Navigate to 'Azure Active Directory'

3. Click 'App registrations'

4. Click 'New registration'

5. Give the registration a name and choose 'Accounts in this organizational directory only', then click 'Register':

6. Click 'Certificates & secrets'

7. Click 'Upload certificate' and select the .cer certificate file created in PREREQUISITE 1 of this guide. Click 'Add'. Once complete, the certificate should be displayed in the dialog

8. Click 'API permissions'

9. Using the 'Add a permission' button; add the following 5 permissions:

   • SharePoint ⇒ Application permissions ⇒ Sites ⇒ Sites.ReadWrite.All

10. Click 'Grant admin consent for [tenant name]', and click 'Yes' to grant consent

PREREQUISITE 3: Create Azure Function App

1. Logon to the Azure Portal with an administrative account

2. From the dashboard select 'Create a resource'

3. Search and select 'Function App'

4. Click 'Create'

5. On Basics:

   • Select the subscription and Resource Group (or create a new one)
   • Provide a unique Function App name
   • Select .Net 'Runtime stack', version 3
   • Select a suitable Region

6. Click Next : Hosting

   • Select or create new storage account
   • Operating System: Windows
   • Plan type: Consumption (serverless)

7. Click Next : Networking (preview)

8. Click Next : Monitoring

   • Enable Application Insights, if required

9. Click Next : Tags

   • Add any tags required

10. Click Next : Review + create; Review settings and create the Function App

11. Once created, go to the new resource

12. Select Settings ⇒ TLS/SSL settings

13. Under Bindings set 'HTTP Only' on 'On'

14. Under Private Key Certificates (.pfx) upload the certificate file created above

15. Select Settings ⇒ Configuration. Under Application settings add the following settings

    Name	Value
    CERT_THUMBPRINT	Thumbprint of certificate loaded into Function App
    CLIENT_ID	Guid of App Registration created above
    OIM_SITE_COLLECTION	Url of the SharePoint site collection containing list
    SUBMISSIONS_LIST	Name of SharePoint list
    TENANT_ID	SharePoint tenant id
    TRANSLATE_AREA_OF_OPS	Translation for converting web form value to SharePoint value of the form: <webform_value>::<SharePoint_value>;;
    TRANSLATE_IMPACT_AREA	Translation for converting web form value to SharePoint value
    TRANSLATE_REPORTING_AS	Translation for converting web form value to SharePoint value
    WEBSITE_LOAD_CERTIFICATES	Thumbprint of certificate loaded into Function App

DEPLOYMENT STEPS

Publish code to Functional App

1. View the destination Function App in Azure
2. From the Overview click ‘Get publish profile’ to download the publish profile
3. Open the development solution in Visual Studio
4. Select Build ⇒ Publish [Solution name]
5. Select ‘New’ (NB: this step may not occur if there are no existing profiles)
6. Select ‘Import Profile’
7. Browse to the downloaded publish profile file and import
8. Remove any Service Dependencies
9. Click ‘Publish’
10. Check Output to ensure Publish was successful

License

MIT Licence