Programmatically create MCA subscriptions across Microsoft Entra tenants

  • Article

This article helps you programmatically create a Microsoft Customer Agreement (MCA) subscription across Microsoft Entra tenants. In some situations, you might need to create MCA subscriptions across Microsoft Entra tenants but have them tied to a single billing account. Examples of such situations include SaaS providers wanting to segregate hosted customer services from internal IT services or internal environments that have strict regulatory compliance requirements, like Payment Card Industry (PCI).

The process to create an MCA subscription across tenants is effectively a two-phase process. It requires actions to be taken in the source and destination Microsoft Entra tenants. This article uses the following terminology:

  • Source Microsoft Entra ID (source.partner.onmschina.cn). It represents the source tenant where the MCA billing account exists.
  • Destination Cloud Microsoft Entra ID (destination.partner.onmschina.cn). It represents the destination tenant where the new MCA subscriptions are created.

You can't create support plans programmatically. You can buy a new support plan or upgrade one in the Azure portal. Navigate to Help + support and then at the top of the page, select Choose the right support plan.

Prerequisites

You must you already have the following tenants created:

Application set-up

Use the information in the following sections to set up and configure the needed applications in the source and destination tenants.

Register an application in the source tenant

To programmatically create an MCA subscription, a Microsoft Entra application must be registered and granted the appropriate Azure RBAC permission. For this step, ensure you're signed into the source tenant (source.partner.onmschina.cn) with an account that has permissions to register Microsoft Entra applications.

Following the steps in Quickstart: Register an application with the Microsoft identity platform.

For the purposes of this process, you only need to follow the Register an application and Add credentials sections.

Save the following information to test and configure your environment:

  • Directory (tenant) ID
  • Application (client) ID
  • Object ID
  • App secret value that was generated. The value is only visible at the time of creation.

Create a billing role assignment for the application in the source tenant

Review the information at Understand Microsoft Customer Agreement administrative roles in Azure to determine the appropriate scope and billing role for the application.

After you determine the scope and role, use the information at Manage billing roles in the Azure portal to create the role assignment for the application. Search for the application by using the name that you used when you registered the application in the preceding section.

Register an application in the destination tenant

To accept the MCA subscription from the destination tenant (destination.partner.onmschina.cn), a Microsoft Entra application must be registered and added to the Billing administrator Microsoft Entra role. For this step, ensure you're signed in to the destination tenant (destination.partner.onmschina.cn) with an account that has permissions to register Microsoft Entra applications. It must also have billing administrator role permission.

Follow the same steps used above to register an application in the source tenant. Save the following information to test and configure your environment:

  • Directory (tenant) ID
  • Application (client) ID
  • Object ID
  • App secret value that was generated. The value is only visible at the time of creation.

Add the destination application to the Billing administrator Microsoft Entra role

Use the information at Assign administrator and non-administrator roles to users with Microsoft Entra ID to add the destination application created in the preceding section to the Billing administrator Microsoft Entra role in the destination tenant.

Programmatically create a subscription

With the applications and permissions already set up, use the following information to programmatically create subscriptions.

Get the ID of the destination application service principal

When you create an MCA subscription in the source tenant, you must specify the service principal or SPN of the application in the destination tenant as the owner. Use one of the following methods to get the ID. In both methods, the value to use for the empty GUID is the application (client) ID of the destination tenant application created previously.

Azure CLI

Sign in to Azure CLI and use the az ad sp show command:

az ad sp show --id aaaaaaaa-bbbb-cccc-1111-222222222222 --query 'id'

Azure PowerShell

Sign in to Azure PowerShell and use the Get-AzADServicePrincipal cmdlet:

Get-AzADServicePrincipal -ApplicationId aaaaaaaa-bbbb-cccc-1111-222222222222 | Select-Object -Property Id

Save the Id value returned by the command.

Create the subscription

Use the following information to create a subscription in the source tenant.

Get a source application access token

Replace the {{placeholders}} with the actual tenant ID, application (client) ID, and the app secret values that you saved when you created the source tenant application previously.

Invoke the request and save the access_token value from the response for use in the next step.

POST https://login.partner.microsoftonline.cn/{{tenant_id}}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{client_id}}&client_secret={{app_secret}}&resource=https%3A%2F%2Fmanagement.chinacloudapi.cn%2F

Get the billing account, profile, and invoice section IDs

Use the information at Find billing accounts that you have access to and Find billing profiles & invoice sections to create subscriptions sections to get the billing account, profile, and invoice section IDs.

Note

We recommend using the REST method with the access token obtained previously to verify that the application billing role assignment was created successfully in the Application Setup section.

Create a subscription alias

With the billing account, profile, and invoice section IDs, you have all the information needed to create the subscription:

  • {{guid}}: Can be a valid GUID.
  • {{access_token}}: Access token of the source tenant application obtained previously.
  • {{billing_account}}: ID of the billing account obtained previously.
  • {{billing_profile}}: ID of the billing profile obtained previously.
  • {{invoice_section}}: ID of the invoice section obtained previously.
  • {{destination_tenant_id}}: ID of the destination tenant as noted when you previously created the destination tenant application.
  • {{destination_service_principal_id}}: ID of the destination tenant service principal that you got from the Get the ID of the destination application service principal section previously.

Send the request and note the value of the Location header in the response.

PUT https://management.chinacloudapi.cn/providers/Microsoft.Subscription/aliases/{{guid}}?api-version=2021-10-01
Authorization: Bearer {{access_token}}
Content-Type: application/json

{
  "properties": {
    "displayName": "{{subscription_name}}",
    "workload": "Production",
    "billingScope": "/billingAccounts/{{billing_account}}/billingProfiles/{{billing_profile}}/invoiceSections/{{invoice_section}}",
    "subscriptionId": null,
    "additionalProperties": {
      "managementGroupId": null,
      "subscriptionTenantId": "{{destination_tenant_id}}",
      "subscriptionOwnerId": "{{destination_service_principal_id}}"
    }
  }
}

Accept subscription ownership

The last phase to complete the process is to accept subscription ownership.

Get a destination application access token

Replace {{placeholders}} with the actual tenant ID, application (client) ID, and app secret values that you saved when you created the destination tenant application previously.

Invoke the request and save the access_token value from the response for the next step.

POST https://login.partner.microsoftonline.cn/{{tenant_id}}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{client_id}}&client_secret={{app_secret}}&resource=https%3A%2F%2Fmanagement.chinacloudapi.cn%2F

Accept ownership

Use the following information to accept ownership of the subscription in the destination tenant:

  • {{subscription_id}}: ID of the subscription created in the Create subscription alias section. It's contained in the location header that you noted.
  • {{access_token}}: Access token created in the previous step.
  • {{subscription_display_name}}: Display name for the subscription in your Azure environment.
POST https://management.chinacloudapi.cn/providers/Microsoft.Subscription/subscriptions/{{subscription_id}}/acceptOwnership?api-version=2021-10-01
Authorization: Bearer {{access_token}}
Content-Type: application/json

{
  "properties": {
    "displayName": "{{subscription_display_name}}",
    "managementGroupId": null
  }
}

Next steps