Merge pull request #12355 from rhrivnak/patch-1

Set-CsTenantFederationConfiguration - new AllowedTrialTenantDomains parameter docs

Author: padmagit77

teams/teams-ps/teams/Set-CsTenantFederationConfiguration.md

@@ -8,6 +8,7 @@ manager: bulenteg
 author: tomkau
 ms.author: tomkau
 ms.reviewer: williamlooney
+ms.date: 12/11/2024
 ---
 
 # Set-CsTenantFederationConfiguration
@@ -25,6 +26,7 @@ Set-CsTenantFederationConfiguration [-Tenant <Guid>]
  [-AllowFederatedUsers <Boolean>] [-AllowPublicUsers <Boolean>] [-AllowTeamsConsumer <Boolean>] [-AllowTeamsConsumerInbound <Boolean>]
  [-TreatDiscoveredPartnersAsUnverified <Boolean>] [-SharedSipAddressSpace <Boolean>] [-RestrictTeamsConsumerToExternalUserProfiles <Boolean>]
  [-AllowedDomainsAsAList <List>] [-ExternalAccessWithTrialTenants <ExternalAccessWithTrialTenantsType>] [-CustomizeFederation <Boolean>]
+ [-AllowedTrialTenantDomains <List>]
  [[-Identity] <XdsIdentity>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
@@ -175,13 +177,49 @@ Set-CsTenantFederationConfiguration -ExternalAccessWithTrialTenants "Allowed"
 
 Example 11 shows how you can allow users to communicate with users in tenants that contain only trial licenses (default value is Blocked).
 
-### -------------------------- Example 12 -------------------------
+### -------------------------- Example 12 --------------------------
 ```
-Set-CsTenantFederationConfiguration -CustomizeFederation $True
+$list = New-Object Collections.Generic.List[String]
+$list.add("contoso.com")
+$list.add("fabrikam.com")
+
+Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains $list
 ```
 
-Example 12 shows how you can enable the feature where you can customize your federation in ExternalAccessPolicy.
+Using the `AllowedTrialTenantDomains` parameter, you can whitelist specific "trial-only" tenant domains, while keeping the `ExternalAccessWithTrialTenants` set to `Blocked`. Example 12 shows how you can set or replace domains in the Allowed Trial Tenant Domains using a List collection object. 
+First, a List collection is created and domains are added to it, then, simply include the `AllowedTrialTenantDomains` parameter and set the parameter value to the List object. 
+When this command completes, the Allowed Trial Tenant Domains list will be replaced with those domains.
 
+### -------------------------- Example 13 --------------------------
+```
+$list = New-Object Collections.Generic.List[String]
+$list.add("contoso.com")
+
+Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains @{Add=$list}
+```
+
+Example 13 shows how you can add domains to the existing Allowed Trial Tenant Domains using a List collection object.
+First, a List is created and domains are added to it, then, use the Add method in the `AllowedTrialTenantDomains` parameter to add the domains to the existing allowed domains list.
+When this command completes, the domains in the list will be added to any domains already on the Allowed Trial Tenant Domains list.
+
+### -------------------------- Example 14 --------------------------
+```
+$list = New-Object Collections.Generic.List[String]
+$list.add("contoso.com")
+
+Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains @{Remove=$list}
+```
+
+Example 14 shows how you can remove domains from the existing Allowed Trial Tenant Domains using a List collection object.
+First, a List is created and domains are added to it, then use the Remove method in the `AllowedTrialTenantDomains` parameter to remove the domains from the existing allowed domains list.
+When this command completes, the domains in the list will be removed from the Allowed Trial Tenant Domains list.
+
+### -------------------------- Example 15 -------------------------
+```
+Set-CsTenantFederationConfiguration -CustomizeFederation $True
+```
+
+Example 15 shows how you can enable the feature where you can customize your federation in ExternalAccessPolicy.
 
 ## PARAMETERS
 
@@ -475,6 +513,27 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -AllowedTrialTenantDomains
+You can whitelist specific "trial-only" tenant domains, while keeping the `ExternalAccessWithTrialTenants` set to `Blocked`. This will allow you to protect your organization against majority of tenants that don't have any paid subscriptions, while still being able to collaborate externally with those trusted trial-tenants in the list. 
+ 
+Note: 
+- The list supports up to maximum 4k domains.
+- If `ExternalAccessWithTrialTenants` is set to `Allowed`, then the `AllowedTrialTenantDomains` list will not be checked. 
+- Any domain in this list that belongs to a tenant with paid subscriptions will be ignored.
+
+```yaml
+Type: List
+Parameter Sets: (All)
+Aliases: 
+applicable: Microsoft Teams
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -RestrictTeamsConsumerToExternalUserProfiles
 Defines if a user is restriced to collaboration with Teams Consumer (TFL) user only in Extended Directory.
 Possible values: True, False