Introducing Granular Federation Controls and updating behavior of AllowFederatedUsers

teams/teams-ps/MicrosoftTeams/New-CsEdgeDomainPattern.md

@@ -37,7 +37,10 @@ Whether or not users can communicate with people who have accounts on public IM
 Federation is managed, in part, by using allowed domain and blocked domain lists.
 The allowed domain list specifies the domains that users are allowed to communicate with; the blocked domain list specifies the domains that users are not allowed to communicate with.
 By default, users can communicate with any domain that does not appear on the blocked list.
-However, administrators can modify this default setting and limit communication to domains that are on the allowed domains list.
+However, administrators can modify this default setting and limit communication to domains that are on the allowed domains list. 
+
+> [!IMPORTANT]
+> The `AllowFederatedUsers` property must be set to `True` for the `AllowedDomains` list to take effect. If `AllowFederatedUsers` is set to `False`, users will be blocked from communicating with all external domains regardless of the values in `AllowedDomains` or any `ExternalAccessPolicy` instance.
 
 Skype for Business Online does not allow you to directly modify the allowed list or the blocked list; for example, you cannot use a command similar to this one, which passes a string value representing a domain name to the blocked domains list:
 
@@ -59,8 +62,30 @@ Set-CsTenantFederationConfiguration -BlockedDomains $x
 ```
 
 Example 1 demonstrates how you can assign a single domain to the blocked domains list for a specified tenant.
-To do this, the first command in the example creates a domain object for the domain fabrikam.com; this is done by calling the New-CsEdgeDomainPattern cmdlet and by saving the resulting domain object in a variable named $x.
-The second command then uses the Set-CsTenantFederationConfiguration cmdlet and the BlockedDomains parameter to configure fabrikam.com as the only domain blocked by the current tenant.
+To do this, the first command in the example creates a domain object for the domain fabrikam.com; this is done by calling the `New-CsEdgeDomainPattern` cmdlet and by saving the resulting domain object in a variable named $x.
+The second command then uses the `Set-CsTenantFederationConfiguration` cmdlet and the `BlockedDomains` parameter to configure fabrikam.com as the only domain blocked by the current tenant. Please note that `AllowFederatedUsers` should be `True` for this to work.
+
+### Example 2
+```
+$x = New-CsEdgeDomainPattern -Domain "fabrikam.com"
+
+Set-CsTenantFederationConfiguration -AllowedDomains $x
+```
+
+Example 2 demonstrates how you can assign a single domain to the allowed domains list for a specified tenant.
+To do this, the first command in the example creates a domain object for the domain fabrikam.com; this is done by calling the `New-CsEdgeDomainPattern` cmdlet and by saving the resulting domain object in a variable named $x.
+The second command then uses the `Set-CsTenantFederationConfiguration` cmdlet and the `AllowedDomains` parameter to configure fabrikam.com as the only domain allowed by the current tenant. Please note that `AllowFederatedUsers` should be `True` for this to work.
+
+### Example 3
+```
+$x = New-CsEdgeDomainPattern -Domain ""
+
+Set-CsTenantFederationConfiguration -AllowedDomains $x
+```
+
+Example 3 demonstrates how you can block a specified tenant from any external federation.
+To do this, the first command in the example creates an empty domain object; this is done by calling the `New-CsEdgeDomainPattern` cmdlet and by saving the resulting domain object in a variable named $x.
+The second command then uses the `Set-CsTenantFederationConfiguration` cmdlet and the `AllowedDomains` parameter to configure the current tenant with a Block-All setting. Please note that `AllowFederatedUsers` should be `True` in case you want to allow specific users to be able to communicate externally via `ExternalAccessPolicy` instances.
 
 ## PARAMETERS
 

teams/teams-ps/MicrosoftTeams/Set-CsExternalAccessPolicy.md

@@ -91,7 +91,10 @@ This enables your users to use Skype for Business and log on to Skype for Busine
 
 After an external access policy has been created, you can use the `Set-CsExternalAccessPolicy` cmdlet to change the property values of that policy.
 For example, by default the global policy does not allow users to communicate with people who have accounts with a federated organization.
-If you would like to grant this capability to all of your users you can call the `Set-CsExternalAccessPolicy` cmdlet and set the value of the global policy's EnableFederationAccess property to True.
+If you would like to grant this capability to all of your users you can call the `Set-CsExternalAccessPolicy` cmdlet and set the value of the global policy's EnableFederationAccess property to True. 
+
+> [!NOTE]
+> For the domain settings defined under `AllowFederatedUsers` to be applied, the value of the property `AllowedFederatedUsers` under `TenantFederationConfiguration` should be set to `True` for the Tenant.
 
 ## EXAMPLES
 
@@ -118,7 +121,7 @@ Get-CsExternalAccessPolicy -Filter tag:* | Set-CsExternalAccessPolicy -EnableFed
 ```
 
 Example 3 enables federation access for all the external access policies that have been configured at the per-user scope.
