As you may be aware, Microsoft has this cloud platform known as Azure. It’s actually grown quite a bit since it’s first inception. Within the last couple of months, Microsoft has announced Azure Resource Manager which is on one hand a set of tools for letting you manage your applications in a new way, it is also in a sense the name applied to looking at the components of your applications as being in one or more groups. These groups allow you to define control, manage, deploy, update, and destroy based on these groups. Basically, if you dive into the extensive Azure documentation, Role Based Access Control has been introduced along with a new portal and other sets of tools.

Another change is that many, but not yet all, APIs have transitioned from an XML based format to REST/JSON. More and more APIs are moving over as time progresses, just as more functionality is being exposed in the new Azure Portal.

These “Gaffer’s Guide” posts are in no way to replace the existing Azure documentation, but instead is targeting documenting my own experiences with using Azure, the new functionality, and different Azure SDKs depending on the projects I am on.

Getting Started

This first post is going to walk you through a very simple scenario - You have your MSDN account tied to a Live ID, how do I use the Azure CLI?

The caveats:

  • This guide will only be focusing on the ARM mode of the Azure CLI.
    • No use of the .publishsettings file, just username and password tied to an Active Directory account.
  • This guide will link to detailed documentation, but will stay focused on the aspects relevant to the problem being addressed in the particular post.
  • There are two Azure Portals the old one and the new one. This post will only require interacting with the first, but later posts may use the new one. Not all functionality is available in the new portal yet.

Before getting started, this post assumes that you have at least installed the Azure CLI tools for your chosen platform. Instructions for installing the Azure CLI are here.

You will likely note a post titled Connect to an Azure subscription from the Azure Command Line Interface (Azure CLI). If the contents of that post is something you understand, having spent time using Azure and the Azure CLI, you probably can skip reading this post.

If you continue, please open a command or terminal windows and place the Azure CLI into ARM mode. It should resemble the following:

jims@spielen:~$ azure config mode arm
info:    New mode is arm

The Azure CLI is Installed, I Can Log Into The Azure Portal, Now What?

Try logging into the Azure CLI now that you have it installed. Use the same account that you used to log into the Azure Portal. For the sake of these examples, we will assume the following values:

So, to login to the Azure CLI, you enter the following:

jims@spielen:~$ azure login -u
info:    Executing command login
warn:    Please note that currently you can login only via Microsoft organizational account or service principal. For instructions on how to set them up, please read
Password: *********

Very likely, the result you encountered resembled the following:

+ Authenticating...
error:   Server returned error in RSTR - ErrorCode: NONE : FaultMessage: NONE
info:    Error information has been recorded to /home/jims/.azure/azure.err
error:   login command failed


What this means is, the email address you used, most likely referred to as a Live ID, did not meet the requirements of being a “Microsoft organizational account” and it certainly isn’t a “service principal” which is an Azure concept that will be covered in the next Gaffer’s Guide post.

What is an Microsoft Organizational Account?

The answer to that question is a bit involved, but the simple answer for our purposes is, a Microsoft Organizational Account is an account that exists in an Active Directory service. If you have a company or your own domain, it can be a bit involved, but for this series of posts, it basically means:

  • An Active Directory needs to be set up in your Azure account
  • A user needs to be created in that Active Directory

Creating An Active Directory, If Necessary

More likely than not, your Azure account should have an existing Active Directory. To verify this, log into the Azure Portal. Then scroll down to the “Active Directory” entry and select it. Should should see something like In order to create an Active Directory, scroll down on the left portion of the panel and select “Active Directory”. You should see something similar to:

Select active directory.

You can skip to the next section.

If you don’t see an existing directory, click on the “+ New” in the bottom left (also visible above), the select “Directory” and “Custom Create”, and fill in the form with values you choose, and click the Check to finish. The form should resemble:

Add a new Active Directory.

Upon clicking the “Check” to finish, the newly created directory is in the list.

Adding A User to Active Directory

Select your Active Directory entry from the list. Then you should see a number of options, select “USERS” at the top of the page. You should see a list of users with your account listed. At the bottom of the screen (scroll down if necessary), click on “Add User” and navigate through the forms filling in the required fields. For “Role” on the second page, choose “Service Admin” and do not enable Multi-Factor Authentication. On the final page of the form, click the “Create” button and you should be presented with a screen saying “Get temporary password”. The form should resemble the following:

Add user to Active Directory.

Make sure you record the temporary password, then click the Check and you will see the user added to the list.

Setting the New User Password

Note - due to some quirks logging in and out, the following step is probably best done in another browser or in “incognito mode” in your current browser.

In order to set a permanent password, you will need to login to a Microsoft property to change it. The easiest is here. Sign in with your new email and the temporary password. In the case of the above, the values would be:

Upon logging in, you should be presented with a form to change your password. Do so, click “Submit” and your password will be changed and you will be prompted to log back in. There is no need to log back in.

Giving the Active Directory Access to Azure Subscription

The final step in being able to use the newly created account with the Azure subscription is to give it administrator privileges to your account. This is done back in the main Azure portal by selecting Settings on the left and then the Users option as pictured below.

Add user as admin to subscription.

Click “Add”, and enter the email address of the added user in the field, select the subscription and click the Check to complete the operation. The filled out form should resemble:

Add user as admin form.

Now What?

At this point, you can try again logging into the CLI. Going back to the initial example, logging in with the new account should resemble:

jims@spielen:~$ azure login -u
info:    Executing command login
warn:    Please note that currently you can login only via Microsoft organizational account or service principal. For instructions on how to set them up, please read
Password: ***********
|info:    Added subscription Free Trial
info:    Setting subscription "Free Trial" as default
info:    login command OK

The above indicates a successful login. At this point, the subscription has what is referred to in many azure documents as “a work or school account” associated with it.

Additional Reading

The Azure team has a set of documents worth exploring. This document is a more thorough walk through of the document Connect to an Azure subscription from the Azure Command-Line Interface. Once you are comfortable logging in and using parts of the Azure the article Use the Azure CLI for Mac, Linux, and Windows with Azure Resource Manager is worth exploring.

Keep in mind, for future exploration, Azure is moving more and more towards new APIs and the “ARM mode” of the CLI, so consider sticking with those examples.