Export (0) Print
Expand All
Expand Minimize

Grant-CsExternalAccessPolicy

 

Topic Last Modified: 2012-03-23

Enables you to assign an external access policy to a user or a group of users. 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 have SIP accounts with a public instant messaging (IM) provider such as MSN; and, 3) access Microsoft Lync Server 2010 over the Internet, without having to log on to your internal network.

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

When you install Lync 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 Domain Services (AD DS). In addition, users are not allowed to access Lync Server over the Internet; instead, they must be logged on to your internal network before they will be able to log on to Lync 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:

1. Communicate with people who have SIP accounts with a federated organization. Note that enabling federation will not automatically 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.

2. Communicate with people who have SIP accounts with a public instant messaging service such as MSN.

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

When you install Lync Server, a global external access policy is automatically created for you. 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, it 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. 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.

Who can run this cmdlet: By default, members of the following groups are authorized to run the Grant-CsExternalAccessPolicy cmdlet locally: RTCUniversalUserAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:

Get-CsAdminRole | Where-Object {$_.Cmdlets –match "Grant-CsExternalAccessPolicy"}

 

Parameter Required Type Description

Identity

Required

XdsIdentity

Identity of the user account the policy should be assigned to. User Identities can be specified by using one of four formats: 1) the user's SIP address; 2) the user's user principal name (UPN); 3) the user's domain name and logon name, in the form domain\logon (for example, litwareinc\kenmyer); and, 4) the user's Active Directory display name (for example, Ken Myer). User Identities can also be referenced by using the user’s Active Directory distinguished name.

In addition, you can use the asterisk (*) wildcard character when specifying the user Identity. For example, the Identity "* Smith" returns all the users with a display name that ends with the string value " Smith."

PolicyName

Required

String

"Name" of the policy to be assigned. The PolicyName is simply the policy Identity minus the policy scope (the "tag:" prefix). For example, a policy with the Identity tag:Redmond has a PolicyName equal to Redmond; a policy with the Identity tag:RedmondAccessPolicy has a PolicyName equal to RedmondAccessPolicy.

To unassign a per-user policy previously assigned to a user, set the PolicyName parameter to $Null.

DomainController

Optional

String

Enables you to specify the fully qualified domain name (FQDN) of a domain controller to be contacted when assigning the new policy. If this parameter is not specified, then Grant-CsExternalAccessPolicy will contact the first available domain controller.

PassThru

Optional

Switch Parameter

Enables you to pass a user object through the pipeline that represents the user being assigned the policy. By default, the Grant-CsExternalAccessPolicy cmdlet does not pass objects through the pipeline.

WhatIf

Optional

Switch Parameter

Describes what would happen if you executed the command without actually executing the command.

Confirm

Optional

Switch Parameter

Prompts you for confirmation before executing the command.

String value or Microsoft.Rtc.Management.ADConnect.Schema.ADUser object. Grant-CsExternalAccessPolicy accepts pipelined input of string values representing the Identity of a user account. The cmdlet also accepts pipelined input of user objects.

By default, Grant-CsExternalAccessPolicy does not return a value or object. However, if you include the PassThru parameter, the cmdlet will return instances of the Microsoft.Rtc.Management.ADConnect.Schema.OCSUserOrAppContact object.

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

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 ------------------------

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 of Redmond (the l in the filter, a lowercase L, represents the locality). That collection is then piped to Grant-CsExternalAccessPolicy, which assigns the policy RedmondAccessPolicy to each user in the collection.

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

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 ------------------------

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 ------------------------

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 (OU). 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. The returned collection is then piped to Grant-CsExternalAccessPolicy, which assigns the policy USAccessPolicy to each user in the collection.

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

Get-CsUser | Grant-CsExternalAccessPolicy -PolicyName $Null

Example 6 unassigns any per-user external access policy previously assigned to any of the users enabled for Lync Server. To do this, the command calls Get-CsUser (without any additional parameters) in order to return a collection of all the users enabled for Lync Server. 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.

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft