Gaurav Mantri's Personal Blog.

About Windows Azure Publish Settings File and how to create your own Publish Settings File

In this blog post I’m going to talk about the publish settings file for Windows Azure and how you can create your own publish settings file.

Publish Settings File

In this section we’re going to talk about publish settings file, how it works, and some observations about using this file. If you’re aware of this, please feel free to skip this section.

What Is It?

A publish settings file is an XML file which contains information about your subscription. It contains information about all subscriptions associated with a user’s Live Id (i.e. all subscriptions for which a user is either an administrator or a co-administrator). It also contains a management certificate which can be used to authenticate Windows Azure Service Management API requests. Typically a publish settings file look something like this:


<?xml version="1.0" encoding="utf-8"?>
<PublishData>
  <PublishProfile
    PublishMethod="AzureServiceManagementAPI"
    Url="https://management.core.windows.net/"
    ManagementCertificate="MIIKPAIBAzCCCfwGCSqGSIb3DQEHAaCCCe0EggnpMIIJ5TCCBe4GCSqGSIb3DQEHAaCCBd8EggXbMIIF1zCCBdMGCyqGSIb3DQEMCgECoIIE7jCCBOowHAYKKoZIhvcNAQwBAzAOBAhSgQEdjGWWzgICB9AEggTI7EIY9TKTWkDqxG+j9Bnxw8k4a5OC3hw4lp8r/5Ch7uJ4AuY2cxNf+pt2gqejjcwxdhNn+suzebsrs3cI/7NEHka+hrxBrjZH1e5bUDjUAWYY6nm6iZYveS53nKcuwZHIjTrGBTa0xQSfMcBs5I5WaVfHVEKtVp67pLsInGBy+uExXwVk2/SmZFjKlKenQfSrnexUKvDt8WibWd/O42sqYIwcDPaKccSbbGNylFDal0cEkDLKPvpWBVwmPXsfPVcOuGKX1+LqxLX5+iCOND07+MS5gzD7c2IF+hTkOIk2CtDGV5rXBQWr5pqD5TecuYAPfuB5U6NtQ1Xzd0byiWqMP2zkTW3+KgEvxVHwzjYp24/4gCci5RnzTCINCT6OnZy3vWZLXEatyoys2iiZNTsEicV2J74na+1ChqPrFOErf5FvvHU6fVOsi/VpxQ2hq+crvwYrnM+mgpVl1Xai8ngwgAcruU9oK52z8hJSaRQ1zQNDFasepNRuSAFJzmddjF6w+6j3P04/i+ybTf/vIRuDH9tqujoYW2/LR6aaG+9GEfs1+g0Ld031nE6IbT9pM0HhIX4QfJhdby0G9fvGfvdXAQtWuK5AMHlrAp+G/ktGaGcoX3LyK9LeRp/JttSGCqB54XrVys4Uf6QRm1MB3o1czz8oqFVTxkqYjHocqRuCKIoxS/q13RpYWO1M9XJCKZ3iO+siYtJseAdUdqCjgJ1uD1UPBuZLHTrkPk+GSxFxjsYzh3Za3pAr/V4uArA4oujO1RP7v7a34cNQnhzWHjyvSnrvpYEyEfxg4nZtQMdTh6LY5NzI2QT0iCWgclRm47wlMYNUoSe4mDXPGgYgTntyqm+CHkTQxJjsD6Bb1B5xbns0/mRGegB2XofPjtShsqnsMLofhqVs8jFflYSKu7TpOeWZT55ItW6veTxpZNXtZbk8KAtsaT11p/6iNZ7vj9ptgFWkdFTgZt9EkHh+f68wd7CekBYK2fr5aw8iyxMY0iRdhoFOujnhAO+kfaCqi8i6k9+Yj8RreRvBvSv3V7vuUDZYzCofeucfR/qZAF9jEU8xaYrxj2HFOxFC+oTHJnak2W/rPL/TguTwtivthir/osRV2tvONPEIBOGAKKnoEM7aA3bNCpfeMsa2tyUZYmNWbIIWyKUGWKiRmC7dBLU+WTAHCXqyieWfusaQ+7Aoy5XQKOvYznR8SG6APv0jeoFG8S8NqU1Dlg1sDG5cRMcSdQbbP7ihbZS1BZhD6Z6W/NsBHdFsQ8GFI/4oZDkYEka201uc2zrp1HNMe3veH18t8H0EqLFkaiWa+gTWj1T7+xmE5XMNLhWJyf9+i8ncqPop6ND+mSILdXrkqsQhgLmY2cPxdIBvnzbfICk7e9ZQEe4FXRfQ3Du4eaSTqkj0jaCMbTPgc9WrqSoO7otu5N4UT46s59hJOJNDjs4TE/DaXui4/a4orO82UnEmP1+XyUsaGYW1pSPbFM0FrOo5hQoBRhJeSRFbwWV5v6L+sJDeykh9Lbz3qeaFcyBxuI6TSSW5oTGFKsBh1NaeXRkEFlWwEBwQMYALPwLYExRnt26IGhnhMBE8I+wbvqbv4aoOsSuyo240vi/Kfrjp9aGn2us0fw63cujZhZtAMYHRMBMGCSqGSIb3DQEJFTEGBAQBAAAAMFsGCSqGSIb3DQEJFDFOHkwAewAxADIARQBGAEQAOAA4ADUALQA3AEUARgA3AC0ANAA4ADEANwAtAEIAOQAzADQALQBBAEEARAAyAEUARgBBADAAQQBCADkARAB9MF0GCSsGAQQBgjcRATFQHk4ATQBpAGMAcgBvAHMAbwBmAHQAIABTAG8AZgB0AHcAYQByAGUAIABLAGUAeQAgAFMAdABvAHIAYQBnAGUAIABQAHIAbwB2AGkAZABlAHIwggPvBgkqhkiG9w0BBwagggPgMIID3AIBADCCA9UGCSqGSIb3DQEHATAcBgoqhkiG9w0BDAEGMA4ECIP11AEEFXKrAgIH0ICCA6jZ7y2kaiXQkwoOvHiwTZ1fdt91K9N3g9NgY0VY1ww5g8qMYGSkVWgq7+eWu373+no6Qgwh7xEWi/+FLDXc4FWX7TEJCPlnaZjYrdpAXjJdug3Jxxxhq0Tl9koZ/os6feOqy/zVyG2s9fPByC56n9mFQp0v/OA47bdl5of530zVX7ClejQdwENpCetLV400Pr123bG/TV9rxK4WGIE5V9OA3QBnQftkCjy7/J2BY2eaBvfV2+PMyUK8est/DGaM4WnuPIokMt6kIX6/zoZ6zDLBMYwC1ptI1JbR2J64E6NGElq1rZ/4phSTWz18njt6fuYJs6BckQt5/H/7N+L20gxYUEUyIjkhHpiBsEebIx5Q8FYt1s3gYxgCOn0JSR4AKMNTF9JFdbXJVVpukIy8HIBjoJSReF+D+GYdOlwexSnnajUCX7SIZiryGXSOfeHVffr/8UIfPOD3kdabhG3GkAHVdZmBbDMzTSa7u/g42YZncp85dUA4byOVbcGT6OOdzm+wlJnLgXnsmprXsnFhjk2gD0F7QzYFdRXU5mUgBuhzCnIQBKnR5eyS2LKLun//m1grhHkZAJ7wlm9bF2KxsmalQUu6j3dWa7aj4w7OJ+1eHZNSjfjsAS2IzglHpmpELdL0F9Hp8VYOvat9SkaybyDRDKudl84lUD1QxQvTluE/cDzcNN9f2/cpqrXKn28lGljalG6WhiOjrFH2mlbkblx2WYpvodGYGCnfGILtD+KJQbfs/oKSXj8VexH88MJrs9FJwFd0vLoiYmMAeVYzH/AgSiyXBEoTceUwU/nH8j0janXWzM3MKGso+hdYapcBqemywqpUvWQ49xc59LbEUB4Actr1iw7PHWkxelPjZMqVxRHy25R8uiCc++NTtUeHsDDSRj481a0+VoCy9L14S/qPBedvKX6Rl5FaLvLiPYp48IHFiW0XHDxQCiVKaXIRfR55GjzpuHFp/ofbFwB+nfybcmQq59zZihWezn5znu2ZrMLUqZygkhOdpA8eJeqEROormuwoNNeYWzATFIkrp8KZe+u+2iRNsa6ixLU/q4+R4X83iTcCHbganCl1S9jhTIT7NHZ++TD9pbwgHedSY2y+YxuTAZmFbQCKa8FvIQvRZ6jl7IFeuUkXgxAdtZk7Uirgsr7cN1PlEW5wyrIM3H/35XPVFcdR/ckpkExRlX3KPzQWNjbMy+ygkpGjZXDGwIAAm1iriBJ1NQMbS+b3V9Ag/jcMMDiExiMwNzAfMAcGBSsOAwIaBBTCmV5zt/CoSMkXdfeDuUPQ1HZ7BwQUCQKAaL+Em/bYMSpVzwFHw6REQLk=">
    <Subscription
      Id="d11fff51-e7c1-49ef-b833-f9204c337943"
      Name="My Awesome Subscription" />
  </PublishProfile>
