Step-By Step: How to Configure Azure Lighthouse using PowerShell

8 min readSep 8, 2021

Use PowerShell to configure Lighthouse and Manage Resources in Another Subscription

With Azure Lighthouse, rights can be delegated to managed service providers or enterprise IT organizations who need to manage resources across multiple tenants.

Tenant owners can delegate rights at the subscription or resource group level to control who has access to their resources and what actions can be taken. Once Azure Lighthouse is configured, you can centrally manage Azure services like Azure Policy, Sentinel and Arc for multiple subscriptions.

In this series, we’re setting up Azure Lighthouse as a Managed Service Provider with multiple customers to test it out. If you need to configure a test environment to manage, you can skip back to earlier posts as required:

Part 1 — Azure Subscription Signup
Part 2 — Switch from PowerShell ISE to Visual Studio Code
Part 3 — Get Started with a GitHub Repo (fork, clone, edit & push the repo)
Part 4 — Deploy Some Test Azure Resources & Azure AD Users
Part 5 — Configure Azure Lighthouse to Manage Resources in Another Subscription

To configure Azure lighthouse we’ll follow the Microsoft Doco: Onboard a customer to Azure Lighthouse

Lighthouse Deployment Pre-Requisites

To onboard a customers subscription to Azure Lighthouse, you’ll need to:

Gather some information about both tenants
Install the Microsoft.ManagedServices Provider
Select or create an admin group that will be granted access to the customer subscription
Create your own Lighthouse ARM Template and parameters file
Deploy that ARM template in the customers subscription

To make that a bit easier, I've collated those steps into a PowerShell script.

bacic_azure> Lighthouse> Deploy Lighthouse Demo.ps1

Lets, Automate those Pre-Requisites a Bit: Edit the Variables

In the Basic Azure > Lighthouse folder, open up the Deploy Lighthouse Demo script

Lighthouse Deployment Variables to be Edited

Edit the variables to suit your environment

$PathToTemplateFiles = Where the JSON files used to configure lighthouse will be saved
$CustomerSubscriptionId = the subscription ID of your “Customer” subscription. Aka, the subscription that will be managed
$SubscriptionName = The display name of the managing subscription that will eventually manage many resources from multiple customers
$AdminGroup = The name of the Azure AD admin group in the in the Managed Service Provider (MSP) or Managing tenant.
Use either an Azure AD group that already exists OR the name you’d like to use when creating a new one
$AdminGroupMember = User account you’d like to add to the group. You can leave this blank if your group is already set up and populated
$MSPOfferName =The name you want to appear in the customers lighthouse portal under Service Provider Offers. This must be unique.

Log into the Managed Service Provider subscription, install the PowerShell Modules, register the Managed Services Provider

This bit doesn’t require too much explanation, however, the authentication popup always pops UNDER in my experience so if you don’t see it, check that :)

#Log into the MSP Subscription with Connect-AzAccount since we're not using Cloud ShellImport-Module Az -Verbose
Clear-AzContext
Connect-AzAccount$AZSubscription = Get-AzSubscription -SubscriptionName $SubscriptionName#Confirm the MSP subscription is selected before continuing
Get-AzContext#Connect to the MSP Subscription Azure AD Tenant
Get-AzSubscription -SubscriptionName $SubscriptionName| Set-AzContext -Force -Verbose
Connect-AzureAD -TenantId $AzSubscription.TenantId#Register the Microsoft.ManagedServices Provider
Register-AzResourceProvider -Provider Namespace Microsoft.ManagedServices

Retrieve role definition IDs that will be assigned in the customer environment

To deploy Azure Lighthouse, you need to edit an ARM template parameters file and tell Azure:

Who gets access (principalId)
What is the display name of PrincipalId(principalIdDisplayName)
What role do they get(roleDefinitionId)

In this case, we’re going to grant the Customer1 Admins Managed Service Provider group : Reader, Contributor, Security Admin, Log Analytics Contributor and Limited User Access Administrator rights.

