Modifying the Teams Tenant Federation Configuration with PowerShell

Blocking Sub-Domains in the Tenant Federation Configuration

The publication of message center notification MC770792 (5 April 2024) describing a new Teams tenant federation setting to block all sub-domains of a blocked domain seems like a very good idea. After all, if you decide to block inbound connections from “malware.com.” it’s likely that you also want to block sub-domains like “marketing.malware.com.”

Microsoft says that the update should be in all tenants by mid-April. From an administrator perspective, the change becomes active with version 6.1 of the Microsoft Teams PowerShell module, which adds support for the BlockAllSubdomains switch for the Set-CsTenantFederationConfiguration cmdlet. For example:

Set-CsTenantFederationConfiguration -BlockAllSubdomains $True -BlockedDomains "malware.com"

The new setting isn’t used by default and won’t affect existing block lists. If you do use it, Microsoft notes that the setting blocks “all new communication to and from subdomains in the Block list… Existing 1:1 chats with users from blocked subdomains will be disabled. In existing group chats with users from blocked subdomains, the users from the blocked subdomains will be removed from the group chat.”

Updating the Allow List

In September 2022, I wrote an article explaining how to update the Teams external federation configuration with PowerShell. The idea was to create an allow list for federated chat based on the home domains for guest accounts known in the tenant directory. The article was a response to the theoretical “GIFShell” attack against Teams by a security researcher. Having an allow list of known domains means that users can only communicate with users belonging to domains in the allow list using one-to-one federated chat. It’s still the most effect way of blocking potential malware arriving in a tenant via Teams chat with an attacker.

I looked over the code to remind myself about how to manipulate the tenant federation configuration and realized that a nice update would be to check the domains for guest accounts to make sure that they are Microsoft 365 tenants before adding them to the tenant federation configuration. For instance, guest accounts might belong to domains like gmail.com, yahoo.com, and outlook.com, but there’s no need to have these large consumer domains in the configuration.

The technique explained in the article about tenant identifiers provided the foundation for the solution. I created a function to check if a domain is a Microsoft 365 tenant and call the function to check a domain before including it in the list to update the tenant federation configuration with. Here’s the function:

function Get-DomainByCheck {
# Check a domain name to make sure that it's active
  param (
      [parameter(Mandatory = $true)]
      $Domain
  )

  $Uri = ("https://graph.microsoft.com/v1.0/tenantRelationships/findTenantInformationByDomainName(domainName='{0}')" -f $Domain) 
  Try {	
    [array]$Global:DomainData = Invoke-MgGraphRequest -Uri $Uri -Method Get -ErrorAction Stop
    If ($DomainData.displayname -in $UnwantedRealms) {
      Return $false
    } Else {
      Return $true
    }
  } Catch {
    Return $false
  }
}

Domains that pass the test are added to the tenant federation configuration, which is also available through the Settings & Policies section of the Teams admin center (Figure 1).

Dealing with Unwanted Domains

You’ll notice that the function checks against an array called $UnwantedRealms. If a domain is found in the array, the function returns false to indicate that the domain shouldn’t be added to the tenant federation configuration. The script defines the array as follows:

$Global:UnwantedRealms = "MSA Realms", "Test_Test_Microsoft"

If the Graph findTenantInformationByDomainName API matches a Microsoft 365 tenant, its display name is returned in the domain information fetched by the request. For instance, if the function checks Microsoft.com, the display name is Microsoft. But if it checks a domain which is federated for identity purposes with Entra ID, like gmail.com, the display name is “MSA Realms.” And the display name returned for the domains used by Teams to deliver email to channels (like amer.teams.ms) is “Test_Test_Microsoft.” Perhaps the engineers never thought that the display name they selected for these domains would ever see the light of day…

Why would guest accounts have email addresses belong to Teams channels? The SMTP addresses generated by Teams for channels can be given to guest accounts to allow the account to be a member of a Microsoft 365 group. Any email sent to the group will automatically end up as a channel conversation and serve as a record of that email interaction. Another method to bring email into Teams is to create mail contacts with Teams channel addresses and include them in distribution lists. In any case, we don’t need to include the Teams email domains in the tenant federation configuration, which is why the script excludes them.

Scripting Makes Processing Multiple Domains Easier

The Teams tenant federation configuration is easy to maintain through the Teams admin center. PowerShell makes it easier when large numbers of domains are involved. If you want to see the code I used, download the script from GitHub.

---

Insight like this doesn’t come easily. You’ve got to know the technology and understand how to look behind the scenes. Benefit from the knowledge and experience of the Office 365 for IT Pros team by subscribing to the best eBook covering Office 365 and the wider Microsoft 365 ecosystem.