Grant-CsExternalAccessPolicy -Identity <UserIdParameter> [-PolicyName <String>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-PassThru <SwitchParameter>] [-WhatIf [<SwitchParameter>]]

Parameters

When you install Communications Server 2010 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. In addition, users are not allowed to access Communications Server over the Internet; instead, they must be logged on to your internal network before they will be able to log on to Communications 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.

Communicate with people who have SIP accounts with a public instant messaging service such as AOL or Yahoo!.

Access Communications Server over the Internet, without having to first log on to your internal network. This enables your users to use Microsoft Communicator "14" and log on to Communications Server from an Internet café or other remote location.

When you install Communications Server a global external access policy is automatically created for you. (Because this is a global policy, that also means that all of your users, by default, have their external access capabilities managed by this policy.) In addition to this global policy, you can use New-CsExternalAccessPolicy to create additional external access policies configured at either the site or the per-user scope.

When a policy is created at the site scope that policy is automatically assigned to the site in question; for example, an external access policy with the Identity site:Redmond will automatically be assigned to the Redmond site. By contrast, policies created at the per-user scope are not automatically assigned to anyone. Instead, these policies must be explicitly assigned to a user (or a group of users) in order to be implemented. Assigning per-user policies is the job of the Grant-CsExternalAccessPolicy cmdlet.

Note that per-user policies always take precedent over site policies and the global policy. For example suppose you create a per-user policy that allows communication with federated users, and you assign that policy to Ken Myer. As long as that policy is in force, Ken will be allowed to communicate with federated users, even if this type of communication is not allowed by Ken’s site policy or by the global policy. That’s because the settings in the per-user policy take precedence.

Grant-CsExternalAccessPolicy does not return a value or object. Instead, the cmdlet assigns instances of the Microsoft.Rtc.Management.WriteableConfig.Policy.ExternalAccess.ExternalAccessPolicy object to users.

-------------------------- Example 1 ------------------------

	Copy Code
Grant-CsExternalAccessPolicy -Identity "Ken Myer" -PolicyName RedmondAccessPolicy

The preceding command assigns the external access policy RedmondAccessPolicy to the user with the Active Directory display name Ken Myer.

-------------------------- Example 2 ------------------------

	Copy Code
Get-CsUser -LDAPFilter "l=Redmond" | Grant-CsExternalAccessPolicy -PolicyName RedmondAccessPolicy

The command shown in Example 2 assigns the external access policy RedmondAccessPolicy to all the users who work in the city of Redmond. To do this, the command first uses Get-CsUser and the -LDAPFilter parameter to return a collection of all the users who work in Redmond; the filter value "l=Redmond" limits returned data to those users who work in the city (l, or locality) of Redmond. That collection is then piped to Grant-CsExternalAccessPolicy, which assigns RedmondAccessPolicy to each user in the collection.

-------------------------- Example 3 ------------------------

	Copy Code
Get-CsUser - LDAPFilter "Title=Sales Representative" | Grant-CsExternalAccessPolicy -PolicyName SalesAccessPolicy

In Example 3, all the users who have the job title "Sales Representative" are assigned the external access policy SalesAccessPolicy. To perform this task, the command first uses Get-CsUser and the -LDAPFilter parameter to return a collection of all the Sales Representatives; the filter value "Title=Sales Representative" restricts the returned collection to users who have the job title "Sales Representative". This filtered collection is then piped to Grant-CsExternalAccessPolicy, which assigns the policy SalesAccessPolicy to each user in the collection.

-------------------------- Example 4 ------------------------

	Copy Code
Get-CsUser -Filter {ExternalAccessPolicy -eq $Null} | Grant-CsExternalAccessPolicy -PolicyName BasicAccessPolicy

The command shown in Example 4 assigns the external access policy BasicAccessPolicy to all the users who have not been explicitly assigned a per-user policy. (That is, users currently being governed by a site policy or by the global policy.) To do this, Get-CsUser and the -Filter parameter are used to return the appropriate set of users; the filter value {ExternalAccessPolicy -eq $Null} limits the returned data to user accounts where the ExternalAccessPolicy property is equal to (-eq) a null value ($Null). By definition, ExternalAccessPolicy will be null only if users have not been assigned a per-user policy. This filtered collection is then piped to Grant-CsExternalAccessPolicy, which assigns the policy BasicAccessPolicy to each user in the collection.

-------------------------- Example 5 ------------------------

	Copy Code
Get-CsUser -OU "ou=US,dc=litwareinc,dc=com" | Grant-CsExternalAccessPolicy -PolicyName USAccessPolicy

The preceding command assigns the external access policy USAccessPolicy to all the users who have accounts in the US organizational unit. The command starts off by calling Get-CsUser and the -OU parameter; the parameter value "ou=US,dc=litwareinc,dc=com" limits the returned data to user accounts found in the US OU in Active Directory. The returned collection is then piped to Grant-CsExternalAccessPolicy, which assigns USAccessPolicy to each user in the collection.

-------------------------- Example 6 ------------------------

	Copy Code
Get-CsUser | Grant-CsExternalAccessPolicy -PolicyName $Null

Example 6 unassigns any per-user external access policy previously assigned to any of the Microsoft Communications Server-enabled users in Active Directory. To do this, the command calls Get-CsUser (without any additional parameters) in order to return a collection of all the Communications Server-enabled users. That collection is then piped to Grant-CsExternalAccessPolicy, which uses the syntax "-PolicyName $Null" to remove any per-user external access policy previously assigned to these users. Without an assigned per-user policy, users will have their external access permissions governed by their site policy (if such a policy exists) or by the global policy.