</PublishData>

What it does is that it eases your deployment process through Visual Studio or other tools which support it. To explain this, consider how things were done prior to the introduction of this functionality. One would need to go through the following steps:

  1. Create a self-signed certificate either using IIS or makecert utility.
  2. Import that certificate into your local certificate store.
  3. Export that certificate into .cer file format and upload that certificate into Windows Azure Portal.
  4. Now use that certificate in Visual Studio or any other tool which consumes Windows Azure Service Management API. You would need to specify your subscription id (meaning another trip to portal) for each subscription you would want to use.

With publish profile file, one would go through the following steps:

  1. Visit the link (see below – How To Get It) and download the file. You may need to sign using your Live Id.
  2. Use this file in the tools which support it like Visual Studio or Cerebrata’s Azure Management Tools.
  3. All your subscriptions will be imported successfully.

How To Get It?

To get it, please visit the following link: https://windows.azure.com/download/publishprofile.aspx

You may need to sign in with your Live Id. If the process is successful, you will be asked to save a file with “publishsettings” extension. You can open it in notepad or any text editor to see it’s contents.

How It Works?

So when you request a publish settings file from the link above, what Windows Azure does is that it creates a new management certificate and attaches that certificate to all of your subscriptions. The publish settings file contains raw data of that certificate and all your subscriptions. Any tool which supports this functionality would simply parse this XML file, reads the certificate data and installs that certificate in your local certificate store (usually Current User/Personal (or My)). Since Windows Azure Service Management API makes use of certificate based authentication and same certificate is present in both Windows Azure Management Certificates Section for your subscription and in your local computer’s certificate store, authentication works like a charm. 

