Multitenant organization
A multitenant organization is an organization which has more than one tenants, it means, it has more instances of Microsoft Entra ID.
Why to have multiple tenants? The most common reasons are:
- Business: organizations with multiple subsidiaries or with acquired companies
- Regulations: organizations with different compliance or regulatory needs or operating in multiple geographies
- Testing: organizations with multiple tenants for development, testing or staging purposes
You can read more details about multitenant organization in the official Microsoft documentation.
Manage multitenant organization programmatically
Microsoft Graph API introduces a new Multitenant organization API. To be able to use this API on behalf of a user, the user must be either Security Administrator or Global Administrator.
Examples below require the Microsoft Graph PowerShell SDK, at least version 2.19 which is the first version that has cmdlets for managing the multitenant organization.
I will authenticate with a client secret through the Entra ID application with granted application permission MultiTenant.ReadWrite.All.
To connect with client secret:
$clientId = '<client_id>'
$tenantId = '<tenant_id>'
$secret = '<client_secret>'
$clientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $clientId, (ConvertTo-SecureString -String $secret -AsPlainText -Force)
Connect-MgGraph -ClientSecretCredential $clientSecretCredential -TenantId $tenantId -NoWelcome
Read properties of the multitenant organization
To read properties, call cmdlet Get-MgTenantRelationshipMultiTenantOrganization. The response contains properties like description, displayName or state.
Id CreatedDateTime Description DisplayName State
-- --------------- ----------- ----------- -----
b5f05824-81ee-4daf-b341-2753eecf70ab inactive
When the multitenant organization feature is not active, the state will be set to inactive.
Activate a new multitenant organization
To activate the multitenant organization feature, you need to setup display name and optionally description by using Set-MgTenantRelationshipMultiTenantOrganization cmdlet.
$params = @{
displayName = "Martin Corp"
description = "Tenants for development and testing"
}
Set-MgTenantRelationshipMultiTenantOrganization -BodyParameter $params
In the response, the property state is now active which indicates that the multitenant organization has been created successfully.
Id CreatedDateTime Description DisplayName State
-- --------------- ----------- ----------- -----
a9c5b810-44f2-4dc7-9e49-fbc3a8b0ce1e 5/10/2024 6:40:41 AM Tenants for development and testing Martin Corp active
Update the multitenant organization
For some unknown reason, there is no cmdlet for updating properties of existing multitenat organization. Cmdlets are auto-generated based on metadata exposed by the Graph API, so hopefully the next version of the PowerShell SDK will support the update.
I would expect cmdlet like Update-MgTenantRelationshipMultiTenantOrganization. The usage should be very similar to Set-MgTenantRelationshipMultiTenantOrganization.
List tenants in the multitenant organization
When you create a new multitenant organization, your tenant is automatically added to the multitenant organization as the owner.
Cmdlet Get-MgTenantRelationshipMultiTenantOrganizationTenant retrieves all tenants in the multitenant organization.
Get-MgTenantRelationshipMultiTenantOrganizationTenant
The response:
Id AddedByTenantId AddedDateTime DisplayName JoinedDateTime Role State TenantId
-- --------------- ------------- ----------- -------------- ---- ----- --------
086f77fd-e1a7-4d4b-8727-4d4a9f99b8ec 70cf0eca-e1e8.. 5/10/2024 6:40:40 AM MSFT owner active 70cf0eca-e1e8...
There are two types of role for tenants:
- owner: Can manage the multitenant organization. There can be multiple tenants with the owner role
- member: Can only participate in a multitenant organization
The state of the tenant can be:
- active: Tenant can participate in the multitenant organization
- pending: Tenant was added to the multitenant organization, but the admin of the added tenant must submit join request to complete adding
- removed: Tenant is being removed from the multitenant organization
You can filter tenants by either state or role, but not by both.
Get-MgTenantRelationshipMultiTenantOrganizationTenant -Filter "role eq 'owner'"
Get-MgTenantRelationshipMultiTenantOrganizationTenant -Filter "state eq 'pending'"
Even if the official documentation claims that filtering by tenantId is supported, in fact it's not.
Add tenant to the multitenant organization
Only the admin of a owner tenant can add other tenants to the multitenant organization. Id of the tenant to be added is required.
If you don't know the tenant id, you can use the endpoint findTenantInformationByDomainName and find the tenant id based on the domain name.
PowerShell SDK doesn't have cmdlet for this endpoint, but as an alternative, you can call the endpoint via Invoke-MgGraphRequest:
Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/v1.0/tenantRelationships/findTenantInformationByDomainName(domainName='contoso.com')"
The endpoint requires CrossTenantInformation.ReadBasic.All permission. The response contains tenant id.
Name Value
---- -----
@odata.context https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.tenantInformation
tenantId 6babcaad-604b-40ac-a9d7-9fd97c0b779f
displayName Contoso, Ltd
federationBrandName
defaultDomainName CONTOSO18839.onmicrosoft.com
So, let's try to add Contoso tenant to the multitenant organization via cmdlet New-MgTenantRelationshipMultiTenantOrganizationTenant.
$params = @{
tenantId = "6babcaad-604b-40ac-a9d7-9fd97c0b779f"
displayName = "Contoso, Ltd",
role = "member"
}
New-MgTenantRelationshipMultiTenantOrganizationTenant -BodyParameter $params
I've specified tenant id, display name and the role.
The response from Get-MgTenantRelationshipMultiTenantOrganizationTenant will be
Id AddedByTenantId AddedDateTime DisplayName JoinedDateTime Role State TenantId
-- --------------- ------------- ----------- -------------- ---- ----- --------
086f77fd-e1a7-4d4b-8727-4d4a9f99b8ec 70cf0eca-e1e8.. 5/10/2024 6:40:40 AM MSFT owner active 70cf0eca-e1e8...
efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f 70cf0eca-e1e8.. 5/10/2024 8:11:12 AM Contoso, Ltd member pending 6babcaad-604b...
The Contoso tenant is now in pending state until its admin will send join request. The admin can check the join request via Get-MgTenantRelationshipMultiTenantOrganizationJoinRequest.
Id AddedByTenantId MemberState Role
-- --------------- ----------- ----
efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f 70cf0eca-e1e8-4d78-9d03-62ecf811dfc2 pending member
We can see which tenant wants to add our tenant to the multitenant organization and what's the current state of the join request.
Confirm join request
To confirm the join request, use cmdlet Update-MgTenantRelationshipMultiTenantOrganizationJoinRequest and in the body set the addedByTenantId property to a tenant that added the current tenant to the multitenant organization.
$params = @{
addedByTenantId = "70cf0eca-e1e8-4d78-9d03-62ecf811dfc2"
}
Update-MgTenantRelationshipMultiTenantOrganizationJoinRequest -BodyParameter $params
Remove tenants and delete the multitenant organization
An active member tenant can remove itself from the multitenant organization. An active owner tenant can remove any other tenant and itself. If the active owner remove itself and there is no other active tenant, it will delete the entire multitenant organization.
To remove the tenant, use Remove-MgTenantRelationshipMultiTenantOrganizationTenant cmdlet and specify id of the member to be removed returned by Get-MgTenantRelationshipMultiTenantOrganizationTenant in MultiTenantOrganizationMemberId parameter. Also tenant id can be used.
# for Contoso tenant, efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f represents id returned by Get-MgTenantRelationshipMultiTenantOrganizationTenant
Remove-MgTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f
# also tenant id is acceptable
Remove-MgTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId 6babcaad-604b-40ac-a9d7-9fd97c0b779f
