Skip to content

Commit 0000b76

Browse files
author
Florian Wagner
authored
Added PowerShell style documentation (#17)
* Update to support PowerShell Core & Linux Signed-off-by: Florian Wagner <florian.wagner@microsoft.com> * PowerShell style doc - fixed nslookup in CreateSSL Signed-off-by: Florian Wagner <florian.wagner@microsoft.com>
1 parent 4ceff5e commit 0000b76

16 files changed

Lines changed: 536 additions & 262 deletions

‎Deploy/ActivateSSL.ps1‎

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,39 @@
1-
###
2-
#
3-
# Activate Custom Domain Name SSL Certificate and activate TrafficManager Endpoints
4-
#
5-
# This script will do following steps:
6-
#
7-
# 1. Import information from previous Terraform runs
8-
# 2. Terraform execution to activate certificate and map TrafficManager endpoints
9-
# 3. Update Bot Endpoint
10-
#
11-
# After the script is successfully executed the bot should be in a usable from WebChat
12-
#
13-
###
14-
# Parameters
1+
<#
2+
.SYNOPSIS
3+
Activate Custom Domain Name SSL Certificate and activate TrafficManager Endpoints
4+
5+
.DESCRIPTION
6+
Activate Custom Domain Name SSL Certificate and activate TrafficManager Endpoints
7+
8+
This script will do following steps:
9+
10+
1. Import information from previous Terraform runs
11+
2. Terraform execution to activate certificate and map TrafficManager endpoints
12+
3. Update Bot Endpoint
13+
14+
After the script is successfully executed the bot should be in a usable state from WebChat
15+
16+
.EXAMPLE
17+
.\ActivateSSL.ps1 -YOUR_DOMAIN bot.mydomain.com
18+
19+
.INPUTS
20+
None. You cannot pipe objects.
21+
22+
.OUTPUTS
23+
System.Boolean. Sucessful execution
24+
25+
#>
1526
param(
16-
# Only needed in Issuing Mode
27+
# The domain (CN) name for the SSL certificate
1728
[Parameter(HelpMessage="The domain (CN) name for the SSL certificate")]
1829
[string] $YOUR_DOMAIN,
1930

31+
#Terraform and SSL creation Automation Flag. $False -> Interactive, Approval $True -> Automatic Approval
2032
[Parameter(HelpMessage="Terraform and SSL creation Automation Flag. `$False -> Interactive, Approval `$True -> Automatic Approval")]
2133
[bool] $AUTOAPPROVE = $False,
22-
23-
[Parameter(HelpMessage="KeyVault certificate name")]
34+
35+
#KeyVault certificate key name
36+
[Parameter(HelpMessage="KeyVault certificate key name")]
2437
[string] $KEYVAULT_CERT_NAME = "SSLcert"
2538
)
2639
# Import Helper functions

‎Deploy/CheckExistingSSL.ps1‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,30 @@
1-
###
2-
#
3-
# Check if already a SSL certificate was imported to KeyVault
4-
#
5-
# This script will do following steps:
6-
#
7-
# 1. Read values from Terraform IaC run (Bot deployment scripts)
8-
# 2. Check if certificate exists in Key Vault
9-
#
10-
# Returns $True if certificate already exists
11-
#
12-
###
13-
# Parameters
1+
<#
2+
.SYNOPSIS
3+
Check if already a SSL certificate was imported to KeyVault
4+
5+
.DESCRIPTION
6+
Check if already a SSL certificate was imported to KeyVault
7+
8+
This script will do following steps:
9+
10+
1. Read values from Terraform IaC run (Bot deployment scripts)
11+
2. Check if certificate exists in Key Vault
12+
13+
Returns $True if certificate already exists
14+
15+
.EXAMPLE
16+
.\CheckExistingSSL.ps1 -KEYVAULT_CERT_NAME SSLcert
17+
18+
.INPUTS
19+
None. You cannot pipe objects.
20+
21+
.OUTPUTS
22+
System.Boolean. Returns $True if certificate already exists
23+
24+
#>
1425
param(
15-
[Parameter(HelpMessage="KeyVault certificate name")]
26+
#KeyVault certificate key name
27+
[Parameter(HelpMessage="KeyVault certificate key name")]
1628
[string] $KEYVAULT_CERT_NAME = "SSLcert"
1729
)
1830
# Import Helper functions

‎Deploy/CreateOrImportSSL.ps1‎

Lines changed: 47 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,77 @@
1-
###
2-
#
3-
# Import existing or create/issue new SSL certificate
4-
#
5-
# This script will do following steps:
6-
#
7-
# In Import Mode
8-
# 1. Execute Import script
9-
#
10-
# In Issuing Mode
11-
# 1. Execute Issuing script
12-
#
13-
# 2. Terraform execution to activate certificate
14-
#
15-
# After the script is successfully executed the Bot should be in a usable from within Bot Framework Service (WebChat) and Emulator
16-
#
17-
###
18-
# Parameters
1+
<#
2+
.SYNOPSIS
3+
Import existing or create/issue new SSL certificate
4+
5+
.DESCRIPTION
6+
Import existing or create/issue new SSL certificate
7+
8+
This script will do following steps:
9+
10+
1. Validate Parameters
11+
12+
2. Deactivate SSL Endpoints (in FORCE mode e.g. changing certificate or changing to custom domain name)
13+
14+
In Import Mode
15+
3. Execute Import script
16+
17+
In Issuing Mode
18+
3. Execute Issuing script
19+
20+
4. Terraform execution to activate certificate
21+
22+
After the script is successfully executed the Bot should be in a usable from within Bot Framework Service (WebChat) and Bot Emulator
23+
24+
.EXAMPLE
25+
.\CreateOrImportSSL.ps1 -YOUR_CERTIFICATE_EMAIL my@mymail.com -YOUR_DOMAIN bot.mydomain.com -LETS_ENCRYPT_STAGING $False -AUTOAPPROVE $True
26+
27+
.EXAMPLE
28+
.\CreateOrImportSSL.ps1 -PFX_FILE_LOCATION ../SSL/mybot.pfx -PFX_FILE_PASSWORD securesecret -AUTOAPPROVE $False
29+
30+
.INPUTS
31+
None. You cannot pipe objects.
32+
33+
.OUTPUTS
34+
System.Boolean. Returns $True if executed successfully
35+
36+
#>
1937
param(
20-
# Only needed in Issuing Mode
38+
# Mail to be associated with Let's Encrypt certificate
2139
[Parameter(HelpMessage="Mail to be associated with Let's Encrypt certificate")]
2240
[string] $YOUR_CERTIFICATE_EMAIL,
2341

24-
# Only needed in Issuing Mode
42+
# The domain (CN) name for the SSL certificate
2543
[Parameter(HelpMessage="The domain (CN) name for the SSL certificate")]
2644
[string] $YOUR_DOMAIN,
2745

28-
# Only needed in Issuing Mode
46+
# $True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service) - Default: $False
2947
[Parameter(HelpMessage="`$True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service) - Default: `$False")]
3048
[string] $LETS_ENCRYPT_STAGING = $False,
3149

50+
# SSL CERT (PFX Format) file location
3251
[Parameter(HelpMessage="SSL CERT (PFX Format) file location")]
3352
[string] $PFX_FILE_LOCATION,
3453

54+
# SSL CERT (PFX Format) file password
3555
[Parameter(HelpMessage="SSL CERT (PFX Format) file password")]
3656
[string] $PFX_FILE_PASSWORD,
3757

38-
[Parameter(HelpMessage="KeyVault certificate name")]
58+
# KeyVault certificate key name
59+
[Parameter(HelpMessage="KeyVault certificate key name")]
3960
[string] $KEYVAULT_CERT_NAME = "SSLcert",
4061

62+
# Terraform and SSL creation Automation Flag. $False -> Interactive, Approval $True -> Automatic Approval
4163
[Parameter(HelpMessage="Terraform and SSL creation Automation Flag. `$False -> Interactive, Approval `$True -> Automatic Approval")]
4264
[bool] $AUTOAPPROVE = $False,
4365

66+
# Flag to determine if run from within OneClickDeploy.ps1
4467
[Parameter(HelpMessage="Flag to determine if run from within OneClickDeploy.ps1")]
4568
[bool] $ALREADYCONFIRMED = $False,
4669

70+
# Force Reimport or Reissuing if certificate already exists
4771
[Parameter(HelpMessage="Force Reimport or Reissuing if certificate already exists")]
4872
[bool] $FORCE = $False,
4973

74+
# To change existing infrastructure, e.g. skips DNS check. $False -> first run/no infrastructure, $True -> subsequent run, existing infrastructure
5075
[Parameter(HelpMessage="To change existing infrastructure, e.g. skips DNS check. `$False -> first run/no infrastructure, `$True -> subsequent run, existing infrastructure")]
5176
[bool] $RERUN = $False
5277
)

‎Deploy/CreateSSL.ps1‎

Lines changed: 49 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,54 @@
1-
###
2-
#
3-
# Issue new SSL certificate from Let's Encrypt
4-
#
5-
# This script will do following steps:
6-
#
7-
# 1. Read values from previous Infrastructure Deployment run (Terraform & Bot Deployment)
8-
# 2. Terraform execution to spin up container who issues SSL cert and stores in KeyVault
9-
# 3. Check if certificate was created
10-
# 3. Terraform destroy to clean up resources only need for SSL issuing
11-
#
12-
# After the script is successfully executed the certificate should be stored in KeyVault
13-
#
14-
###
15-
# Parameters
1+
<#
2+
.SYNOPSIS
3+
Issue new SSL certificate from Let's Encrypt
4+
5+
.DESCRIPTION
6+
Issue new SSL certificate from Let's Encrypt
7+
8+
This script will do following steps:
9+
10+
1. Read values from previous Infrastructure Deployment run (Terraform & Bot Deployment)
11+
2. If custom domain is set, check if it points to TrafficManager DNS entry
12+
3. Terraform execution to spin up container who issues SSL cert and stores in KeyVault
13+
4. Check if certificate was created
14+
5. Terraform destroy to clean up resources only need for SSL issuing
15+
16+
After the script is successfully executed the certificate should be stored in KeyVault
17+
18+
.EXAMPLE
19+
.\CreateSSL.ps1 -YOUR_CERTIFICATE_EMAIL my@mymail.com -YOUR_DOMAIN bot.mydomain.com -LETS_ENCRYPT_STAGING $False -AUTOAPPROVE $True
20+
21+
.INPUTS
22+
None. You cannot pipe objects.
23+
24+
.OUTPUTS
25+
System.Boolean. Returns $True if executed successfully
26+
27+
#>
1628
param(
29+
# Mail to be associated with Let's Encrypt certificate
1730
[Parameter(Mandatory=$true, HelpMessage="Mail to be associated with Let's Encrypt certificate")]
1831
[ValidatePattern("(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|""(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*"")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])")]
1932
[string] $YOUR_CERTIFICATE_EMAIL,
2033

34+
# The domain (CN) name for the SSL certificate
2135
[Parameter(HelpMessage="The domain (CN) name for the SSL certificate")]
2236
[string] $YOUR_DOMAIN,
2337

38+
39+
# $True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service) - Default: $False
2440
[Parameter(HelpMessage="`$True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service) - Default: `$False")]
2541
[string] $LETS_ENCRYPT_STAGING = $False,
2642

43+
# Terraform Automation Flag. $False -> Interactive, Approval $True -> Automatic Approval
2744
[Parameter(HelpMessage="Terraform Automation Flag. `$False -> Interactive, Approval `$True -> Automatic Approval")]
2845
[bool] $AUTOAPPROVE = $False,
2946

30-
[Parameter(HelpMessage="KeyVault certificate name")]
47+
# KeyVault certificate key name
48+
[Parameter(HelpMessage="KeyVault certificate key name")]
3149
[string] $KEYVAULT_CERT_NAME = "SSLcert",
3250

51+
# Maximum wait time for DNS resolve and certificate generation in minutes. Default 15 min
3352
[Parameter(HelpMessage="Maximum wait time for DNS resolve and certificate generation in minutes. Default 15 min")]
3453
[int] $MAX_WAIT_TIME_MIN = 15
3554
)
@@ -57,8 +76,8 @@ $success = $success -and $?
5776
$TrafficManager = terraform output -state="$(Get-ScriptPath)/$iaCFolder/terraform.tfstate" -json trafficManager | ConvertFrom-Json
5877
$success = $success -and $?
5978

60-
# 2. Apply Terraform for SSLIssuing
61-
Write-Host "## 2. Apply Terraform for SSLIssuing"
79+
# 2. If custom domain is set, check if it points to TrafficManager DNS entry
80+
Write-Host "## 2. If custom domain is set, check if it points to TrafficManager DNS entry"
6281

6382
if ($YOUR_DOMAIN -eq "")
6483
{
@@ -73,22 +92,27 @@ elseif ($YOUR_DOMAIN -ne $TrafficManager.fqdn) {
7392
# If a custom domain is set check if CNAME to TrafficManager FQDN is set
7493
# Not working in PowerShellCore: $resolved = Resolve-DnsName -Name $YOUR_DOMAIN -DnsOnly 2> $null
7594
# Changing to nslookup
76-
$resolved = nslookup $FQDN 2> $null
95+
$resolved = nslookup $YOUR_DOMAIN 2> $null
7796
while (((($resolved | Select-String $TrafficManager.fqdn).Length -eq 0)) -and ($loopcount -le $loopmax))
7897
{
7998
$loopcount++
8099
Write-Host "### WARNING, there is no CNAME entry for domain '$YOUR_DOMAIN' pointing to '$($TrafficManager.fqdn)'."
81100
Write-Host "### Please check your DNS entry, or create the missing CNAME entry. Sleeping for $waitretrysec seconds and try again..."
82101
Start-Sleep -s $waitretrysec
83-
#$resolved = Resolve-DnsName -Name $YOUR_DOMAIN -DnsOnly 2> $null
84-
$resolved = nslookup $FQDN 2> $null
102+
103+
# Not working in PowerShellCore: $resolved = Resolve-DnsName -Name $YOUR_DOMAIN -DnsOnly 2> $null
104+
# Changing to nslookup
105+
$resolved = nslookup $YOUR_DOMAIN 2> $null
85106
}
86107

87108
# delete dummy endpoint again
88109
az network traffic-manager endpoint delete --name dummy --type externalEndpoints --profile-name $TrafficManager.name --resource-group $TrafficManager.resource_group > $null
89110
# TrafficManager healthcheck profile will be changed back in SSLActivate Terraform (ActivateSSL.ps1)
90111
}
91112

113+
# 3. Apply Terraform for SSLIssuing
114+
Write-Host "## 3. Apply Terraform for SSLIssuing"
115+
92116
# Terraform Init
93117
terraform init "$(Get-ScriptPath)/$terraformFolder"
94118
# Terraform Apply
@@ -100,8 +124,8 @@ terraform apply -var "keyVault_name=$($KeyVault.name)" -var "keyVault_rg=$($KeyV
100124
-var "production=$PRODUCTION" -state="$(Get-ScriptPath)/$terraformFolder/terraform.tfstate" $(Get-TerraformAutoApproveFlag $AUTOAPPROVE) "$(Get-ScriptPathTerraformApply)/$terraformFolder"
101125
$success = $success -and $?
102126

103-
# 3. Check for creation of certificate
104-
Write-Host "## 3. Check for availability of certificate"
127+
# 4. Check for creation of certificate
128+
Write-Host "## 4. Check for availability of certificate"
105129
$loopcount = 0
106130
az keyvault certificate show --vault-name $KeyVault.name --name $KEYVAULT_CERT_NAME > $null 2> $1
107131
while ($? -eq $False -and ($loopcount -le $loopmax))
@@ -114,8 +138,8 @@ while ($? -eq $False -and ($loopcount -le $loopmax))
114138
$success = $success -and $?
115139
Write-Host "## Certificate found!"
116140

117-
# 4. Destroy Terraform SSLIssuing
118-
Write-Host "## 4. Destroy unneccessary infrastructure again"
141+
# 5. Destroy Terraform SSLIssuing
142+
Write-Host "## 5. Destroy unneccessary infrastructure again"
119143

120144
# Terraform Init (should not be needed)
121145
terraform init "$(Get-ScriptPath)/$terraformFolder"

‎Deploy/DeactivateSSL.ps1‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,25 @@
1-
###
2-
#
3-
# Deactivate SSL Certificate when in direct use with TrafficManager Domain
4-
#
5-
# This script will do following steps:
6-
#
7-
# 1. Read relevant data of TrafficManager from Terraform Infrastructure execution
8-
# 2. Delete all TrafficManager endpoints, this will also remove the custom domain name entry from WebApps automatically
9-
#
10-
###
11-
# Parameters
1+
<#
2+
.SYNOPSIS
3+
Deactivate SSL Certificate when in direct use with TrafficManager Domain
4+
5+
.DESCRIPTION
6+
Deactivate SSL Certificate when in direct use with TrafficManager Domain
7+
8+
This script will do following steps:
9+
10+
1. Read relevant data of TrafficManager from Terraform Infrastructure execution
11+
2. Delete all TrafficManager endpoints, this will also remove the custom domain name entry from WebApps automatically
12+
13+
.EXAMPLE
14+
.\DeactivateSSL.ps1
15+
16+
.INPUTS
17+
None. You cannot pipe objects.
18+
19+
.OUTPUTS
20+
System.Boolean. Returns $True if executed successfully
21+
22+
#>
1223
param(
1324

1425
)

0 commit comments

Comments
 (0)