Onboarding to Azure Lighthouse using a template

Azure Lighthouse enables you to see and manage Azure resources from different tenancies, in the one place, with the power of delegated administration. That tenancy may be a customer (for example, if you're a managed services provider with a support contract arrangement in place), or a separate Azure environment for legal or financial reasons (like franchisee groups or Enterprises with large brand groups). 

To get started, you need to on-board the customer's tenancy so that users in your own tenancy (referred to as the service provider) have access to the customer's resources. This is know as delegated administration and can be done via deploying an Azure template, or by publishing a private or public offer to the Azure Marketplace, for your customer to accept. With either method, the customer can see who they've granted delegated administration rights too, your actions on their  resources and logged, and the customer can revoke this access at any time.

So let's take a look at the Azure template on-boarding, in detail.

What exactly is delegated administration?

Delegated administration is similar to role based access control, except you're granting access to people or service principles in a different Azure tenancy. This access can be applied at a subscription level, at a resource group level, or for multiple resource groups inside a subscription. The access level itself is defined by which built-in role definition you choose. This granular level of access allows you to adhere to the security of granting the least amount of access rights need to perform the tasks that are required. For example, if you're only contracted to manage backups, the Backup Operator role would be sufficient. 

Your first take is to determine what kind of work you'll be doing in the customer's tenancy, what access is needed and at which scope level, and who in your organization needs this access. It's recommend that you use existing user groups (or establish new ones), grant the access to the group name, then manage the membership of the group. This removes the need to re-run the delegated administration process if you have staff changes, and actions are always logged under the individual user or service principle ID. Click here for more information on supported roles with Azure Lighthouse.

Step 1: Collect the following

Your tenant ID (the service provider) – This is shown in two places, in the Azure portal, under Azure . On the Overview page, it's listed as Tenant ID and on the Properties blade, it's listed as the Directory ID. Note: For most Azure environments, you tenancy will only have one directory and these values will be identical in both places. 


Principal ID and Principal ID Display Name of the group you want to give the access to –  For example, I've created a group in my service provider tenancy called “Customer Admins”, and I'll add my support staff to that group. I want those people to have access to manager my customer's resources. So I need to have both the ID and the Display Name of that group. In the Azure Portal, fire up Cloud Shell and use the command:

(Get-AzADGroup -DisplayName '').id

For my example, I'd enter (Get-AzADGroup -DisplayName ‘Customer Admins').id and get a Principal ID that looks like cef0a784-fOtherLettersAndNumbers

The Display Name is just the name of the group, with the correct case.

ID of the Role Definition – As I started off by reviewing the built-in roles and selecting which one met my access needs, I've decided to give my Customer Admins the “Contributor” role to the customer's tenancy, but I need the ID of that role definition.  This time in the Azure Portal, I'll fire up Cloud Shell and use the command:

(Get-AzRoleDefinition -Name '').id

Replacing ‘' with ‘Contributor' and getting back an ID of b24988ac-6180-42a0-ab88-20f7382dd24c 

Azure Template and parameters file – You'll need to download two .json files: the Azure Resource Manager template and it's associated parameters file. See this table for a quick links, depending on what level you are setting the access at (subscription, resource group, or multiple resource groups). 

Note: the official page for this table is Onboard a customer to Azure delegate resource management, so check there for any updates. The files are stored in GitHub at https://github.com/Azure/Azure-Lighthouse-samples 

A note for GitHub newbies

  • If you click on a link in the table to the direct files, browse up a level to the Azure-Lighthouse-Samples (https://github.com/Azure/Azure-Lighthouse-samples) then hit Clone or Download. Then you can choose Download ZIP.
  • Once you've expanded the downloaded zip file, if you want to apply the access at a Subscription level, browse to the Azure-Delegated-Resource-Managementtemplatesdelegated-resource-management folder. In the next step, you'll edit the delegatedResourceManagement.parameters.json file (or whichever parameters file is relevant, according to your needs and the above table).

 Step 2: Edit the Parameters file –  Here's where VS Code comes in handy, because of how nicely it keeps the formatting and displays the code. If you don't have it installed, download it here.

In the appropriate parameters file, you need to edit it to show your own:

mspOfferName – e.g. My MSP Name – Gold Support

mspOfferDescription – Whatever you like, can be the same as your offer name

managedByTenantID – Your service provided tenant ID, found in step 1.

Authorizations (principalId, principalIDDisplayName, roleDefinitionID) – The group ID, display name, and role definition ID you decided on and determined the values of, in Step 1.

Your parameters file should then look a little like this (for Subscription level access):

    "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentParameters.json#",
    "contentVersion": "",
    "parameters": {
        "mspOfferName": {
            "value": "My Admin Company - Gold Support Contract"
        "mspOfferDescription": {
            "value": "My Admin Company - Gold Support Contract"
        "managedByTenantId": {
            "value": "9f12345b-11dd-321e-123e-123456789123"
        "authorizations": {
            "value": [
                    "principalId": "cef0a784-abc1-1234-a9bf-123456789123",
                    "principalIdDisplayName": "Customer Admins",
                    "roleDefinitionId": "b24988ac-6180-42a0-ab88-20f7382dd24c"

Great work so far! Now we have everything we need to onboard the customer … except actual access to the customer's tenancy to do the deployment of this template, to grant us access!

Step 3 : Deploy the Azure Resource Manager template, including the parameters file

If you are already doing work for this customer, you may have a separate admin login to their tenancy already. Or you may have to send these two files to your customer to get them to deploy them.

The deployment must be done by an account that already has the built-in Owner role for the subscription being onboarded. And for a subscription-level deployment, this cannot be done in Cloud Shell in the Azure Portal. It must be done using Azure PowerShell (installed) or the Azure CLI.

But wait  …….

Before we go deploying this, it's likely that the customer's tenancy is configured by default with helpful names like “Default Directory” and “Free Trial” names for the Directory and the Subscription. With permission, you may want to rename these to Customername Directory and CustomerName subscription (in the Azure / Properties and the Subscription/Overview), before you deploy this template. This will make it a little easier to differentiate between more than one customer, when you see them listed in your Azure portal. 

So with Azure PowerShell running, log into the customer subscription using the Connect-AzAccount command and then to deploy a local copy of the template and parameters file, run

New-AzDeployment -Name  `
                 -Location  `
                 -TemplateFile  `
                 -TemplateParameterFile  `

Substituting the with anything, the with the location of the customer's subscription, and the correct file paths (e.g. “C:ScriptsdelegatedResourceManagement.json” and  “C:ScriptsdelegatedResourceManagement.parameters.json

If you do have the files in Cloud (like your own Github account), you can replace TemplateFile with TemplateUri and TemplateParameterFile with TemplateParameterUri and the URL to those files.


After a little time has passed, you should see the customer's tenancy in the My Customers blade of the Azure Portal (search for My Customers if that blade doesn't appear by default), and you should see your customer's resources appearing in the appropriate places, like the All Resources pane – as long as the filtering also includes their subscription!

What's next?

Now you can manage those resources from the one Azure Portal, with your one set of login credentials. See what services are currently supported: Cross tenant management experience.

Here's an example of using this delegated administration access to manage security, including non-Azure resources via Azure Arc.

Learn more about Azure Lighthouse with the official documentation at docs.microsoft.com.


This article was originally published by Microsoft's Azure Blog. You can find the original article here.