-To carry out this task, the first thing the command does is use the `Get-CsExternalAcessPolicy` cmdlet and the Filter parameter to return a collection of all the policies that have been configured at the per-user scope.
+To carry out this task, the first thing the command does is use the `Get-CsExternalAccessPolicy` cmdlet and the Filter parameter to return a collection of all the policies that have been configured at the per-user scope.
 (The filter value "tag:*" limits returned data to policies that have an Identity that begins with the string value "tag:".
 Any policy with an Identity that begins with "tag:" has been configured at the per-user scope.) The filtered collection is then piped to the `Set-CsExternalAccessPolicy` cmdlet, which modifies the EnableFederationAccess property for each policy in the collection.
 
@@ -152,7 +155,7 @@ In this example, we create an ExternalAccessPolicy named "GranularFederationExam
 > Applicable: Lync Server 2010, Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019
 
 > [!NOTE]
-> Please note that this parameter is in Private Preview.
+> Please note that this parameter is in Public Preview.
 
 Specifies the external domains allowed to communicate with users assigned to this policy. This setting is applicable only when `CommunicationWithExternalOrgs` is configured to `AllowSpecificExternalDomains`. This setting can be modified only in custom policy. In Global (default) policy `CommunicationWithExternalOrgs` can only be set to `OrganizationDefault` and cannot be changed.
 ```yaml
@@ -172,7 +175,7 @@ Accept wildcard characters: False
 > Applicable: Lync Server 2010, Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019
 
 > [!NOTE]
-> Please note that this parameter is in Private Preview.
+> Please note that this parameter is in Public Preview.
 
 Specifies the external domains blocked from communicating with users assigned to this policy. This setting is applicable only when `CommunicationWithExternalOrgs` is configured to `BlockSpecificExternalDomains`. This setting can be modified only in custom policy. In Global (default) policy `CommunicationWithExternalOrgs` can only be set to `OrganizationDefault` and cannot be changed.
 ```yaml
@@ -192,7 +195,7 @@ Accept wildcard characters: False
 > Applicable: Lync Server 2010, Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019
 
 > [!NOTE]
-> Please note that this parameter is in Private Preview.
+> Please note that this parameter is in Public Preview.
 
 Indicates how the users get assigned by this policy can communicate with the external orgs. There are 5 options:
 

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

@@ -108,46 +108,55 @@ When this command completes, the blocked domain list will be cleared.
 
 ### Example 6
 ```
+Set-CsTenantFederationConfiguration -AllowedDomains $Null
+```
+
+Example 6 shows how you can remove all the domains assigned to the allowed domains list for the current tenant, thereby blocking external communication for all users in the Tenant. In case `AllowFederatedUsers` is set to `True`, then explicit `ExternalAccessPolicy` instances can be leveraged to set a per-user federation setting.
+To do this, simply include the AllowedDomains parameter and set the parameter value to null ($Null).
+When this command completes, the allowed domain list will be cleared.
+
+### Example 7
+```
 $list = New-Object Collections.Generic.List[String]
 $list.add("contoso.com")
 $list.add("fabrikam.com")
 Set-CsTenantFederationConfiguration -AllowedDomainsAsAList $list
 ```
 
-Example 6 shows how you can replace domains in the Allowed Domains using a List collection object.
+Example 7 shows how you can replace domains in the Allowed Domains using a List collection object.
 First, a List collection is created and domains are added to it, then, simply include the AllowedDomainsAsAList parameter and set the parameter value to the List object.
 When this command completes, the allowed domains list will be replaced with those domains.
 
-### Example 7
+### Example 8
 ```
 $list = New-Object Collections.Generic.List[String]
 $list.add("contoso.com")
 $list.add("fabrikam.com")
 Set-CsTenantFederationConfiguration -AllowedDomainsAsAList @{Add=$list}
 ```
 
-Example 7 shows how you can add domains to the existing Allowed Domains using a List object.
+Example 8 shows how you can add domains to the existing Allowed Domains using a List object.
 First, a List is created and domains are added to it, then use the Add method in the AllowedDomainsAsAList 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 AllowedDomains list.
 
-### Example 8
+### Example 9
 ```
 $list = New-Object Collections.Generic.List[String]
 $list.add("contoso.com")
 $list.add("fabrikam.com")
 Set-CsTenantFederationConfiguration -AllowedDomainsAsAList @{Remove=$list}
 ```
 
-Example 8 shows how you can remove domains from the existing Allowed Domains using a List object.
+Example 9 shows how you can remove domains from the existing Allowed Domains using a List object.
 First, a List is created and domains are added to it, then use the Remove method in the AllowedDomainsAsAList 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 AllowedDomains list.
 
-### Example 9
+### Example 10
 ```
 Set-CsTenantFederationConfiguration -AllowTeamsConsumer $True -AllowTeamsConsumerInbound $False
 ```
 
-The command shown in Example 9 enables communication with people using Teams with an account that's not managed by an organization, to only be initiated by people in your organization. This means that people using Teams with an account that's not managed by an organization will not be able to discover or start a conversation with people in your organization.
+The command shown in Example 10 enables communication with people using Teams with an account that's not managed by an organization, to only be initiated by people in your organization. This means that people using Teams with an account that's not managed by an organization will not be able to discover or start a conversation with people in your organization.
 
-### Example 10
+### Example 11
 ```
 $list = New-Object Collections.Generic.List[String]
 $list.add("contoso.com")
@@ -157,20 +166,20 @@ Set-CsTenantFederationConfiguration -BlockedDomains $list
 Set-CsTenantFederationConfiguration -BlockAllSubdomains $True
 ```
 
-Example 10 shows how you can block all subdomains of domains in BlockedDomains list.
+Example 11 shows how you can block all subdomains of domains in BlockedDomains list.
 In this example, all users from contoso.com and fabrikam.com will be blocked.
 When the BlockAllSubdomains is enabled, all users from all subdomains of all domains in BlockedDomains list will also be blocked.
 So, users from subdomain.contoso.com and subdomain.fabrikam.com will be blocked.
 Note: Users from subcontoso.com will not be blocked because it's a completely different domain rather than a subdomain of contoso.com.
 
-### Example 11
+### Example 12
 ```
 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 shows how you can allow users to communicate with users in tenants that contain only trial licenses (default value is Blocked).
 
-### Example 12
+### Example 13
 ```
 $list = New-Object Collections.Generic.List[String]
 $list.add("contoso.com")
