JavaInterop - Setting up Remote Desktop connectivity for your Java app in Windows Azure

If you can log into the computer in the Windows Azure cloud where you're deploying your Java application, that can simplify your troubleshooting, diagnostics, tool deployment, debugging, or just simply learning and playing around with the platform. It can make the cloud look and feel as if it's your own desktop computer with its highly visual, real-time interactivity. Hence, remote access is an important part of the cloud development experience. This tutorial will teach you how you can easily and quickly enable remote access in your Windows Azure cloud using the Windows Azure Starter Kit for Java.

Download the Windows Azure Starter Kit for Java

You will need to download the Windows Azure Starter Kit for Java from the CodePlex project page (v1.4 or later). The files can be found at: http://wastarterkit4java.codeplex.com/

The Windows Azure Starter Kit for Java uses Apache Ant as part of the build process. If you are not familiar with Ant, go check the installation manual which can be found at http://ant.apache.org/manual/index.html. Ant can be downloaded from the Apache project page at http://ant.apache.org

This tutorial only focuses on the remote access capabilities the Starter Kit provides you with. To learn more about the Windows Azure Starter Kit for Java commandline tools in general, see Deploying a Java application to Windows Azure with Command-line Ant.

Using the "Out of the Box" remote access configuration

The Starter Kit is a set of files that play a dual function:

It is a command-line toolset for building Windows Azure packages using Apache Ant
It is a self-contained, sample Window Azure project with some pre-configured settings and deployment files that works "out of the box". It can even be seamlessly imported into Eclipse if needed, though if you're working with Eclipse a lot, you will want to get the Windows Azure Plugin for Eclipse with Java.

Among the "out of the box" functionality included in the Starter Kit is the pre-configured ability to use Remote Desktop to connect to your Windows Azure cloud, with only minimal configuration changes needed. You do not even need to deploy any of your own files or code to take advantage of this, the nearly empty package created by the Starter Kit "out of the box" will have everything you need.

Note: The Starter Kit's "out of the box" remote access configuration is intended for educational purposes only. The certificate it relies on, and its private key password, are publicly known and thus provide no extra security, so you should replace the certificate with your own as soon as you start using the Starter Kit for anything beyond educational purposes. Read the rest of this tutorial to find out how.

In general, the following basic steps are needed from the moment you download Starter Kit to the moment you log into your running role instance in the Windows Azure cloud:

Build a deployment package configured for the cloud
Deploy your package and certificate to the cloud
Set a login password for remote access
Start a Remote Desktop connection from the Windows Azure portal

Here's a detailed walkthrough of each of these steps:

Build a deployment package configured for the cloud:
1. Open the package.xml file from the project directory and set packagetype attribute inside the <windowsazurepackage> tag to "cloud", then save.
```
<windowsazurepackage packagetype="cloud" …>
```
2. To build, make sure to have Apache Ant command-lineinstalled and run this command inside your project directory
```
ant -buildfile package.xml
```
Deploy your package and certificate to the cloud

(The instructions below refer to controls in the screenshots using numbers, like [1])

You will be working with the Windows Azure portal, so first, using your web browser, log into the main portal page at http://windows.azure.com and navigate to your hosted services list [1, 2]:

Depending on whether you are creating a new hosted service, or uploading into an existing one, the next set of details are a bit different:
- Creating a new hosted service- If you're creating a new hosted service, then follow these steps:
  1. Click New Hosted Service[3]:
  2. On the form that shows up, specify the package location [4]:
    <your project>\deploy\WindowsAzurePackage.cspkg
  3. Specify the configuration file [5]:
    <your project>\deploy\ServiceConfiguration.cscfg
  4. Click Add Certificate[6]:
  5. In the Upload Certificate prompt, specify the certificate file [7]:
    <your project>\cert\SampleRemoteAccessPrivate.pfx
  6. For the password [8], use: Password1
  7. Click OK on the open dialogs and wait a few minutes while Windows Azure deploys your package and provisions your compute instance, until you see Ready in the Status column for your role instance.
- Deploying to an existing hosted service- if your hosted service already exists, and you just want to deploy your new package to it, then follow these steps instead:
  1. Select the Certificates node [3] under you hosted service
  2. Click Add Certificate[4]
  3. When prompted for the certificate file location [5], use:
    <your project>\cert\SampleRemoteDesktopPrivate.pfx
  4. For the password [6], type in: Password1
  5. Click Create [7]. (You will then see a certificate in your Certificates list under the label "Windows Azure Tools")
  6. Next, you need to upload your deployment files. For that, first select the hosted service node [8]
  7. Click New Staging Deployment[9]
  8. On the form that shows up, specify the package location [10]:
    <your project>\deploy\WindowsAzurePackage.cspkg
  9. Specify the configuration file [11]:
    <your project>\deploy\ServiceConfiguration.cscfg, and click OK. If you get a warning prompt, just ignore it for now (click Yes).
  10. Now wait a few minutes while Windows Azure deploys your package and provisions your compute instance, until you see Ready in the Status column for your role instance entry.