Some Comments

Here are some comments about using this file:

  • Undoubtedly, this is a great way to get all your subscriptions into the tools which consumes Windows Azure Service Management API.
  • Since this a text file containing not only your subscriptions but also the management certificate required to manage those subscriptions, extreme care must be taken to protect this file. Anybody who has access to this file has complete access to your subscriptions. If you think that this file is compromised, you must delete the certificate from the management certificates section in Windows Azure Portal to prevent any misuse.
  • Currently there’s a limit of 10 management certificates per subscription. As mentioned above the process for creating a publish settings file always create a new certificate and associate with all subscriptions associated with your Live Id. If you try and generate publish settings file more than that, you will get an error.
  • Currently the process of creating a publish profile file does not allow you to choose for which subscription you wish to generate this file. It automatically creates this file and puts all of your subscriptions in that file. This might pose some problem in certain scenarios:

    For example consider the scenario where you’re a consultant working for different clients and are administrator/co-administrator on subscriptions for those clients. When you generate this file, it will not only try and create management certificates in each of your client’s subscriptions but also include all those subscription ids in this file. This would make it difficult for you to share this file with your colleagues at one client location.

    In yet another scenario, consider you’re an administrator for your company’s Windows Azure subscriptions and you would want to use this file however you want to restrict access to those subscriptions. For example, you may have a subscription just for your QA environments and another one just for your production environments. Using this functionality when you generate the file, you can’t really specify that you wish to generate only for your QA environment subscription.

