Onboard a customer to Azure Lighthouse

This article explains how you, as a service provider, can onboard a customer to Azure Lighthouse. When you do so, delegated resources (subscriptions and/or resource groups) in the customer's Microsoft Entra tenant can be managed by users in your tenant through Azure delegated resource management.

You can repeat the onboarding process for multiple customers. When a user with the appropriate permissions signs in to your managing tenant, that user is authorized to perform management operations across customer tenancy scopes, without having to sign in to each individual customer tenant.

The onboarding process requires actions to be taken from within both the service provider's tenant and from the customer's tenant. All of these steps are described in this article.

Gather tenant and subscription details

To onboard a customer's tenant, it must have an active Azure subscription. When you create a template manually, you'll need to know the following:

• The tenant ID of the service provider's tenant (where you will be managing the customer's resources).
• The tenant ID of the customer's tenant (which will have resources managed by the service provider).
• The subscription IDs for each specific subscription in the customer's tenant that will be managed by the service provider (or that contains the resource group(s) that will be managed by the service provider).

If you don't know the ID for a tenant, you can retrieve it by using the Azure portal, Azure PowerShell, or Azure CLI.

If you create your template in the Azure portal, your tenant ID is provided automatically. You don't need to know the customer's tenant or subscription details in order to create your template in the Azure portal. However, if you plan to onboard one or more resource groups in the customer's tenant (rather than the entire subscription), you'll need to know the names of each resource group.

Define roles and permissions

As a service provider, you may want to perform multiple tasks for a single customer, requiring different access for different scopes. You can define as many authorizations as you need in order to assign the appropriate Azure built-in roles. Each authorization includes a principalId which refers to a Microsoft Entra user, group, or service principal in the managing tenant.

To define authorizations in your template, you must include the ID values for each user, user group, or service principal in the managing tenant to which you want to grant access. You'll also need to include the role definition ID for each built-in role you want to assign. When you create your template in the Azure portal, you can select the user account and role, and these ID values will be added automatically. If you are creating a template manually, you can retrieve user IDs by using the Azure portal, Azure PowerShell, or Azure CLI from within the managing tenant.

Whenever possible, we recommend using Microsoft Entra user groups for each assignment whenever possible, rather than individual users. This gives you the flexibility to add or remove individual users to the group that has access, so that you don't have to repeat the onboarding process to make user changes. You can also assign roles to a service principal, which can be useful for automation scenarios.

When defining your authorizations, be sure to follow the principle of least privilege so that users only have the permissions needed to complete their job. For information about supported roles and best practices, see Tenants, users, and roles in Azure Lighthouse scenarios.

To track your impact across customer engagements and receive recognition, associate your Microsoft Cloud Partner Program ID with at least one user account that has access to each of your onboarded subscriptions. You'll need to perform this association in your service provider tenant. We recommend creating a service principal account in your tenant that is associated with your partner ID, then including that service principal every time you onboard a customer. For more info, see Link a partner ID.

Create an Azure Resource Manager template

To onboard your customer, you'll need to create an Azure Resource Manager template for your offer with the following information. The mspOfferName and mspOfferDescription values will be visible to the customer in the Service providers page of the Azure portal once the template is deployed in the customer's tenant.

You can create this template in the Azure portal, or by manually modifying the templates provided in our samples repo.

Create your template in the Azure portal

To create your template in the Azure portal, go to My customers and then select Create ARM Template from the overview page.

On the Create ARM Template offer Page, provide your Name and an optional Description. These values will be used for the mspOfferName and mspOfferDescription in your template, and they may be visible to your customer. The managedByTenantId value will be provided automatically, based on the Microsoft Entra tenant to which you are logged in.

Next, select either Subscription or Resource group, depending on the customer scope you want to onboard. If you select Resource group, you'll need to provide the name of the resource group to onboard. You can select the + icon to add additional resource groups in the same subscription if needed. (To onboard additional resource groups in a different subscription, you must create and deploy a separate template for that subscription.)

Finally, create your authorizations by selecting + Add authorization. For each of your authorizations, provide the following details:

1. Select the Principal type depending on the type of account you want to include in the authorization. This can be either User, Group, or Service principal. In this example, we'll choose User.
2. Select the + Select user link to open the selection pane. You can use the search field to find the user you'd like to add. Once you've done so, click Select. The user's Principal ID will be automatically populated.
3. Review the Display name field (populated based on the user you selected) and make changes, if desired.
4. Select the Role to assign to this user.
5. For Access type, select Permanent or Eligible. If you choose Eligible, you will need to specify options for maximum duration, multifactor authentication, and whether or not approval is required. For more information about these options, see Create eligible authorizations. The eligible authorizations feature can't be used with service principals.
6. Select Add to create your authorization.

After you select Add, you'll return to the Create ARM Template offer screen. You can select + Add authorization again to add as many authorizations as needed.