To retrieve and store a list of RoleDefinitionId’s for the demo, run the following section of the script.

Right click, Run Selection to get a list of RoleDefinitionId’s

$SecurityAdminRole = (Get-AzRoleDefinition -Name 'Security Admin')
$ReaderRole = (Get-AzRoleDefinition -Name 'Reader')
$UserAccessAdminRole = (Get-AzRoleDefinition -Name 'User Access Administrator')
$ContributorRole = (Get-AzRoleDefinition -Name 'Contributor')
$LogAnalyticsContributorRole = (Get-AzRoleDefinition -Name 'Log Analytics Contributor')
$AzSubscriptionId = $AzSubscription.id

NB: The templates we’re using here are for the entire subscription but there are templates for delegating rights to a resource group or multiple resource groups on the Lighthouse GitHub.

Check for or Create the Lighthouse Admin Group

This is an AzureAD group that will be granted access in the customer subscription.
If you want to see the customer subscription at the end of this demo — you need to be in the admin group.
Put your username in the $admingroupmember variable if you’re making a new Lighthouse Admin group for this demo.

To check for, or create a new admin group, run the following section of the script:

#Check for an existing group
$AdminGroupId= (Get-AzureAdGroup -SearchString $AdminGroup).ObjectId#OR Create a new group, add the admin user and assign Reader Role rights
New-AzureADGroup -DisplayName $AdminGroup -MailEnabled $false -SecurityEnabled $true -MailNickName "NotSet" -Description "Used to enable lighthouse access to customer resources"Add-AzureADGroupMember -ObjectId $AdminGroupId -RefObjectId $AdminGroupMember.objectIdNew-AzRoleAssignment -ObjectId $AdminGroupId -RoleDefinitionName $ReaderRole.name -Scope "/subscriptions/$AzSubscriptionId"#Check the group members
Get-AzureADGroupMember -ObjectId $AdminGroupId

Download and Edit the Azure Lighthouse ARM Template Files

Next up, we need to download and edit the ARM template files that the Lighthouse team have provided. Run this section of the script to download the files:

Run this section of the script to download the files

#Download the Lighthouse Subscription Delegation Templates
#Ref & More Templates: https://docs.microsoft.com/en-us/azure/lighthouse/how-to/onboard-customer#create-your-template-manuallyNew-Item -Path $PathToTemplateFiles -Name "Lighthouse" -ItemType "directory"Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/Azure/Azure-Lighthouse-samples/master/templates/delegated-resource-management/subscription/subscription.json' -OutFile $PathToTemplateFiles\Lighthouse\subscription.json -ErrorAction Stop -VerboseInvoke-WebRequest -Uri 'https://raw.githubusercontent.com/Azure/Azure-Lighthouse-samples/master/templates/delegated-resource-management/subscription/subscription.parameters.json' -OutFile $PathToTemplateFiles\Lighthouse\subscription.parameters.json -ErrorAction Stop -Verbose

Now that the files are saved locally, we’ll take the values we defined earlier including the MSP Offer Name, MSP Subscription Tenant ID, Admin Group ID and Role Definition ID’s and copy them into the template.

Copy our unique values into the template

(Get-Content -path $PathToTemplateFiles\Lighthouse\subscription.parameters.json -Raw) | Foreach-Object {
$_ -replace 'Relecloud Managed Services',$MSPOfferName `
-replace '<insert managing tenant id>', $AzSubscription.TenantId `
-replace '00000000-0000-0000-0000-000000000000', $AdminGroupId `
-replace 'PIM_Group', $AdminGroup `
-replace 'acdd72a7-3385-48ef-bd42-f606fba81ae7', $SecurityAdminRole.id `
-replace '91c1777a-f3dc-4fae-b103-61d183457e46', $ReaderRole.id `
-replace '18d7d88d-d35e-4fb5-a5c3-7773c20a72d9', $UserAccessAdminRole.id `
-replace 'b24988ac-6180-42a0-ab88-20f7382dd24c', $ContributorRole.id `
-replace '92aaf0da-9dab-42b6-94a3-d43ce8d16293', $LogAnalyticsContributorRole.id
} | Set-Content -Path $PathToTemplateFiles\lighthouse\subscription.parameters.json