We’ll try and address those issues in the next section where we create a publish setting file for a  subscription using an existing management certificate.

Creating Your Own Publish Settings File

We all realize that publish settings file eases the friction of managing your subscriptions considerably. Indeed it has its shortcomings but the ease factor clearly outweighs the shortcomings.

I was actually helping somebody out on MSDN forums where the person posted about these shortcomings. You can read that thread here: http://social.msdn.microsoft.com/Forums/en-US/windowsazuretroubleshooting/thread/5054447c-b04a-4a69-bf89-d17c441b1c73/. This gave me an idea about building a small utility which you can use to create your own publish settings file. In this section I’m going to describe that.

The Code

I built a simple console application which creates this publish setting file. The source code for the application is listed below. Feel free to use the code as is or modify it to suit your need.


using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml;
using System.Security.Cryptography.X509Certificates;
using System.IO;

namespace CreatePublishSettingsFile
{
    class Program
    {
        private static string subscriptionId = "[your subscription id]";
        private static string subscriptionName = "My Awesome Subscription";
        private static string certificateThumbprint = "[certificate thumbprint. the certificate must have private key]";
        private static StoreLocation certificateStoreLocation = StoreLocation.CurrentUser;
        private static StoreName certificateStoreName = StoreName.My;
        private static string publishFileFormat = @"<?xml version=""1.0"" encoding=""utf-8""?>
<PublishData>
  <PublishProfile
    PublishMethod=""AzureServiceManagementAPI""
    Url=""https://management.core.windows.net/""
    ManagementCertificate=""{0}"">
    <Subscription
      Id=""{1}""
      Name=""{2}"" />
  </PublishProfile>
</PublishData>";

        static void Main(string[] args)
        {
            X509Store certificateStore = new X509Store(certificateStoreName, certificateStoreLocation);
            certificateStore.Open(OpenFlags.ReadOnly);
            X509Certificate2Collection certificates = certificateStore.Certificates;
            var matchingCertificates = certificates.Find(X509FindType.FindByThumbprint, certificateThumbprint, false);
            if (matchingCertificates.Count == 0)
            {
                Console.WriteLine("No matching certificate found. Please ensure that proper values are specified for Certificate Store Name, Location and Thumbprint");
            }
            else
            {
                var certificate = matchingCertificates[0];
                var certificateData = Convert.ToBase64String(certificate.Export(X509ContentType.Pkcs12, string.Empty));
                if (string.IsNullOrWhiteSpace(subscriptionName))
                {
                    subscriptionName = subscriptionId;
                }
                string publishSettingsFileData = string.Format(publishFileFormat, certificateData, subscriptionId, subscriptionName);
                string fileName = Path.GetTempPath() + subscriptionId + ".publishsettings";
                File.WriteAllBytes(fileName, Encoding.UTF8.GetBytes(publishSettingsFileData));
                Console.WriteLine("Publish settings file written successfully at: " + fileName);
            }
            Console.WriteLine("Press any key to terminate the program.");
            Console.ReadLine();
        }
    }
}

How It Works?

Basically what this application does is reads the data for a certificate (you specify the thumbprint and certificate location), converts it into Base64 format string and writes that data in an XML file along with the subscription id. Pretty straight forward!!

