It’s a usual requirement to make our Cloud Service Extended Support (CSES) enable with HTTPS communication.
This blog’s purpose is to give the users who didn’t successfully enable HTTPS in CSES yet a step-by-step instruction. We can refer to the official document about this topic at first to have a basic understanding which will help us go through this blog more easily.
Pre-requirements:
Before starting, you must setup the environment at first.
To set up a local development environment, you need to have:
- Visual Studio. If you don’t install it yet, please kindly find it here.
- A CSES project. In this blog, I used the simplest example project included automatically when we create a CSES project in Visual Studio. You can follow these screenshots to create the same project.
How to create CSES project 1
How to create CSES project 2
How to create CSES project 3
- SSL certificate in .pfx file type. If you already have one assigned by CA, it’ll be great. But if you don’t have one, you can follow this document to use the PowerShell script to self-assign a certificate for test use.
- A KeyVault resource under the same resource group as CSES resource. If you didn’t create it when you created the CSES, please kindly follow this document to create a new one.
Important points to explain before starting:
As normally we can have multiple choices to deploy the CSES project into Azure Cloud, such as deployment from Visual Studio, using ARM template, using CICD tool like DevOps etc. But the nature of them is always the same:
- Prepare your certificate
- Modify your project configuration
- Package the project file into .csdef, .cscfg and .cspkg files
- Do some configuration change on the CSES resource itself if needed, such as Update the packageURL, configuration/configuraitonURL setting, update the OsSecret setting.
- Deploy/Update the new project into Azure Cloud
The above first two points are necessary for whichever way you deploy your project. The following three points are also important but not necessary for every user to do it manually. It may be done automatically by the tool such as Visual Studio.
In the next part, I’ll summarize them into two parts: Code change (necessary part) and Configuration change (Not necessary part for every situation).
Code change:
1. The first step is to upload your certificate into the Azure Key Vault, certificate part. You can follow our official document about this until step 6 since step 7 and 8 will be explained in the next part with more details.
Once it’s done, please kindly note down the thumbprint of the certificate for use in next steps.
2. Then, we need to modify the .cscfg and .csdef files to configure how our CSES project will use the certificate and which certificate will use.
At first, we need to add the following configurations into .cscfg under the role where you want to use this certificate. In this blog, our aim is to use certificate as SSL certificate of HTTPS communication with WebRole so I added it under WebRole1.
Please remember to replace the thumbprint by your own. And also, pay attention to the “name”. You can customize it but we need to make sure this name matches the name in .csdef file in the next step.
<Certificates>
<Certificate name="Certificate1" thumbprint="90901150EC77B73833A7326BDF00712303838613" thumbprintAlgorithm="sha1" />
</Certificates>
Then in the .csdef, we need to configure 3 pieces of code in total.
The bindings will check and use the endpoint HttpsIn. The InputEndpoint will define a new endpoint with HTTPS protocol and the certificate we need to use. And the Certificates will define how the certificate will be installed in the Cloud Service instance.
Please pay attention that the certificate name of the InputEndpoint and Certificate in .csdef and Certificate in .cscfg must be same.
<Binding name="HttpsIn" endpointName="HttpsIn" />
<InputEndpoint name="HttpsIn" protocol="https" port="443" certificate="Certificate1" />
<Certificates>
<Certificate name="Certificate1" storeLocation="LocalMachine" storeName="My" permissionLevel="limitedOrElevated"/>
</Certificates>
Until here, all the necessary changes in code level are done. If you need some more customized configuration, please kindly refer to .csdef schema and .cscfg schema.
Configuration change:
In this part, due to the different deployment method, the needed action could be different. Since it’s impossible to include the non-necessary steps of all the methods of deployment, I’ll focus on all the methods which are recommended officially and documented in the official tutorials about how to deploy new CSES.
Visual Studio:
1. Please copy your ServiceConfiguration.Cloud.cscfg context and paste in ServiceConfiguration.Local.cscfg. If you have different configuration or you still need the local configuration file for further use, please at least add the <certificate> lines in the ServiceConfiguration.Local.cscfg. Otherwise, the Visual Studio cannot recognize correctly and will affect the next step.
2. Follow the same steps of deployment. In the publish configuration window, remember to select the key vault where our certificate is saved.
3. Click on Publish and wait for the deployment finish.
ARM template:
1. Please kindly follow the step 7 to step 10 of this blog to package the project, upload the package and configuration files into storage account container, generate and note down the SAS token URL and note down the secret identifier of the certificate.
2. In your original ARM template of the CSES, pay attention on the “osProfile” property of the CSES resource. If our original CSES project with only HTTP communication is without any extension, then in the osProfile will be blank such as:
To make CSES be able to retrieve the correct certificate from correct KeyVault, we must need to setup in the ARM template which KeyVault we want to use.
You can either use a parameter to input this value or hardcode it in the ARM template, the expected result will be like: (The sourceVault parameter can be found in the address line of the Key Vault page in Azure Portal. The certificateUrl is the secret identifier of the certificate which we note down in step 1)
3. Deploy the new ARM template with the new parameters such as package SAS token, configuration SAS token etc. and wait the deployment finish.
P.S. If here you get the error message like the public IP address is being used, please kindly remove the public IP address part from your .cscfg file and ARM template (only the resource part if it exists, do NOT remove the public IP setting from CSES resource shown in the following screenshot).
The example ARM template and parameter can be found here: CSESHTTPStemplate and CSESHTTPSparameter.
PowerShell:
1. Please kindly follow the step 7 to step 9 of this blog to package the project, upload the .cspkg file into storage account container, generate and note down the SAS token URL. (Only .cspkg file is needed to be uploaded.)
2. Login with Connect-AzAccount, then use following script to update your CSES. Please remember to replace all the information by following table:
|
Variable or command name |
The expected value |
|
cspkgurl |
The SAS token URL of .cspkg file we get from step 1 |
|
cscfgFilePath |
The local path to your .cscfg file |
|
Get-AzKeyVault |
ResourceGroupName for the name of resource group where Key Vault is deployed and VaultName for the name of Key Vault resource |
|
Get-AzKeyVaultCertificate |
VaultName for the name of Key Vault resource and Name for the name of the certificate saved in KeyVault |
$cspkgurl = "https://minalinsky.blob.core.windows.net/cses-https/CSESOneWebRoleHTTPS.cspkg?sp=r&st=2021-11-13T09:02:04Z&se=2021-11-13T17:02:04Z&spr=https&sv=2020-08-04&sr=b&sig=xxxxx%3D"
$cscfgFilePath = "C:\Users\zhangjerry\Desktop\VisualStudioproject\CSESOneWebRoleHTTPS\bin\Release\app.publish\ServiceConfiguration.Cloud.cscfg"
$keyVault = Get-AzKeyVault -ResourceGroupName CSES -VaultName CSESKVault
$certificate = Get-AzKeyVaultCertificate -VaultName CSESKVault -Name csescert
$secretGroup = New-AzCloudServiceVaultSecretGroupObject -Id $keyVault.ResourceId -CertificateUrl $certificate.SecretId
$osProfile = @{secret = @($secretGroup)}
$cses = Get-AzCloudService -Name jerrycsesps -SubscriptionId 5102f0a2-e80b-48c6-8d4b-2834a4473453 -ResourceGroupName CSESPS
$cses.Configuration = Get-Content $cscfgFilePath | Out-String
$cses.PackageUrl = $cspkgurl
$cses.OSProfile = $osProfile
$cses | Update-AzCloudService
Portal:
1. Please kindly follow the step 7 to step 9 of this blog to package the project, upload the .cspkg, .cscfg and .csdef files into storage account container, generate and note down the SAS token URL. (.csdef, .cscfg and .cspkg files are all needed to be uploaded. The .csdef file is not included in the linked blog.)
2. Follow steps to update the CSES project in Azure Portal
- Click on Update from CSES page
Update button in Azure Portal
- Browse and select correct file from blob storage container for corresponding setting
Select uploaded file from storage account 1
Select uploaded files from storage account 2
- Select the Key Vault where we uploaded the certificate in Configuration page
Key Vault setting in Azure Portal
- Once the certificate is found in the selected Key Vault, it will show Found status. Click on Update button and deploy the new project code
Key Vault certificate validation result
SDK:
1. This part code is rewritten based on the official SDK example code which can be found in official github.
2. To successfully use SDK to deploy the CSES project and modify related configuration, an application registered in AAD is the best practice. Please follow these steps:
- Please kindly follow this document to register a new application
- Please assign owner role of whole subscription on this new application
- Please create a new application secret for further use. The detailed instruction can be found here
- Follow this part to configure the access policy of Key Vault and add permission at least the read permission of certificate on our application
- Please kindly note down your tenant ID (which can be found in the home page of AAD), the application ID (which can be found in the app registrations page), and the value of the created secret in step c
Tenant ID in AAD page
Application ID of the registered application
3. Please kindly follow the step 7 to step 10 of this blog to package the project, upload the .cspkg file into storage account container, generate and note down the SAS token URL. (Only .cspkg file is needed to be uploaded.) Also note down the secret identifier of the certificate
4. Download the example project from here
5. Modify the parameters in LoginHelper.cs in line 18, 19 and 20. tenantId is replaced by Tenant ID, clientId is replaced by the application ID and clientCredentials is replaced by the value of secret
6. Modify the parameters in Program.cs file, line 25, line 35 to 45. Please refer to the next table to modify the value
|
Variable |
The expected value |
|
m_subId |
The ID of subscription where the CSES is in |
|
csrgName |
The resource group where the CSES is in |
|
csName |
The CSES resource name |
|
kvrgName |
The resource group where our Key Vault resource is in |
|
kvName |
The Key Vault resource name |
|
kvsubid |
The ID of subscription where the Key Vault is in |
|
secretidentifier |
The secret identifier URL from step 3. |
|
filename |
The local path to your .cscfg file. |
|
packageurl |
The SAS token URL from step 3. |
Attention! In this SDK example code, the Key Vault and CSES are allowed to be in different subscriptions. By default, we set them in the same subscription. If these two resources are in different resource, please modify the line 40, the kvsubid value from m_subId to the real subscription ID
7. Remember to install the dependency Nuget packages. In Visual Studio, we can install it by:
- Right click the project and choose Manage Nuget Packages
Manage NuGet package button in VS
- In the browse page, search for the needed package and install. The required packages are following:
- Microsoft.Azure.Management.ResourceManager
- Microsoft.Azure.Management.Compute
- Microsoft.Azure.Management.Storage
- Azure.Identity
- Microsoft.Rest.ClientRuntime.Azure.Authentication
8. Run the whole project and wait for the message in the command window. If it shows “exit with code 0”, then the update/deployment should be working. If it shows “exit with code 1”, there may be an issue to be checked. Please verify the error message.
Result:
We'll be able to communicate with CSES website by HTTPS protocol. If our certificate is self-signed, the browser may report a warning that the certificate is not secure, but it will not block the traffic.
Posted at https://sl.advdat.com/3rbxT5k
