In the first Gaffer Guide installment logging into the Azure CLI using an Organizational Account was covered. As mentioned in that document, another way to log into the Azure CLI is through the use of what is known as a service principal.

What is a Service Principal? A Service Principal is an instance of an application that is within your Active Directory that is allowed access to one or more resources.

Before diving more into Service Principals, notice something mentioned in that above statement, a Service Principal is tied to an application. It is possible to add Applications do an Active Directory, often for purposes of integrating the application service with the AD. An MSDN discussion of integrated apps can be found here. Typically a number of these applications are integrated for purposes of single sign on, but when we talk about a Service Principal, this is going a step farther and allowing the application access to resources controlled by the Active Directory itself.

For purposes of this discussion about the Azure CLI and Azure Resource Manager, the basic traits of an Service Principal are:

  • An application is created within the Active Directory
    • The application will be associated with the user that creates it
  • A service principal is then created for that application
  • That service principal is granted access to the subscription.
    • It is possible to give finer grained access, but that is outside the scope of this document.

The Azure team has documentation on walking through the creation of a Service Principal using both PowerShell and the Azure CLI here and David Ebbo walks through the usage of the portal and PowerShell to set up a Service Principal for use in Automating Azure on your CI server. One other Azure page that mentions how to create a Service Principal, but is not complete due to the need to associate the Service Principal with a subscription and assigning roles is here.

Creating the Service Principal

The steps for creating a Service Principal are:

  • Create an Application
  • Create a Service Principal for that Application
  • Grant access and permissions to your subscription to the Service Principal

First you need to log in. If you followed the prior installment you are already logged in. If not, you should log in. The process should resemble below:

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

In order to create the Service Principal, an Application must first be created within the Active Directory. To do so using the CLI, you will need to come up with three “properties”, an Application Name, Application Home Page, and Application URI, and a passowrd*. Note, that these values actually mean something in the context of when you integrating an application into Active Directory. However, for purposes of creating a Service Principal to manage your subscription, you can use whatever values make sense for you. The URIs need to be valid in “format” but not real URIs.

So, for purposes of this example, the following values will be used:

To create the Application, you use the azure ad app create command. Note, you must be in ARM mode for the Azure CLI for the azure ad commands to be available. Using the above to create the app:

jims@spielen:~$ azure ad app create --name "climanager" --home-page "http://localhost/climanager" --identifier-uris "http://localhost/climanager" --password "spielpassword"
info:    Executing command ad app create
+ Creating application climanager
data:    Application Id:          1b283f2a-6e7f-4d64-9cc5-d08986fbd2c9
data:    Application Object Id:   ac2dd0aa-e6a1-4983-bf06-00931b9140d2
data:    Application Permissions:
data:                             claimValue:  user_impersonation
data:                             description:  Allow the application to access climanager on behalf of the signed-in user.
data:                             directAccessGrantTypes:
data:                             displayName:  Access climanager
data:                             impersonationAccessGrantTypes:  impersonated=User, impersonator=Application
data:                             isDisabled:
data:                             origin:  Application
data:                             permissionId:  ddbf02bf-497f-464f-a567-c2d7409c20bf
data:                             resourceScopeType:  Personal
data:                             userConsentDescription:  Allow the application to access climanager on your behalf.
data:                             userConsentDisplayName:  Access climanager
data:                             lang:
info:    ad app create command OK

In order to now create a Service Principal for the Application, you need the Application Id which in this case is the value 1b283f2a-6e7f-4d64-9cc5-d08986fbd2c9.

To create the Service Principal, you use the azure ad sp create command. Do so as follows:

jims@spielen:~$ azure ad sp create 1b283f2a-6e7f-4d64-9cc5-d08986fbd2c9
info:    Executing command ad sp create
+ Creating service principal for application 1b283f2a-6e7f-4d64-9cc5-d08986fbd2c9
data:    Object Id:               905b816f-0789-4627-889d-2da2a5892555
data:    Display Name:            climanager
data:    Service Principal Names:
data:                             1b283f2a-6e7f-4d64-9cc5-d08986fbd2c9
data:                             http://localhost/climanager
info:    ad sp create command OK

To grant permissions to the newly created Service Principal we need to use it’s Object Id listed above and the Subscription Id that privileges will be granted to. To find out the Subscription Id, use the command azure account list. We will also record one other piece of information from this command, the Tenant Id.

jims@spielen:~$ azure account list
info:    Executing command account list
data:    Name        Id                                    Tenant Id                             Current
data:    ----------  ------------------------------------  ------------------------------------  -------
data:    Free Trial  c11e8e07-7c04-41b6-96bc-9d8fc3c5fe2a  b368fad9-3955-72a3-8f16-340743cefdd7  true
info:    account list command OK

The Subscription Id is c11e8e07-7c04-41b6-96bc-9d8fc3c5fe2a and the Tenant Id is b368fad9-3955-72a3-8f16-340743cefdd7.

Azure has a number of predefined rules. For the Service Principal to make changes to the subscription, we will use the Contributor role. A number of built in roles are outlined here.

To give the Service Principal permission, use the command azure role assignment create as follows:

jims@spielen:~$ azure role assignment create --objectId 905b816f-0789-4627-889d-2da2a5892555 -o Contributor -c /subscriptions/c11e8e07-7c04-41b6-96bc-9d8fc3c5fe2a/
info:    Executing command role assignment create
+ Getting role definition id
+ Creating role assignment
info:    role assignment create command OK

Testing the Service Principal

At this point, the Service Principal is created and permissions granted. You can now try logging in with that Service Principal. To do so, we need to log out of the Azure Cli and log back in with the Service Principal. We need the following information mentioned previously:

  • Application Id: 1b283f2a-6e7f-4d64-9cc5-d08986fbd2c9
  • Password: spielpassword
  • Tenant Id: b368fad9-3955-72a3-8f16-340743cefdd7

The process will resemble:

jims@spielen:~$ azure logout
info:    Executing command logout
info:    You have logged out.
info:    logout command OK
jims@spielen:~$ azure login -u "1b283f2a-6e7f-4d64-9cc5-d08986fbd2c9" -p "spielpassword" --service-principal --tenant "b368fad9-3955-72a3-8f16-340743cefdd7"
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
info:    Added subscription Free Trial
info:    Setting subscription "Free Trial" as default
info:    login command OK

Now you can use the Service Principal to manage the Azure subscription.

Some Notes

As you will see in a number of the Azure documents that discuss Azure Resource Manager, the old portal and the new portal, there are some disconnects because of the old APIs and the new ones. The above commands use the new APIs and as such, the Application created and the Service Principal are not reflected in the old portal. And, as of today (August 8, 2015), the Azure Directory functionality is not yet surfaced in the new portal. This will change over time, but it is important to be aware of this particular issue.

As resources documenting the management of Active Directory from the Azure CLI are exposed, this entry will be updated.

One thing to note when we granted access to the Service Principal, we gave it Contributor privileges to the subscription as a whole. The new Azure Resource Manager APIs are built with the premise of allowing finer grained access control. It might be worth reading up on Role Based Access Control. One area to start is here.