Once you have created this file, you can share it with your team members and they can use it with Visual Studio or other tools to manage their subscriptions.

Some Considerations

There’re a few things you would need to keep in mind:

  • The certificate you’re using must have private key associated with it. To check if the certificate you’re using has the private key, just look at the icon besides that certificate. It should show a little “key” in that as shown in picture below. Even though the sample application above would work perfectly fine and it will create the file however when you’re trying to authenticate using that certificate, you will get a 403 error.
    image
  • The certificate which gets placed in this file is Pkcs12 (Pfx) format with password as empty string. This is similar to the way certificate placed in the publish settings file generated by Windows Azure.

How Would I Go about Using It?

If I were you, I would make use of this utility this way:

  1. Create a new certificate either by using IIS or makecert utility.
  2. Install that certificate into my certificate store.
  3. Export that certificate from certificate store in cer file format and upload it in Windows Azure portal and associate it with my subscriptions.
  4. Then I would run this utility to create new publish settings file and distribute it (and test it of course before distributing it).

Summary

In this post we learnt (hopefully) about publish settings file and despite it’s shortcomings it’s very useful. We also saw how we can create our own publish settings file.

I hope you’ve found this information useful. As always, if you notice anything incorrect please let me know ASAP and I will fix it.

Oh, Just Wait!!!

I just realized that this is my first post with no smileys in it Smile. Dang, there it is!!

Enjoy Smile. So long and stay tuned!!!


[This is the latest product I'm working on]

Comments

  1. Short and sweet. This will be useful, thanks Gaurav!

  2. Creating my own settings file was just what I was looking for, as the default behaviour is just painful. Thanks.

  3. Has anyone else encountered the following error when trying to deploy to Azure using Powershell “Cannot find Subscription with name ” ?

    I have confirmed that the Subscription ID in the file does in fact match the Subscription id for my Azure subscription. It finds the actual subscription name easily enough but for some reason the ID fails.

Trackbacks

  1. [...] is easy enough to create a management certificate. Gaurav Mantri’s blog post really helped on this. makecert -sky exchange -r -n "CN=JustAProgrammer" -pe -a sha1 -len [...]

  2. [...] the following at the command line to download your publishsettings [...]

  3. [...] To dig a little deeper I managed to find a good article that talks about the limitations of the subscription file when managing multiple subscriptions, and how you can create a custom .PublishSettings file: http://gauravmantri.com/2012/09/14/about-windows-azure-publish-settings-file-and-how-to-create-your-… [...]

  4. Consuming Service Management API from Web/Worker Role – Method 2…

    In my previous post about the same topic I mentioned there are multiple ways to enable your Web/Worker…

  5. Consuming Service Management API from Web/Worker Role – Method 2…

    You can find this blog, and lot of other interesting articles about Azure on My Team Blog In my previous…

  6. [...] Management Certificate: A management certificate is required to authenticate your API calls. This management certificate must be associated with your subscription which you can do by upload the certificate in the portal. You could either create a management certificate on your own and associate it with your subscription (this is covered in details in this post) or you could ask Windows Azure platform to create a management certificate for you and associate it with your subscription. This is done through a process called “Download Publish Profile File”. I have written a blog post about it some days back which you can read here: http://gauravmantri.com/2012/09/14/about-windows-azure-publish-settings-file-and-how-to-create-your-…. [...]

  7. […] To dig a little deeper I managed to find a good article that talks about the limitations of the subscription file when managing multiple subscriptions, and how you can create a custom .PublishSettings file: http://gauravmantri.com/2012/09/14/about-windows-azure-publish-settings-file-and-how-to-create-your-&#8230; […]

  8. […] To make some parts of this easier – especially if you are distributing to a team – consider building your own publish settings file. Also, realize the same certificate can be used by more than one client, and the can also be […]

  9. 0 to Azure VM with PowerShell

    I got a new laptop from MS, a thin and light model, great machine my thinking was can I function as a

Speak Your Mind

*