Menu Close

Step by step: Manually Create an Azure DevOps Service Connection to Azure

One of the benefits of the Azure DevOps pipeline is it’s direct connection to Azure.
If your Azure subscription is in the same tenant as your Azure DevOps account, you can create an Azure DevOps Service connection to Azure easily, as long as your account has the correct permissions. You just sign in at the service connection page and you’re done. What actually happens is that Azure creates a service principal for you to take care of the connection.

You have the option to manually create a Service Connection to Azure as well. In this post I will show you how.

But why?

There are a few use cases for manually creating a service connection:

  • You want to manage the permissions for the service connection.
    This is something you should consider, as the service connection is available for everyone in the project with permissions to run pipelines, without extra verification. This means that if you have a service connection that has contributor rights to the subscription, you give those users in the project the same access!
  • You want to deploy resources to a different Azure tenant.
    Azure DevOps is connected to an Azure AD Tenant. You will be able to create a connection to every subscription you can access based on your account in that tenant. If you want to access a subscription outside of that scope, you will need to create the connection manually.

For this example, I want to use my personal Azure DevOps account to deploy some tests for my module ARMHelper to my Azure subscription. These two are linked to different Azure tenants, so the connection needs to be created manually. Let’s start with the Azure DevOps Service connection.

Create the service principal

First, we need a service principal in the Azure tentant that we want to connect to Azure DevOps.
There are a few ways to make this happen.

For this example, I use the CloudShell to create the principal and then the portal for all settings, as I find this the easiest way to complete the process.

Open the Azure Portal and click on the Cloud shell logo on the top right.

Azure DevOps Service connection

Note: Want to know more about working with the Cloud Shell? Click here.

Use the following code:

New-AzADServicePrincipal -DisplayName AzDo-Connection

Now close the shell en move on to Azure Active Directory in the portal. Click App registrations. Here you will find your new service principal.

Create a secret for the Service pricipal

We need a secret to create the connection with Azure DevOps. Open de service principal and select Certificates and secrets in the menu.

As you can see there is a secret without a description there. This was created with the Service Principal and it was possible to use it at that point, but I find the process a bit complicated compared to just creating a new one. You can remove it now, as you don’t know the secret and the portal will never tell you.

When you select New Client Secret, you get to give it a description of your choice and set expiration. What expiration you want depends on your security needs. It can be more secure to let the secret expire, but this might be an issue when it expires and production stops.

I made the choice to use never expires as this account will not get a lot of permissions.

After you click add, the secret will show in the portal. This is your only chance to copy it’s value. Copy it and store it somewhere safe.

Note: You might make the decision to store it only temporary, as you should not need the secret anymore once the connection is set up. But this does mean that if there are issues in one way or another, troubleshooting might take a bit more time.

Set permissions

The service principal needs permissions to work. It needs Reader rights on the subscription level. After that, you can provide it with the RBAC role of your choice as you would an administrator. Do be careful as like I said before, everyone with access to this connection basically gets the same permissions.

In this case, I have provided this connection with the Reader role on the subscription and Contributor on a specific Resource group.

Creating the connection in Azure DevOps

Open your Azure DevOps organization in a different tab (if this is a different organization, you might need to do this in a private tab).
Open the project that gets the connection and click Project settings at the bottom left. In the menu that pops up, click Service Connections.

Azure DevOps Service connection

If you have set up a connection with Github for your pipelines, you will find it here as well. Click New service connection in the top corner.

After that, click Azure Resource Manager.

You can now select if you want to use an automated authentication of a manual one.

The first option is the best way if your tenant is connected to your account, as discussed before.  As we wanted to do it manually, click Service Principal (Manual)

We now get a few fields to fill in. Enter the connection name and paste the Secret in the field Service principal key. For the other fields, I’ve put together this little PowerShell Snippet. Paste it in the cloud shell to get all the values you need. Change the Service Principal Name to the name you chose when you created it and change the subscription name to the name of your subscription

Note: Not sure what your subscription Name is? Use Get-AzSubscription to get all subscriptions in your tenant

Put the values in the Azure DevOps field and click “verify connection” to make sure it worked.
Note: The menu looks slightly different now, but the field are still the same.

Azure DevOps Service connection

Click OK and now you have a connection you can use in pipelines, for example for Azure PowerShell or ARM deployments. It works exactly as a connection created by the portal.

Azure DevOps Service connection

Don’t forget to think of a way to document the permissions of the account. The good news is that the pipeline will tell you if it fails because of a permission issue.

So this is how you manually create an Azure DevOps Service connection to Azure. If you have any questions, let me know in the comments


  1. Matt Lyke

    if I want to have service connections across multiple projects to the same azure resource. do you create one in azure and create new service connections in each project?

    • Barbara

      You do need to create a new service connection for each project on the Azure DevOps side.
      It is possible to use the same service principal on Azures side for multiple projects. You can however only define the permissions for Azure once.
      So if different projects require different permissions, you could use the same service principal without issues.

  2. Jason

    If I have my Subscriptions in a Management Group do I replace the $AzSubscriptionName value with the name of my Management Group?

    • Barbara

      As you can tell by the screenshots, this post was written before creating a connection on a management group level was possible. If you want to use a management group scope, You can run Get-AzManagementGroup | Select-Object Name, Id in the cloud shell to get an overview of your management groups. Copy the Name and ID for the one you need and paste it in the right fields in the form.

  3. Hema

    Hi, I’m getting the error “Could not create Endpoint Administrators group. If group already exists within the project, please delete it and retry the operation.” when creating a service connection. This happens only when I’m trying with a particular Azure Devops organization. What might be the issue? Thanks.

  4. Brett McDonald

    First of all this is a great post. But, when you get to the end. What do you enter for Credential – select Service principle key – Service principle key?

    I can’t figure out what to enter here?

    • Barbara

      Hi Brett,
      For the credential you indeed select service principal key. The value that you enter is the secret you created under the chapter Create a secret for the Service pricipal. You can copy and paste it from the portal when you create the secret

  5. Pingback:Azure Devops Connexion - 2gna - Connexion

  6. Pingback:Azure Devops Connexion - Connexion

Leave a Reply

Your email address will not be published. Required fields are marked *