@@ -179,44 +188,44 @@ $list.add("fabrikam.com")
 Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains $list
 ```
 
-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.
+Using the `AllowedTrialTenantDomains` parameter, you can whitelist specific "trial-only" tenant domains, while keeping the `ExternalAccessWithTrialTenants` set to `Blocked`. Example 13 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
+### Example 14
 ```
 Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains @("contoso.com", "fabrikam.com")
 ```
 
-Example 13 shows another way to set a value of `AllowedTrialTenantDomains`. It uses array of objects and it always replaces value of the `AllowedTrialTenantDomains`. When this command completes, the result is the same as in example 12.
+Example 14 shows another way to set a value of `AllowedTrialTenantDomains`. It uses array of objects and it always replaces value of the `AllowedTrialTenantDomains`. When this command completes, the result is the same as in example 13.
 
 The array of `AllowedTrialTenantDomains` can be emptied by running the following command: `Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains @()`.
 
-### Example 14
+### Example 15
 ```
 $list = New-Object Collections.Generic.List[String]
 $list.add("contoso.com")
 
 Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains @{Add=$list}
 ```
 
-Example 14 shows how you can add domains to the existing Allowed Trial Tenant Domains using a List collection object.
+Example 15 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 15
+### Example 16
 ```
 $list = New-Object Collections.Generic.List[String]
 $list.add("contoso.com")
 
 Set-CsTenantFederationConfiguration -AllowedTrialTenantDomains @{Remove=$list}
 ```
 
-Example 15 shows how you can remove domains from the existing Allowed Trial Tenant Domains using a List collection object.
+Example 16 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 16
+### Example 17
 ```
 Set-CsTenantFederationConfiguration -DomainBlockingForMDOAdminsInTeams "Enabled"
 ```
@@ -234,7 +243,10 @@ If the `New-CsEdgeAllowList` cmdlet is used then users can only communicate with
 Note that string values cannot be passed directly to the AllowedDomains parameter.
 Instead, you must create an object reference using the `New-CsEdgeAllowList` cmdlet or the `New-CsEdgeAllowAllKnownDomains` cmdlet and then use the object reference variable as the parameter value.
 
-The AllowedDomains parameter can support up to 4,000 domains.
+The AllowedDomains parameter can support up to 4,000 domains. 
+
+> [!IMPORTANT]
+> The `AllowFederatedUsers` property must be set to `True` for the `AllowedDomains` list to take effect. If `AllowFederatedUsers` is set to `False`, users will be blocked from communicating with all external domains regardless of the values in `AllowedDomains` or any `ExternalAccessPolicy` instance.
 
 ```yaml
 Type: Boolean
@@ -294,7 +306,9 @@ Accept wildcard characters: False
 > Applicable: Microsoft Teams
 
 When set to True (the default value) users will be potentially allowed to communicate with users from other domains.
-If this property is set to False then users cannot communicate with users from other domains regardless of the values assigned to the AllowedDomains and BlockedDomains properties.
+If this property is set to False then users cannot communicate with users from other domains, regardless of the values assigned to the `AllowedDomains` and `BlockedDomains` properties or any `ExternalAccessPolicy` instances. In effect, the `AllowFederatedUsers` property serves as a master switch that globally enables or disables federation across the Tenant, overridding all other policy settings. 
+
+To block all domains while selectively allowing specific users to communicate externally via explicit `ExternalAccessPolicy` instances, set `AllowFederatedUsers` to `True` and leave the `AllowedDomains` property empty.
 
 ```yaml
 Type: Boolean
@@ -365,8 +379,12 @@ Accept wildcard characters: False
 
 If the AllowedDomains property has been set to AllowAllKnownDomains, then users will be allowed to communicate with users from any domain except domains that appear in the blocked domains list.
 If the AllowedDomains property has not been set to AllowAllKnownDomains, then the blocked list is ignored, and users can only communicate with domains that have been expressly added to the allowed domains list.
+
 The BlockedDomains parameter can support up to 4,000 domains.
 
+> [!IMPORTANT]
+> The `AllowFederatedUsers` property must be set to `True` for the `AllowedDomains` list to take effect. If `AllowFederatedUsers` is set to `False`, users will be blocked from communicating with all external domains regardless of the values in `AllowedDomains` or any `ExternalAccessPolicy` instance.
+
 ```yaml
 Type: List
 Parameter Sets: (All)