When you've added all of your authorizations, select View template. On this screen, you'll see a .json file that corresponds to the values you entered. Select Download to save a copy of this .json file. This template can then be deployed in the customer's tenant. You can also edit it manually if you need to make any changes.

Create your template manually

You can create your template by using an Azure Resource Manager template (provided in our samples repo) and a corresponding parameter file that you modify to match your configuration and define your authorizations. If you prefer, you can include all of the information directly in the template, rather than using a separate parameter file.

The template you choose will depend on whether you are onboarding an entire subscription, a resource group, or multiple resource groups within a subscription. We also provide a template that can be used for customers who purchased a managed service offer that you published to Azure Marketplace, if you prefer to onboard their subscription(s) this way.

If you want to include eligible authorizations, select the corresponding template from the delegated-resource-management-eligible-authorizations section of our samples repo.

The following example shows a modified subscription.parameters.json file that can be used to onboard a subscription. The resource group parameter files (located in the rg-delegated-resource-management folder) have a similar format, but they also include an rgName parameter to identify the specific resource group(s) to be onboarded.

{
    "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "mspOfferName": {
            "value": "Fabrikam Managed Services - Interstellar"
        },
        "mspOfferDescription": {
            "value": "Fabrikam Managed Services - Interstellar"
        },
        "managedByTenantId": {
            "value": "00000000-0000-0000-0000-000000000000"
        },
        "authorizations": {
            "value": [
                {
                    "principalId": "00000000-0000-0000-0000-000000000000",
                    "principalIdDisplayName": "Tier 1 Support",
                    "roleDefinitionId": "b24988ac-6180-42a0-ab88-20f7382dd24c"
                },
                {
                    "principalId": "00000000-0000-0000-0000-000000000000",
                    "principalIdDisplayName": "Tier 1 Support",
                    "roleDefinitionId": "36243c78-bf99-498c-9df9-86d9f8d28608"
                },
                {
                    "principalId": "00000000-0000-0000-0000-000000000000",
                    "principalIdDisplayName": "Tier 2 Support",
                    "roleDefinitionId": "acdd72a7-3385-48ef-bd42-f606fba81ae7"
                },
                {
                    "principalId": "00000000-0000-0000-0000-000000000000",
                    "principalIdDisplayName": "Service Automation Account",
                    "roleDefinitionId": "b24988ac-6180-42a0-ab88-20f7382dd24c"
                },
                {
                    "principalId": "00000000-0000-0000-0000-000000000000",
                    "principalIdDisplayName": "Policy Automation Account",
                    "roleDefinitionId": "18d7d88d-d35e-4fb5-a5c3-7773c20a72d9",
                    "delegatedRoleDefinitionIds": [
                        "b24988ac-6180-42a0-ab88-20f7382dd24c",
                        "92aaf0da-9dab-42b6-94a3-d43ce8d16293"
                    ]
                }
            ]
        }
    }
}

The last authorization in the example above adds a principalId with the User Access Administrator role (18d7d88d-d35e-4fb5-a5c3-7773c20a72d9). When assigning this role, you must include the delegatedRoleDefinitionIds property and one or more supported Azure built-in roles. The user created in this authorization will be able to assign these roles to managed identities in the customer tenant, which is required in order to deploy policies that can be remediated. The user is also able to create support incidents. No other permissions normally associated with the User Access Administrator role will apply to this principalId.

Deploy the Azure Resource Manager template

Once you have created your template, a user in the customer's tenant must deploy it within their tenant. A separate deployment is needed for each subscription that you want to onboard (or for each subscription that contains resource groups that you want to onboard).

When onboarding a subscription (or one or more resource groups within a subscription) using the process described here, the Microsoft.ManagedServices resource provider will be registered for that subscription.

The deployment may be done by using PowerShell, by using Azure CLI, or in the Azure portal, as shown below.

Deploy by using PowerShell

To deploy a single template:

# Log in first with Connect-AzAccount if you're not using Cloud Shell

# Deploy Azure Resource Manager template using template and parameter file locally
New-AzSubscriptionDeployment -Name <deploymentName> `
                 -Location <AzureRegion> `
                 -TemplateFile <pathToTemplateFile> `
                 -Verbose

# Deploy Azure Resource Manager template that is located externally
New-AzSubscriptionDeployment -Name <deploymentName> `
                 -Location <AzureRegion> `
                 -TemplateUri <templateUri> `
                 -Verbose

To deploy a template with a separate parameter file:

# Log in first with Connect-AzAccount if you're not using Cloud Shell

# Deploy Azure Resource Manager template using template and parameter file locally
New-AzSubscriptionDeployment -Name <deploymentName> `
                 -Location <AzureRegion> `
                 -TemplateFile <pathToTemplateFile> `
                 -TemplateParameterFile <pathToParameterFile> `
                 -Verbose

