Assigns a client PIN authentication policy to a user or group of users. PIN authentication provides a way for users to access Microsoft Communications Server 2010 using a telephone that does not have an alphanumeric keyboard and thus cannot be used to enter the user name and password. The client PIN policies enable you to control such settings as the minimum PIN length and the PIN lifetime (that is, the number of days a PIN can be used before it must be reset).
Syntax
Grant-CsPinPolicy -Identity <UserIdParameter> [-PolicyName <String>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-PassThru <SwitchParameter>] [-WhatIf [<SwitchParameter>]] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Required |
UserIDParameter |
Indicates the Identity of the user account to be assigned the per-user PIN policy. User Identities can be specified using one of four formats: 1) the user's SIP address; 2) the user's Universal Principal Name; 3) the user's domain name and logon name, in the form domain\logon (e.g., litwareinc\kenmyer); and, 4_ the user's Active Directory display name (for example, Ken Myer). Note that the SamAccountName cannot be used as an identity; that's because SamAccountNames are not necessarily unique in a forest. In addition, you can use the asterisk (*) wildcard character when using the Display Name as the user Identity. For example, the Identity "* Smith" returns all the users who have a display name that ends with the string value " Smith". |
|
PolicyName |
Optional |
String |
"Name" of the policy to be assigned. The PolicyName is simply the policy Identity minus the policy scope (which is displayed as the prefix tag: when you call Get-CsPinPolicy). For example, a policy with the Identity tag:Redmond has a PolicyName equal to Redmond; a policy with the Identity tag:RedmondUsersPinPolicy has a PolicyName equal to RedmondUsersPinPolicy. To assign the global policy to a user, set the -PolicyName to a null value ($Null). |
|
DomainController |
Optional |
String |
Enables you to specify the fully qualified domain name of a domain controller to be contacted when assigning the new policy. If this parameter is not specified then Grant-CsPinPolicy 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-CsPinPolicy 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. |
Detailed Description
Communications Server 2010 enables users to connect to the system, or to join PSTN (Public Switched Telephone Network) conferences via telephone. Typically, logging on to the system or joining a conference requires the user to enter a user name or password; unfortunately, entering a user name and password can be a problem if you are using a phone that does not have an alphanumeric keypad. Because of that, Communications Server enables you to supply users with numeric-only PIN numbers; when prompted, users can then log on to the system or join a conference by entering the PIN number instead of a user name and password.
Communications Server uses PIN policies to manage PIN authentication properties; for example, you can specify the minimum length for a PIN number as well as determine whether you will allow PINs that use "common patterns" such as repeating digits (for example, a PIN number like 11223344). Pin policies can be configured at the global or the site scope; in addition, pin policies can be configured at the per-user scope and then assigned to a user or a specified set of users. In order to assign a per-user policy (for example, a policy with the Identity RedmondUsersPinPolicy) you must use the Grant-CsPinPolicy cmdlet. This cmdlet is used only for assigning per-user policies; site policies are automatically assigned to the specified site at the time they are created.
Return Types
Grant-CsClientPin does not return a value or object. Instead, the cmdlet configures instances of the Microsoft.Rtc.Management.UserPinService.PinInfoDetails object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
Grant-CsPinPolicy -Identity "kenmyer@litwareinc.com" -PolicyName RedmondUsersPinPolicy |
|
The command shown in Example 1 assigns the policy RedmondUsersPinPolicy to the user kenmyer@litwareinc.com.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
Grant-CsPinPolicy -Identity kenmyer@litwareinc.com -PolicyName $Null |
|
Example 2 assigns the global client PIN policy to the user kenmyer@litwareinc.com. Calling Grant-CsPinPolicy and setting the policy name to a null value ($Null) removes any per-user policy assigned to the user. In turn, that means the user's PIN number will be governed by the site policy or, if a site policy does not exist, by the global policy.
-------------------------- Example 3 ------------------------
| Copy Code |
|
|---|---|
Get-CsUser -LDAPFilter "l=Redmond" | Grant-CsPinPolicy -PolicyName RedmondUsersPinPolicy |
|
In Example 3, the policy RedmondUsersPinPolicy is assigned to all the users who work in the city of Redmond. To do this, the Get-CsUser cmdlet first retrieves a collection of all the users who work in Redmond; this task is accomplished by including the -LDAPFilter parameter and using the filter value "l=Redmond". (With LDAP filters, "l" represents the user's locality; that is, the city the user works in.) That collection of users is then piped to Grant-CsPinPolicy, which assigns each user the policy RedmondUsersPinPolicy.
-------------------------- Example 4 ------------------------
| Copy Code |
|
|---|---|
Get-CsUser -Filter {ClientPinPolicy -eq $Null} | Grant-CsPinPolicy -PolicyName RedmondUsersPinPolicy
|
|
In the preceding command, the policy RedmondUsersPinPolicy is assigned to all the users who have not been assigned a per-user PIN policy. To determine which users have not been assigned a PIN policy, the Get-CsUser cmdlet is called, along with the -Filter parameter. The Filter value {ClientPinPolicy -eq $Null} returns only those users where the ClientPinPolicy property is null (that is, no per-user PIN policy has been assigned). That collection of users is then piped to Grant-CsPinPolicy, which assigns RedmondUsersPinPolicy to each person in the collection.