Onboarding to Azure Lighthouse using a template
Published Jan 28 2020 02:00 AM 9,579 Views

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 Resource Manager 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 Resource Manager 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 best practice 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 Active Directory. 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 '<yourGroupName>').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 '<roleName>').id



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


Azure Resource Manager 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). 


To onboard this Use this Azure Resource Manager template And modify this parameter file
Subscription delegatedResourceManagement.jsondelegated ResourceManagement.parameters.json

Resource group
rgDelegatedResourceManagement.json rgDelegatedResourceManagement.parameters.json
Multiple resource groups within a subscription multipleRgDelegatedResourceManagement.json multipleRgDelegatedResourceManagement.parameters.json


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-Management\templates\delegated-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 Active Directory/ 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 <deploymentName> `
                 -Location <AzureRegion> `
                 -TemplateFile <pathToTemplateFile> `
                 -TemplateParameterFile <pathToParameterFile> `



Substituting the <deploymentName> with anything, the <AzureRegion> with the location of the customer's subscription, and the correct file paths (e.g. "C:\Scripts\delegatedResourceManagement.json" and  "C:\Scripts\delegatedResourceManagement.parameters.json"


If you do have the files in Cloud storage (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.


Version history
Last update:
‎Jan 29 2020 04:05 PM
Updated by: