Section 0 - Prepare for SPARK Deployment

READ THIS ENTIRE PAGE FIRST!

This page contains a checklist and instructions of all of the prerequisites required before you begin to deploy SPARK.

THE SPARK DEPLOYMENT TEAM WILL BE EXPECTING THE ITEMS ON THIS PAGE TO BE ALREADY DONE BEFORE THE DEPLOYMENT BEGINS!

IF YOU HAVE QUESTIONS OR ISSUES, PLEASE REACH OUT TO YOUR MICROSOFT SPARK LEAD OR THE SPARK DEPLOYMENT TEAM

Checklist

• The SPARK Deployment Workbook
• Prepare the Microsoft Azure Subscription
• Install PowerShell 7.2+
• Install PnP PowerShell
• Create Certificates

The SPARK Deployment Workbook

📎 Download the SPARK Deployment Workbook

Download and keep this workbook open as you go through the entire deployment. You will fill this in as you gather data and configure the SPARK components.

Environment Variables

1. Review the script below and update the Connect to Azure section to uncomment the appropriate connection line for your environment
2. Run the script below to generate a variables.csv file
3. Open the variables.csv file and copy the environment values in the SPARK deployment workbook

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
########################################## Required Modules ##########################################
#Install-Module Az.Accounts

########################################## Connect to Azure ##########################################
#Import-Module Az.Accounts

# Connect to Azure
# Commercial/GCC
#Connect-AzAccount | Out-Null;

# GCC-H/DoD
#Connect-AzAccount -Environment AzureUSGovernment | Out-Null;

########################################## Get Environment Values ##########################################
# Define the table to store the key/value pairs
$data = @()

# Get the environment information
$azContext = Get-AzContext

# Output the variables for the spreadsheet
$data += @{ Name = "v_azAccountEnvironment"; Value = $azContext.Environment.Name }
$data += @{ Name = "v_azureEnvironment"; Value = $azContext.Environment.Name }
$data += @{ Name = "v_catchAllAccount"; Value = "org-spark-mail@$($azContext.Tenant.DefaultDomain)" }
$data += @{ Name = "v_exo_email_suffix"; Value = "@$($azContext.Tenant.DefaultDomain)" }
$data += @{ Name = "v_exo_organization"; Value = $azContext.Tenant.DefaultDomain }
$data += @{ Name = "v_exo_sendEmailNPE"; Value = "org-spark-mail@$($azContext.Tenant.DefaultDomain)" }
$data += @{ Name = "v_subscriptionId"; Value = $azContext.Subscription.Id }
$data += @{ Name = "v_subscriptionName"; Value = $azContext.Subscription.Name }
$data += @{ Name = "v_tenant"; Value = $azContext.Tenant.DefaultDomain }
$data += @{ Name = "v_tenantId"; Value = $azContext.Tenant.Id }

# Get the tenant information
$tenantDetails = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$($azContext.Tenant.Id)/.well-known/openid-configuration" -Method Get

# Set the variables, based on the environment
switch ($tenantDetails.msgraph_host) {
    'graph.microsoft.com' {
        $spoDomain = "sharepoint.com";
        $data += @{ Name = "v_exo_environment"; Value = "O365DEFAULT" }
        $data += @{ Name = "v_graphUrl"; Value = "https://$($tenantDetails.msgraph_host)" }
        $data += @{ Name = "v_MgGraph_Environment"; Value = "Global" }
        $data += @{ Name = "v_sqlConnectionString"; Value = "Server=tcp:sqldb-spark.database.windows.net,1433;Initial Catalog=sqldb-spark;Encrypt=True;MultipleActiveResultSets=True;" }
    }
    'graph.microsoft.us' {
        $spoDomain = "sharepoint.us";
        $data += @{ Name = "v_exo_environment"; Value = "O365USGovGCCHigh" }
        $data += @{ Name = "v_graphUrl"; Value = "https://$($tenantDetails.msgraph_host)" }
        $data += @{ Name = "v_MgGraph_Environment"; Value = "USGov" }
        $data += @{ Name = "v_sqlConnectionString"; Value = "Server=tcp:sqldb-spark.database.usgovcloudapi.net,1433;Initial Catalog=sqldb-spark;Encrypt=True;MultipleActiveResultSets=True;" }
    }
    'dod-graph.microsoft.us' {
        $spoDomain = "sharepoint-mil.us";
        $data += @{ Name = "v_exo_environment"; Value = "O365USGovDoD" }
        $data += @{ Name = "v_graphUrl"; Value = "https://$($tenantDetails.msgraph_host)" }
        $data += @{ Name = "v_MgGraph_Environment"; Value = "USGovDoD" }
        $data += @{ Name = "v_sqlConnectionString"; Value = "Server=tcp:sqldb-spark.database.usgovcloudapi.net,1433;Initial Catalog=sqldb-spark;Encrypt=True;MultipleActiveResultSets=True;" }
    }
}