Set a login password for Remote Access

The "out of the box" configuration in the Starter Kit does not include a login password for remote access. You need to set it yourself in the Windows Azure portal by following these steps:
1. Once the role instance is Ready, select the Role node [1] (not Role Instance) and click Configure[2] in the Remote Access section of the UI
2. In the form that shows up, you will see the User name[3] listed is "test". Feel free to change it if you'd like to, but you don't have to.
3. Specify a login Password[4] for that user name. The password needs to meet the Windows 2008 R2 Server strength requirements. There will be a helpful message popping up whenever your password is not strong enough.
4. Click OK, and wait for the Role instance to go back to Ready state (it will show as Updating… for a while)
Start a Remote Desktop connection from the Windows Azure portal
1. Once the role instance is Ready again, select the Role Instance node [1] (not Role) and click Connect[2] in the Remote Access section of the UI
2. A number of security-related prompts will follow. Just accept them and allow Remote Desktop to be turned on.
  
  ; ;
  
  You should now see a familiar Remote Desktop login screen, where you can log in using the credentials (user name and password) you specified earlier:
  
  ; ;
  
  After another security prompt (because of the self-signed certificate), which you should say Yes to, you will see the familiar Windows Server 2008 desktop!

Creating a new self-signed remote access certificate

For better security, you should replace the sample remote access certificate files included in Starter Kit with your own.

If you are not yet ready to use a trusted certificate issued by a certificate authority, you can use a "quick and dirty" self-signed certificate. This is more secure than the publicly known certificate included in the Starter Kit distribution, but still not as trustworthy as an authority-issued one, so it is not generally recommended for use in anything other than basic testing. If you want to create a certificate like that though, then use the encutil.exe command-line utility provided on the Starter Kit's project site: http://wastarterkit4java.codeplex.com, with the following command-line:

encutil.exe -create -cert "MyNewKey.cer" -pfx "MyNewKey.pfx" -alias "MyNewKey" -pwd MyNewPassword

Here of course, you will want to replace "MyNewKey.*" with whatever filenames you choose, use whatever alias you choose (it does not matter), and specify a new certificate password in place of MyNewPassword. This will create two self-signed certificate files, both representing the same private/public key pair.

MyNewKey.pfx will contain both the public key and the private key, and therefore needs to be secured with a password (MyNewPassword). This is the certificate file that Windows Azure requires you to upload in order to enable it to decrypt the password you will specify inside ServiceConfiguration.cscfg (more on that later).

Note: The password you use for the self-signed PFX certificate is NOT the same as the password you use for remote access login.

MyNewKey.cer will contain only the public key and hence does not require a password to use it. You will need this certificate file later for encrypting your remote access password, as well as for computing the thumbprint of the certificate for Azure to be able to identify it when you reference it. It is a separate file because in a typical development shop environment, the PFX file (along with its password) should be accessible only to highly privileged administrators or IT, while the CER file (public key only) is needed by developers to configure remote access in their deployment packages for testing and troubleshooting purposes.

Now just delete the SampleRemoteDesktopPrivate.pfx and SampleRemoteDesktopPublic.cer files from your project's directory, and replace them with your newly created certificate files.

Also, remember to delete the SampleRemoteDesktopPrivate.pfx file from your hosted service in the Windows Azure portal and replace it with the newly created PFX file.

Note: If none of the PFX certificate files you've uploaded to Windows Azure matches the thumbprint referenced by your Windows Azure package (inside ServiceConfiguration.cscfg), the Windows Azure portal will reject your package upload

Specifying the remote access login credentials

Certificate thumbprint

In order for Windows Azure to recognize your remote access configuration as valid, the certificate thumbprint referenced inside ServiceConfiguration.cscfg must correspond to a matching certificate you have uploaded. To get the thumbprint of a newly created certificate, use the previously mentioned encutil.exe as follows:

encutil.exe -thumbprint -cert "MyNewKey.cer"

Where "MyNewKey.cer" corresponds to the CER file you created earlier. This will output a sequence of characters. Make sure to copy that sequence carefully into the thumbprint attribute of the <Certificate> tag, whose name attribute is "Microsoft.WindowsAzure.Plugins.RemoteAccess.PasswordEncryption", inside ServiceConfiguration.cscfg,. Here's an example:

