New-CsExternalAccessPolicy
Enables you to create a new external access policy.
External access policies determine whether or not your users can: 1) communicate with users who have Session Initiation Protocol (SIP) accounts with a federated organization; 2) communicate with users who are using custom applications built with Azure Communication Services; 3) access Skype for Business Server over the Internet, without having to log on to your internal network; 4) communicate with users who have SIP accounts with a public instant messaging (IM) provider such as Skype; and, 5) communicate with people who are using Teams with an account that's not managed by an organization.
This cmdlet was introduced in Lync Server 2010.
For information about external access in Microsoft Teams, see Manage external access in Microsoft Teams and Teams and Skype interoperability for specific details.
Syntax
New-CsExternalAccessPolicy
[-Identity] <XdsIdentity>
[-AllowedExternalDomains <List>]
[-BlockedExternalDomains <List>]
[-CommunicationWithExternalOrgs <Boolean>]
[-Confirm]
[-Description <String>]
[-EnableAcsFederationAccess <Boolean>]
[-EnableFederationAccess <Boolean>]
[-EnableOutsideAccess <Boolean>]
[-EnablePublicCloudAccess <Boolean>]
[-EnablePublicCloudAudioVideoAccess <Boolean>]
[-EnableTeamsConsumerAccess <Boolean>]
[-EnableTeamsConsumerInbound <Boolean>]
[-EnableXmppAccess <Boolean>]
[-FederatedBilateralChats <Boolean>]
[-Force]
[-InMemory]
[-Tenant <Guid>]
[-WhatIf]
[<CommonParameters>] Description
When you install Skype for Business Server your users are only allowed to exchange instant messages and presence information among themselves: by default, they can only communicate with other people who have SIP accounts in your Active Directory Domain Services. In addition, users are not allowed to access Skype for Business Server over the Internet; instead, they must be logged on to your internal network before they will be able to log on to Skype for Business Server.
That might be sufficient to meet your communication needs. If it doesn't meet your needs you can use external access policies to extend the ability of your users to communicate and collaborate. External access policies can grant (or revoke) the ability of your users to do any or all of the following:
Communicate with people who have SIP accounts with a federated organization. Note that enabling federation alone will not provide users with this capability. Instead, you must enable federation and then assign users an external access policy that gives them the right to communicate with federated users.
(Microsoft Teams only) Communicate with users who are using custom applications built with Azure Communication Services (ACS). This policy setting only applies if ACS federation has been enabled at the tenant level using the cmdlet Set-CsTeamsAcsFederationConfiguration.
Access Skype for Business Server over the Internet, without having to first log on to your internal network. This enables your users to use Skype for Business and log on to Skype for Business Server from an Internet café or other remote location.
Communicate with people who have SIP accounts with a public instant messaging service such as Skype.
(Microsoft Teams Only) Communicate with people who are using Teams with an account that's not managed by an organization. This policy only applies if Teams Consumer Federation has been enabled at the tenant level using the cmdlet Set-CsTenantFederationConfiguration or Teams Admin Center under the External Access setting.
When you install Skype for Business Server, a global external access policy is automatically created for you. In addition to the global policy, you can also create custom external access policies at either the site or the per-user scope. If you create an external access policy at the site scope, that policy will automatically be assigned to the site upon creation. If you create an external access policy at the per-user scope, that policy will be created but will not be assigned to any users. To assign the policy to a user or group of users, use the Grant-CsExternalAccessPolicy cmdlet.
New external access policies can be created by using the New-CsExternalAccessPolicy cmdlet. Note that these policies can only be created at the site or the per-user scope; you cannot create a new policy at the global scope. In addition, you can have only one external access policy per site: if the Redmond site already has been assigned an external access policy you cannot create a second policy for the site.
The following parameters are not applicable to Skype for Business Online/Microsoft Teams: Description, EnableXmppAccess, Force, Identity, InMemory, PipelineVariable, and Tenant
Examples
-------------------------- EXAMPLE 1 --------------------------
New-CsExternalAccessPolicy -Identity site:Redmond -EnableFederationAccess $True -EnableOutsideAccess $TrueThe command shown in Example 1 creates a new external access policy that has the Identity site:Redmond; upon creation, this policy will automatically be assigned to the Redmond site. Note that this new policy sets both the EnableFederationAccess and the EnableOutsideAccess properties to True.
-------------------------- Example 2 ------------------------
Set-CsExternalAccessPolicy -Identity Global -EnableAcsFederationAccess $true
New-CsExternalAccessPolicy -Identity AcsFederationNotAllowed -EnableAcsFederationAccess $falseIn this example, the Global policy is updated to allow Teams-ACS federation for all users, then a new external access policy instance is created with Teams-ACS federation disabled and which can then be assigned to selected users for which Team-ACS federation will not be allowed.
-------------------------- Example 3 ------------------------
New-CsExternalAccessPolicy -Identity site:Redmond -EnableTeamsConsumerAccess $True -EnableTeamsConsumerInbound $FalseThe command shown in Example 3 creates a new external access policy that has the Identity site:Redmond; upon creation, this policy will automatically be assigned to the Redmond site. Note that this new policy enables communication with people using Teams with an account that's not managed by an organization and limits this 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 with this policy assigned.
-------------------------- EXAMPLE 4 --------------------------
$x = New-CsExternalAccessPolicy -Identity RedmondAccessPolicy -InMemory
$x.EnableFederationAccess = $True
$x.EnablePublicCloudAccess = $True
$x.EnableOutsideAccess = $True
Set-CsExternalAccessPolicy -Instance $xExample 4 demonstrates the use of the InMemory parameter; this parameter enables you to create an in-memory-only instance of an external access policy. After it has been created, you can modify the in-memory-only instance, then use the Set-CsExternalAccessPolicy cmdlet to transform the virtual policy into a real external access policy.
To do this, the first command in the example uses the New-CsExternalAccessPolicy cmdlet and the InMemory parameter to create a virtual policy with the Identity RedmondAccessPolicy; this virtual policy is stored in a variable named $x. The next three commands are used to modify three properties of the virtual policy: EnableFederationAccess, EnablePublicCloudAccess, and the EnableOutsideAccess. Finally, the last command uses the Set-CsExternalAccessPolicy cmdlet to create an actual per-user external access policy with the Identity RedmondAccessPolicy. If you do not call the Set-CsExternalAccessPolicy cmdlet, then the virtual policy will disappear as soon as you end your Windows PowerShell session or delete the variable $x. Should that happen, an external access policy with the Identity RedmondAccessPolicy will never be created.
-------------------------- Example 5 ------------------------
New-CsExternalAccessPolicy -Identity GranularFederationExample -CommunicationWithExternalOrgs "AllowSpecificExternalDomains" -AllowedExternalDomains @("example1.com", "example2.com")
Set-CsTenantFederationConfiguration -CustomizeFederation $trueIn this example, we create an ExternalAccessPolicy named "GranularFederationExample" that allows communication with specific external domains, namely example1.com and example2.com. The federation policy is set to restrict communication to only these allowed domains. After that, we still have to enable the CustomizeFederation setting in the TenantFederationConfiguration to allow the federation settings as defined in the ExternalAccessPolicy to work.
Parameters
-AllowedExternalDomains
Indicates the domains that are allowed to communicate with the users of this policy. This is referenced only when CommunicationWithExternalOrgs is set to be AllowSpecificExternalDomains.
| Type: | List |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2010, Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-BlockedExternalDomains
Indicates the domains that are blocked from communicating with the users of this policy. This is referenced only when CommunicationWithExternalOrgs is set to be BlockSpecificExternalDomains.
| Type: | List |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2010, Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-CommunicationWithExternalOrgs
Indicates how the users get assigned by this policy can communicate with the external orgs. There are 5 options:
- OrganizationDefault: the users of this policy will follow the federation settings defined in TenantFederationConfiguration
- AllowAllExternalDomains: the users are open to communicate with all domains
- AllowSpecificExternalDomains: the users can only communicate with the users of the domains defined in
AllowedExternalDomains - BlockSpecificExternalDomains: only users from the domains defined in
BlockedExternalDomainsare blocked from communicating with the users of this policy - BlockAllExternalDomains: the users are not able to communicate with any external domains
| Type: | String |
| Position: | Named |
| Default value: | OrganizationDefault |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2010, Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-Confirm
Prompts you for confirmation before executing the command.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Description
Enables administrators to provide explanatory text to accompany the policy. For example, the Description might include information about the users the policy should be assigned to.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnableAcsFederationAccess
Indicates whether Teams meetings organized by the user can be joined by users of customer applications built using Azure Communication Services (ACS). This policy setting only applies if ACS Teams federation has been enabled at the tenant level using the cmdlet Set-CsTeamsAcsFederationConfiguration. Additionally, Azure Communication Services users would be able to call Microsoft 365 users that have assigned policies with enabled federation.
To enable for all users, use the Set-CsExternalAccessPolicy cmdlet to update the global policy, setting the value to True. It can be disabled for selected users by assigning them a policy with federation disabled.
To enable just for a selected set of users, use the Set-CsExternalAccessPolicy cmdlet to update the global policy, setting the value to False. Then assign selected users a policy with federation enabled.
| Type: | Boolean |
| Position: | Named |
| Default value: | True |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Microsoft Teams |
-EnableFederationAccess
Indicates whether the user is allowed to communicate with people who have SIP accounts with a federated organization. Read Manage external access in Microsoft Teams to get more information about the effect of this parameter in Microsoft Teams. The default value is True.
| Type: | Boolean |
| Position: | Named |
| Default value: | True |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnableOutsideAccess
Indicates whether the user is allowed to connect to Skype for Business Server over the Internet, without logging on to the organization's internal network. The default value is False.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnablePublicCloudAccess
Indicates whether the user is allowed to communicate with people who have SIP accounts with a public Internet connectivity provider such as MSN. Read Manage external access in Microsoft Teams to get more information about the effect of this parameter in Microsoft Teams. The default value is False.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnablePublicCloudAudioVideoAccess
Indicates whether the user is allowed to conduct audio/video conversations with people who have SIP accounts with a public Internet connectivity provider such as MSN. When set to False, audio and video options in Skype for Business Server will be disabled any time a user is communicating with a public Internet connectivity contact.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnableTeamsConsumerAccess
(Microsoft Teams Only) Indicates whether the user is allowed to communicate with people who have who are using Teams with an account that's not managed by an organization.
To enable just for a selected set of users, use the Set-CsExternalAccessPolicy cmdlet to update the global policy, setting the value to False. Then assign selected users a policy with federation enabled.
Read Manage external access in Microsoft Teams to get more information about the effect of this parameter in Microsoft Teams. The default value is True.
| Type: | Boolean |
| Position: | Named |
| Default value: | True |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnableTeamsConsumerInbound
(Microsoft Teams Only) Indicates whether the user is allowed to be discoverable by people who are using Teams with an account that's not managed by an organization. It also controls if people who have who are using Teams with an account that's not managed by an organization can start the communication with the user.
To enable just for a selected set of users, use the Set-CsExternalAccessPolicy cmdlet to update the global policy, setting the value to False. Then assign selected users a policy with federation enabled.
Read Manage external access in Microsoft Teams to get more information about the effect of this parameter in Microsoft Teams. The default value is True.
| Type: | Boolean |
| Position: | Named |
| Default value: | True |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnableXmppAccess
Indicates whether the user is allowed to communicate with users who have SIP accounts with a federated XMPP (Extensible Messaging and Presence Protocol) partner. The default value is False.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FederatedBilateralChats
This setting enables bi-lateral chats for the users included in the messaging policy.
| Type: | Boolean |
| Position: | Named |
| Default value: | True |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Force
Suppresses the display of any non-fatal error message that might occur when running the command.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Identity
Unique Identity to be assigned to the policy. New external access policies can be created at the site or per-user scope.
To create a new site policy, use the prefix "site:" and the name of the site as your Identity.
For example, use this syntax to create a new policy for the Redmond site: -Identity site:Redmond.
To create a new per-user policy, use an Identity similar to this: -Identity SalesAccessPolicy.
Note that you cannot create a new global policy; if you want to make changes to the global policy, use the Set-CsExternalAccessPolicy cmdlet instead.
Likewise, you cannot create a new site or per-user policy if a policy with that Identity already exists. If you need to make changes to an existing policy, use the Set-CsExternalAccessPolicy cmdlet.
| Type: | XdsIdentity |
| Position: | 2 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InMemory
Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet's matching Set-<cmdlet>.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Tenant
Globally unique identifier (GUID) of the Skype for Business Online tenant account for whom the new external access policy is being created. For example:
-Tenant "38aad667-af54-4397-aaa7-e94c79ec2308"
You can return the tenant ID for each of your Skype for Business Online tenants by running this command:
Get-CsTenant | Select-Object DisplayName, TenantID
| Type: | Guid |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
Describes what would happen if you executed the command without actually executing the command.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
None. The New-CsExternalAccessPolicy cmdlet does not accept pipelined input.
Outputs
Creates new instances of the Microsoft.Rtc.Management.WritableConfig.Policy.ExternalAccess.ExternalAccessPolicy object.
System.Object