# Determine the sharepoint urls
$domain = $azContext.Tenant.DefaultDomain.Split(".")[0];
$data += @{ Name = "v_helpurl"; Value = "https://$domain.$spoDomain/sites/spark/sitepages/attestation-portal-help.aspx" }
$data += @{ Name = "v_siteadminurl"; Value = "https://$domain-admin.$spoDomain" }
$data += @{ Name = "v_sporootURL"; Value = "https://$domain.$spoDomain" }
$data += @{ Name = "v_tenantUrl"; Value = "https://$domain-admin.$spoDomain" }

# Output the csv
$data | Sort-Object -Property { $_.Name } | Export-Csv -Path "./environment.csv" -NoTypeInformation
Write-Host "CSV file written to environment.csv"

Prepare the Microsoft Azure Subscription

• If not already enabled, enable the following Azure providers in the subscription:
  • Microsoft.Storage - for Azure Storage Accounts
  • Microsoft.Sql - for Azure SQL Database
  • Microsoft.Web - for Azure Function Apps
  • Microsoft.Automation - for Azure Automation Accounts and Runbooks

SPARK Installer Permissions

The overall installation of SPARK will require the following permissions to create and configure the necessary resources and configurations required for functionality. These roles are usually delegated across a team of administrators doing the installation. (Typically using the Spark System Admins Entra Group, but not required)

📎 FOR A LIMITED TIME ONLY!

These roles and permissions are only required during the actual deployment of SPARK. They are not required by the SPARK services or managed identities to function!

Azure Subscription

or

Verify/Install PowerShell 7.2+

On the Installer’s workstation, ensure that PowerShell 7.2 or greater is installed for the latest PnP.PowerShell module.

You can verify the version of PowerShell you are running from a command prompt (not PowerShell)

pwsh --version

If you get an error, it most likely means you do not have it installed.

If you do not have PowerShell 7.2+, you have a few choices to install it:

Install PnP PowerShell

SPARK uses PnP PowerShell for to apply configurations that cannot be completed using the M365 Portals, Graph API or the Microsoft PowerShell modules.

SPARK supports the latest -1 versions of PnP PowerShell.

1. Install PnP PowerShell On the installer’s workstation, ensure PnP PowerShell is installed. You will configure it to connect to Microsoft 365 next.

1
Install-Module PnP.PowerShell -Scope CurrentUser

Create a certificate for PnP PowerShell

Microsoft requires the use of single tenant app registrations with just the scopes and permissions which are needed when using PnP PowerShell.

Once the deployment is completed, you can remove this app registration.

Using your own Certificate Authority (CA)

Recommended for production

Follow your CA’s requirements for creating a SSL certificate. The basic requirements for the certificate are below:

• Cert Name/Common Name: SPARKAutomation
• Subject Name: SPARKAutomation
• Key Length: 2048
• Hash Algorithm: RSA or SHA256
• Key Usage: Digital Signature
• Certificate Validity: 90 days

Be sure to save the password as you will need it for the App Registration configuration.

Recommended for testing/dev environments

Using a self-signed certificate

1. Open Windows PowerShell

2. Review the script below and validate the $pfxOutputPath location for where you want to store the certificate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$certname = "CN=SPARKAutomationPnP"
$certPath = "Cert:\CurrentUser\My"
$pfxOutputPath = "C:\certs\SPARKAutomation_PnP.pfx"
$pfxPassword = ConvertTo-SecureString -String "Sp@rkAutom8tion" -Force -AsPlainText
$cert = New-SelfSignedCertificate `
    -Subject $certname `
    -CertStoreLocation $certPath `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddYears(2)
Export-PfxCertificate `
    -Cert $cert `
    -FilePath $pfxOutputPath `
    -Password $pfxPassword

Create and Export the Certificate

1. From the start menu, type in mmc and open it

1. Click on File and then Add/Remove Snap-in…“

1. Select Certificates and click on Add

2. Select My user account and click on Finish
3. Click on OK

1. Expand Personal and click on Certificates

2. Right-click on the SPARK Automation certificate you created earlier in this section

3. Select All Tasks and click on Export…

1. Walk through the export wizard by clicking on Next using the default properties

Refer to the table below for the wizard selections.

Create the certificate for the Exchange SendMail App Registration

Repeat the same steps from above except for the following items.

• Common Name= SparkAutomation
• Export the private key with the certificate as a .pfx
  • Store the password as you will need to use it during the deployment of the app registration.

Continue to Create the Entra Security Groups