<ServiceConfiguration serviceName="WindowsAzureProject" 
    xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" 
    osFamily ="1" osVersion="*">
    <Role name="WorkerRole1">
    ...
        <Certificates> 
            <Certificate 
                name="Microsoft.WindowsAzure.Plugins.RemoteAccess.PasswordEncryption"
                thumbprint="875F1656A34D93B266E71BF19C116C39F16B6987"
                thumbprintAlgorithm="sha1"/>
        </Certificates>

    </Role>
</ServiceConfiguration>

Remote access password

As you have seen earlier, specifying a remote access password is not actually required in the deployment package itself - you can always do that later, after uploading it via the Windows Azure portal. But if you would like to hard-code an encrypted remote access password straight into your deployment package then follow these steps: (This can be especially helpful in iterative development scenarios, where you need to upload a new package rather often)

First, encrypt a password of your choice using encutil.exe as follows:

encutil.exe -encrypt -text "MyNewPassword" -cert "MyNewKey.cer" >> encryptedPwd.txt

where MyNewPassword should be a strong password of your choice. This will put a long string of characters into encryptedPwd.txt. Then open encryptedPwd.txt in a text editor (with no automatic new-line insertion) and copy this string carefully in its entirety into the password attribute of the <Setting> element whose name attribute is: "Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountEncryptedPassword", inside ServiceConfiguration.cscfg,for example like this:

<ServiceConfiguration serviceName="WindowsAzureProject" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" osFamily="1" osVersion="*">
    <Role name="WorkerRole1">
        <ConfigurationSettings>
            <Setting
                name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountEncryptedPassword"
                value="MIIBnQYJKoZIhvcNAQcDoIIBjjCCAYoCAQAxggFOMIIBSgIBADAyMX4xHDA3BgNVBAMTE1dpbmRvd3MgQXp1cmUgVG9vbHMCEHT1t9jkXoOuRSE1dvwO71AwDQYJKoZIhvcNAQEBBQAEggEAPrO35AgUEoe40v2NqUw+3bF+LGZvSN67YME7naUYnOozhKRBboZwFGzUa/VHbZXcBL+BL48GjSGlqvvi0FgOO2a7jAtw5LqBpz7EAKf69KIRMts+wFTfJH84IH56511GZWc7uFfzG6qEdtj2N/XCv3z6TP7tAdXXAJ9rUAtg0lz0AqgtZabbLkrBiBkoYXz+cu67IWO7Nn9mgQEb1n1qz/3HMAIthLIhUAZY0Ff6ptBIq2GQQi1P9krpbgJuX9Wbun0HauHUf16/Q4PpKuikNEG3NHayF2K8b8maWkjyDhnncxLg3DKLr+pgn4PBdISvX8L9kIuPTyI+l4Da0kxDizAzBgkqhkiG9w0BBwEwFAYIKoZIhvcNAwcECFJnyhF95/8TgBAW486gxA79BgX83S37GjI0"/>
    ...

The encrypted password should be copied over as a single, uninterrupted string, make sure no new-lines characters are included.

User name

While you're setting a new password, you may also change the user name if you wish, just modify the <Setting> tag whose name is "Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountUsername", for example like this:

<ServiceConfiguration serviceName="WindowsAzureProject" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" osFamily="1" osVersion="*">
  <Role name="WorkerRole1">
    <ConfigurationSettings>
      <Setting 
        name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountUsername" 
        value="test"/>
    ...

Now save your ServiceConfiguration.cscfg file and you are ready to redeploy your package via Windows Azure portal, using the same deployment steps as described at the beginning of this tutorial, just using your own certificate files and passwords instead of the sample ones.

Disabling remote access

Remote access is enabled by default in the current Starter Kit, and it is recommended that you keep it that way at least as long as you're troubleshooting your deployments and learning about Windows Azure. There may be circumstances when you wish to disable it though. To do that, remove all the XML elements from ServiceConfiguration.cscfg, ServiceDefinition.csdef and package.xml that mention RemoteAccess and RemoteForwarder in their attributes. More specifically:

ServiceConfiguration.cscfg: remove all the <Setting> elements that mention RemoteAccess and RemoteForwarder in the name attribute.
ServiceConfiguration.cscfg: remove the <Certificate> element that mentions RemoteAccess in the name attribute
ServiceDefinition.csdef: remove the <Import> elements that mention RemoteAccess and RemoteForwarder in the name attribute
package.xml: remove the <property> element that has its name attribute set to "project.enableremoteaccess"

To re-enable remote access later, you will need to recreate this removed XML markup.

Setting up Remote Desktop connectivity for your Java app in Windows Azure

Table of Contents