# Deploy Azure Resource Manager template that is located externally
New-AzSubscriptionDeployment -Name <deploymentName> `
                 -Location <AzureRegion> `
                 -TemplateUri <templateUri> `
                 -TemplateParameterUri <parameterUri> `
                 -Verbose

Deploy by using Azure CLI

To deploy a single template:

# Log in first with az login if you're not using Cloud Shell

# Deploy Azure Resource Manager template using template and parameter file locally
az deployment sub create --name <deploymentName> \
                         --location <AzureRegion> \
                         --template-file <pathToTemplateFile> \
                         --verbose

# Deploy external Azure Resource Manager template, with local parameter file
az deployment sub create --name <deploymentName> \
                         --location <AzureRegion> \
                         --template-uri <templateUri> \
                         --verbose

To deploy a template with a separate parameter file:

# Log in first with az login if you're not using Cloud Shell

# Deploy Azure Resource Manager template using template and parameter file locally
az deployment sub create --name <deploymentName> \
                         --location <AzureRegion> \
                         --template-file <pathToTemplateFile> \
                         --parameters <parameters/parameterFile> \
                         --verbose

# Deploy external Azure Resource Manager template, with local parameter file
az deployment sub create --name <deploymentName> \
                         --location <AzureRegion> \
                         --template-uri <templateUri> \
                         --parameters <parameterFile> \
                         --verbose

Deploy in the Azure portal

To deploy a template in the Azure portal, follow the process described below. These steps must be done by a user in the customer tenant with the Owner role (or another role with the Microsoft.Authorization/roleAssignments/write permission).

1. From the Service providers page in the Azure portal, select Server provider offers.

2. Near the top of the screen, select the arrow next to Add offer, and then select Add via template.

   

3. Upload the template by dragging and dropping it, or select Browse for files to find and upload the template.

4. If applicable, select the I have a separate parameter file box, then upload your parameter file.

5. After you've uploaded your template (and parameter file if needed), select Upload.

6. In the Custom deployment screen, review the details that appear. If needed, you can make changes to these values in this screen, or by selecting Edit parameters.

7. Select Review and create, then select Create.

After a few minutes, you should see a notification that the deployment has completed.

Confirm successful onboarding

When a customer subscription has successfully been onboarded to Azure Lighthouse, users in the service provider's tenant will be able to see the subscription and its resources (if they have been granted access to it through the process above, either individually or as a member of a Microsoft Entra group with the appropriate permissions). To confirm this, check to make sure the subscription appears in one of the following ways.

Confirm in the Azure portal

In the service provider's tenant:

1. Navigate to the My customers page.
2. Select Customers.
3. Confirm that you can see the subscription(s) with the offer name you provided in the Resource Manager template.

In the customer's tenant:

1. Navigate to the Service providers page.
2. Select Service provider offers.
3. Confirm that you can see the subscription(s) with the offer name you provided in the Resource Manager template.

Confirm by using PowerShell

# Log in first with Connect-AzAccount if you're not using Cloud Shell

Get-AzContext

# Confirm successful onboarding for Azure Lighthouse

Get-AzManagedServicesDefinition
Get-AzManagedServicesAssignment

Confirm by using Azure CLI

# Log in first with az login if you're not using Cloud Shell

az account list

# Confirm successful onboarding for Azure Lighthouse

az managedservices definition list
az managedservices assignment list

If you need to make changes after the customer has been onboarded, you can update the delegation. You can also remove access to the delegation completely.

Troubleshooting

If you are unable to successfully onboard your customer, or if your users have trouble accessing the delegated resources, check the following tips and requirements and try again.

• Users who need to view customer resources in the Azure portal must have been granted the Reader role (or another built-in role which includes Reader access) during the onboarding process.
• The managedbyTenantId value must not be the same as the tenant ID for the subscription being onboarded.
• You can't have multiple assignments at the same scope with the same mspOfferName.
• The Microsoft.ManagedServices resource provider must be registered for the delegated subscription. This should happen automatically during the deployment but if not, you can register it manually.
• Authorizations must not include any users with the Owner role, any roles with DataActions, or any roles that include restricted actions.
• Groups must be created with Group type set to Security and not Microsoft 365.
• If access was granted to a group, check to make sure the user is a member of that group. If they aren't, you can add them to the group using Microsoft Entra ID, without having to perform another deployment. Note that group owners are not necessarily members of the groups they manage, and may need to be added in order to have access.
• There may be an additional delay before access is enabled for nested groups.
• The Azure built-in roles that you include in authorizations must not include any deprecated roles. If an Azure built-in role becomes deprecated, any users who were onboarded with that role will lose access, and you won't be able to onboard additional delegations. To fix this, update your template to use only supported built-in roles, then perform a new deployment.

Next steps

• Learn about cross-tenant management experiences.
• View and manage customers by going to My customers in the Azure portal.
• Learn how to update or remove a delegation.