NB: I did this with PowerShell but if the Lighthouse team template changes, you might need to tweak this section a little.

Finally, deploy the template into the customer subscription

The actual template deployment needs to be done by the customer. In the case of this demo, we have both subscriptions and can log in as our mythical customer to deploy easily enough.

If you wanted to do this in the wild, you might need to provide your customers with a script or a GitHub repo page with ARM Template deployment buttons.

First up, log into the customer subscription

Clear-AzContext
Connect-AzAccountGet-AzSubscription -SubscriptionName $CustomerSubscriptionName | Set-AzContext -Force -Verbose$CustomerAZSubscription = Get-AzSubscription -SubscriptionName $CustomerSubscriptionName
Connect-AzureAD -TenantId $CustomerAzSubscription.TenantId#Confirm the correct subscription is selected before continuing
Get-AzContext

And now, the moment of truth! Deploy the templates!

New-AzSubscriptionDeployment -Name DeployServiceProviderTemplate `
-Location $Location `
-TemplateFile $PathToTemplateFiles\Lighthouse\subscription.json `
-TemplateParameterFile $PathToTemplateFiles\Lighthouse\subscription.parameters.json `
-Verbose#Confirm Successful Onboarding for Azure Lighthouse
Get-AzManagedServicesDefinition |fl
Get-AzManagedServicesAssignment |fl#In about 15 minutes the MSP should be visible in the Customer Subscription
Start-Process "https://portal.azure.com/#blade/Microsoft_Azure_CustomerHub/ServiceProvidersBladeV2/providers"

If you’re successful, you’ll see something like this:

Customer Subscription:

And if you click subscriptions, you can see and edit the resources the MSP will be able to centrally manage:

For the MSP experience, open Azure Lighthouse > My Customers and your customers will be listed:

Clicking Delegations shows you the resources that you have been delegated access to:

And if Isearch Virtual Machines in the Azure Portal (logged in as the Managed Service Provider), I can see the customer virtual machines listed seamlessly — as if they’re in my subscription.

Troubleshooting

Ah boooo, if you’re here I guess something didn’t work. Here’s some issues I ran into and how I fixed them:

DeployServiceProviderTemplate Failed

New-AzSubscriptionDeployment :'DeployServiceProviderTemplate' failed with error(s). Showing 1 out of 1 error(s).Status Message: The registration definition '0000-00000-00000000000' not allowed to use the '0000-00000-00000000000' as ManagedByTenantId. Code:InvalidRegistrationDefinitionCreateRequest)

You’re trying to use the same subscription as the Customer and the MSP — you need two subscriptions so you can delegate rights between them
You got them mixed up or when you ran the script to switch from the MSP to Customer subscription, it didn’t work because your credentials are saved somewhere.
Things to try:
Run get-azcontext to check that you’re logged into the customer subscription
Open a new PowerShell terminal to clear any saved credentials, re-run the section that defines the variables, then re-run the customer setup section

The Customer Can’t see the Azure Lighthouse Managed Service Provider Offer

Make sure you’re in the Azure Lighthouse blade
It takes a few minutes to show up so go grab a snack and come back
CTRL +F5 to properly refresh

The Managed Service Provider can’t see any customers

Make sure you’re in the Service Providers blade
Check that the user you’re logged in with is a member of the admin group defined at $admingroup so they have the rights to see the customer resources
In the MSP subscription go to Subscriptions > Subscription Name> Access Control (IAM) and view the role assignments for the user you’re logged in as.
The user will need at least Reader rights to see resources
Check the filter settings of your Azure search to make sure all subscriptions has been selected