Configure an SSL Certificate on an HTTPS Endpoint
Updated: February 14, 2014
To add an HTTPS endpoint to a role in your Windows Azure service and associate it with an SSL certificate, you must follow these steps:
Obtain an SSL certificate from a Certificate Authority. For more information, see Obtain an SSL Certificate.
Add the certificate to certificate store for the hosted service. For more information, see the Upload the Certificate to Windows Azure section.
Add the thumbprint of the certificate the service configuration file. For more information, see the Add the Certificate Thumbprint to the Service Configuration File section.
Update the service definition file to identify the certificate to the hosted service. For more information, see the Add the Certificate in the service definition file section.
Configure the HTTPS endpoint in your service definition file, and associate it with the certificate. For more information, see the Configure the HTTPS endpoint section.
Setup a CNAME record for the domain name the SSL certificate is issued against to redirect traffic to the service. For more information about configuring CNAME, see Configuring a custom domain name for a Windows Azure cloud service.
When testing your HTTPS endpoint in the development environment, all authentication occurs using a self-signed certificate provided for 127.0.0.1. See the section titled Testing an HTTPS endpoint in the compute emulator later in this topic for more information.
An SSL certificate that is used to help secure an HTTPS endpoint in Windows Azure must have the following features:
The certificate must contain a private key.
The purpose of the certificate should be Server Authentication.
The subject name for the certificate must match the domain name that is used to access the service.
Requires a minimum crypto key size of 2048-bits.
|If you are using the Windows Azure Tools for Microsoft Visual Studio to develop your service, you can configure an HTTPS endpoint using the property pages for your role.|
Upload the Certificate to Windows Azure
Windows Azure provides a secure certificate store where you can maintain certificates for your hosted service. When you associate a certificate with your service and upload the certificate to the store, Windows Azure automatically deploys the certificate to the VMs on which your role instances are running. For more information about the certificate store, see Manage Certificates.
To upload your certificate to the certificate store, follow these steps in Add a New Certificate to the Certificate Store.
Add the Certificate Thumbprint to the Service Configuration File
The certificate thumbprint in the service configuration file pairs the logical name of the certificate you provided in the service definition file together with the certificate in the store. Maintaining the thumbprint in the service configuration file keeps the certificate data separate from the service package. This allows you or an IT manager can update the certificate without requiring you to redeploy the service.
To list the certificate and its thumbprint in the service configuration file, modify the configuration file, and add the Certificates collection to the entry for your role. Add a Certificate element to the Certificates collection, and specify the logical name for the certificate. Be sure to use the same name that you specified in the service definition file. Finally, specify the certificate's thumbprint and the algorithm that was used to generate the thumbprint, as shown in this example:
<ServiceConfiguration serviceName="MyService"> <Role name=" MyWorkerRole"> <Instances count="5" /> <ConfigurationSettings> . . . </ConfigurationSettings> <Certificates> <Certificate name="MySSLCert" thumbprint="8420C0773626D5137A820156EB5BD9D6FDB9BEE9" thumbprintAlgorithm="sha1"/> </Certificates> </Role> </ServiceConfiguration>
For more information about how to obtain the thumbprint of a certificate, see the “Creating an X.509 v3 certificate” section of Create a Service Certificate for Windows Azure.
Add the Certificate in the service definition file
To associate a certificate with an HTTPS endpoint, you must provide a logical name for the certificate that will be used to identify it in your service. You must also indicate where the certificate is stored on the virtual machine that is running an instance of your role.
In your service definition file, add the Certificates element to the definition of your role. Within the Certificates collection, add an entry for your certificate, as shown in this example:
<WorkerRole name="MyWorkerRole" vmsize="Small"> <ConfigurationSettings> . . . </ConfigurationSettings> <LocalResources> . . . </LocalResources> <Endpoints> . . . </Endpoints> <Certificates> <Certificate name="MySSLCert" storeLocation="LocalMachine" storeName="My" /> </Certificates> </WorkerRole> </ServiceDefinition>
In this example, the store location is set to LocalMachine, and the store name is set to My. These two attributes indicate where on the VM the certificate (identified here as
MySSLCert) will be installed.
You can select any name that you like for the certificate's name attribute. You will use this name only to refer to the certificate in the definition for the HTTPS endpoint and in the service configuration file.
Configure the HTTPS endpoint
To add an HTTPS endpoint to your role, edit your service definition file, and add an InputEndpoint element to the Endpoints collection for your role. Specify a name for the endpoint, the protocol (HTTPS), and the port. Then specify the logical name for the certificate you defined in the role's Certificates collection.
The following procedure shows how to add an HTTP input endpoint for a web role that listens on port 80 and also defines an HTTPS endpoint that listens on port 443:
To configure the HTTPS endpoint
Open the ServiceDefinition.csdef file for your service in the text editor.
Add the Certificates collection element that contains an Certificate element to the role element to the role that is being secured using SSL. Set the name attribute to the name of your certificate. Set the storeLocation and storeName attributes to specify the location of the certificate in the virtual machine.
<Certificates> <Certificate name="MySSLCert" storeLocation="LocalMachine" storeName="My" /> </Certificates>
Add the Endpoints collection element that contains the InputEndpoint elements to the role element to the role that is being secured using SSL. Set the certificate attribute of the HttpsIn input endpoint to match the certificate name specified in the certificates collection.
<Endpoints> <InputEndpoint name="HttpIn" protocol="http" port="80" /> <InputEndpoint name="HttpsIn" protocol="https" port="443" certificate="MySSLCert" /> </Endpoints>
Save the file.
The completed service definition will resemble the following example.
<ServiceDefinition name="MyService"> <WorkerRole name="MyWorkerRole"> <ConfigurationSettings> . . . </ConfigurationSettings> <LocalResources> . . . </LocalResources> <Endpoints> <InputEndpoint name="HttpIn" protocol="http" port="80" /> <InputEndpoint name="HttpsIn" protocol="https" port="443" certificate="MySSLCert" /> </Endpoints> <Certificates> <Certificate name="MySSLCert" storeLocation="LocalMachine" storeName="My" /> </Certificates> </WorkerRole> </ServiceDefinition>
Testing an HTTPS endpoint in the compute emulator
By default the compute emulator relies on a self-signed certificate for the IP address 127.0.0.1, which corresponds to localhost. If there was a problem installing or configuring the certificate that you configured in the previous steps, the compute emulator will default to authenticating against this self-signed certificate instead of your custom certificate. If your deployment defaults to using an SSL certificate for 127.0.0.1 even though you have defined a different certificate, check to make sure that your custom certificate has no errors and is correctly installed.
By default the self-signed certificate that is used by the compute emulator is not root-trusted. When you browse to the HTTPS, you will receive a certificate error unless you add the certificate to the Trusted Root Certification Authorities store on the local computer. You can ignore the error, or you can add the certificate to the trusted root to eliminate it.
When running the hosted service in the Windows Azure compute emulator, the SSL port maybe set to something other than 443 (often 444 or 445.) If a port that you specify is not available, for an HTTPS endpoint 443, the compute emulator will increment the port number until it finds one that is free.
To use port 443 you must shutdown the application or web site that is using the port, exit, and restart the compute emulator to reload the list of available ports. Shutting down and restarting the emulator does not reload the list of available ports.
To determine whether the port 443 is being used, you can open a command prompt and use the NETSTAT command. For more information about the NETSTAT command, see Netstat.
Using a Self-Signed Certificate with Your Service
If you do not have a certificate that has been issued by a certification authority, you can generate a self-signed certificate for use with your Windows Azure service.
|This self-signed certificate is separate from the one used by the development environment. That certificate is provided for you and used for authentication in the development environment only.|
When you browse to an HTTPS endpoint that's associated with a self-signed certificate in Windows Azure, you will see a certificate error in the browser. By using a certificate signed by a certification authority will eliminate this problem; in the meantime, you can ignore the error.