[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Modifies one or more existing client PIN policies. 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. 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


Set-CsPinPolicy [-Identity <XdsIdentity>] [-AllowCommonPatterns <$true \| $false>] [-Confirm [<SwitchParameter>]] [-Description <String>] [-Force <SwitchParameter>] [-MaximumLogonAttempts <Nullable>] [-MinPasswordLength <UInt32>] [-PINHistoryCount <UInt64>] [-PINLifetime <UInt64>] [-WhatIf [<SwitchParameter>]]

Set-CsPinPolicy [-Identity <XdsIdentity>] [-AllowCommonPatterns <$true | $false>] [-Confirm [<SwitchParameter>]] [-Description <String>] [-Force <SwitchParameter>] [-MaximumLogonAttempts <Nullable>] [-MinPasswordLength <UInt32>] [-PINHistoryCount <UInt64>] [-PINLifetime <UInt64>] [-WhatIf [<SwitchParameter>]]


Set-CsPinPolicy [-AllowCommonPatterns <$true \| $false>] [-Confirm [<SwitchParameter>]] [-Description <String>] [-Force <SwitchParameter>] [-Instance <PSObject>] [-MaximumLogonAttempts <Nullable>] [-MinPasswordLength <UInt32>] [-PINHistoryCount <UInt64>] [-PINLifetime <UInt64>] [-WhatIf [<SwitchParameter>]]

Set-CsPinPolicy [-AllowCommonPatterns <$true | $false>] [-Confirm [<SwitchParameter>]] [-Description <String>] [-Force <SwitchParameter>] [-Instance <PSObject>] [-MaximumLogonAttempts <Nullable>] [-MinPasswordLength <UInt32>] [-PINHistoryCount <UInt64>] [-PINLifetime <UInt64>] [-WhatIf [<SwitchParameter>]]

Parameters

Parameter	Required	Type	Description
Identity	Required	XdsIdentity	Unique Identity assigned to the policy when it was created. PIN policies can be assigned at the global, site, or per-user scope. To refer to the global instance use this syntax: -Identity global. To refer to a policy at the site scope use syntax similar to this: -Identity site:Redmond. To refer to a per-user policy use syntax similar to this: RedmondPinPolicy. If you do not specify an Identity then Set-CsPinPolicy will modify the global policy. Set-CsPinPolicy will not prompt you to enter an Identity.
Instance	Required	UserPinPolicy object	Allows you to pass a reference to an object to the cmdlet rather than set individual parameter values.
MinPasswordLength	Optional	Integer	The minimum allowed length (that is, the minimum number of digits) in a PIN number. For example, if MinPasswordLength is set to 8 then a PIN number of 1259 will be rejected because that PIN only has 4 digits. PIN lengths must have at least 6 digits but no more than 24 digits; the default value is 8.
PINHistoryCount	Optional	Integer	Indicates how often users are allowed to reuse the same PIN number. For example, if the PINHistoryCount is set to 3, then the first three times users reset their PINs they must use a new PIN number; on the fourth reset, they can reuse their first PIN number. (And, on the fifth reset, they can use their second PIN number, and so on.) The PIN history count can be any whole number between 0 and 20, inclusive; 0 means that users can use the same PIN number over and over again. By default, PINHistoryCount is set to 5.
AllowCommonPatterns	Optional	Boolean	Indicates whether or not "common patterns" are allowed in PIN numbers. Common patterns include repeating digits (225577); 4 or more consecutive digits (991234); and PINs that match a user's phone number or extension number. If set to True ($True) common patterns (such as the PIN 1933456, which includes repeating digits) are allowed; if set to False ($False) common patterns are not allowed. The default value is False.
PINLifetime	Optional	Integer	Indicates the length of time (in days) that a PIN remains valid; after the PIN lifetime expires users must select a new PIN number before they will be allowed to use PIN authentication to gain access to the system. PINLifetime can be set to any whole number between 0 and 999, inclusive; 0 indicates that PIN numbers never expire. By default, the PIN lifetime is set to 60 days.
MaximumLogonAttempts	Optional	Integer	Indicates the number of sequential logon failures that are allowed before a user's PIN number is automatically locked. For example, if MaximumLogonAttempts is set to 3 and a user tries, and fails, 4 times in a row to log on, then the user's PIN will be locked and he or she will not be able to access the system until an administrator has unlocked the PIN. Note that this property refers to consecutive logon attempts. After each successful logon, a user's logon attempts count is reset to 0. MaximumLogonAttempts can be set to any whole number between 1 and 999 inclusive. The default value is 15.
Description	Optional	String	Enables administrators to provide explanatory test to accompany a PIN policy. For example, the Description might include information about the users the policy should be assigned to.
Force	Optional	Switch Parameter	Suppresses the display of any non-fatal error message that might arise when running the command.
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 2010 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 2010 client PIN policies to manage PIN authentication properties; for example, you can specify the minimum length for a PIN number as well as determine whether to you will allow PINs that use "common patterns" such as repeating digits (for example, a PIN number like 11223344). You can use the Get-CsPinPolicy cmdlet to retrieve information about the PIN policies currently configured for use in your organization. In addition, you can use Set-CsPinPolicy to modify the property values for any of these PIN policies.

Return Types

Set-CsPinPolicy does not return a value or object. Instead, the cmdlet configures one or more instances of the Microsoft.Rtc.Management.WriteableConfig.Policy.UserPin.UserPolicy object.

Examples

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

	Copy Code
Set-CsPinPolicy -Identity site:Redmond -MinPasswordLength 10

Example 1 modifies the client policy assigned to the Redmond site; if no such policy exists then this command will fail. In this case, the command changes the value of the MinPasswordLength property to 10; that means that new PIN numbers must contain at least 10 digits.

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

	Copy Code
Set-CsPinPolicy -Identity RedmondUsersPinPolicy -MinPasswordLength 10 -AllowCommonPatterns $True

Example 2 modifies two properties of the PIN policy with the Identity RedmondUsersPinPolicy: it changes the value of the MinPasswordLength and the AllowCommonPatterns properties.

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

	Copy Code
Get-CsPinPolicy \| Set-CsPinPolicy -MinPasswordLength 10

The command shown in Example 3 changes the value of the MinPasswordLength for all the PIN policies configured for use in the organization. To do this, the command first uses the Get-CsPinPolicy cmdlet to retrieve a collection of all the existing PIN policies. That entire collection is then piped to Set-CsPinPolicy, which modifies the value of the MinPasswordLength property for each policy in the collection.

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

	Copy Code
Get-CsPinPolicy \| Where-Object {$_.MinPasswordLength -gt 10} \| Set-CsPinPolicy -MaximumLogonAttempts 25

Example 4 uses three different cmdlets in order to change the value of the MaximumLogonAttempts property, but only for cmdlets where the MinPasswordLength property is greater than 10. To do this, Get-CsPinPolicy is first used to retrieve a collection of all the PIN policies configured for use in the organization. That collection is then piped to the Where-Object cmdlet; in turn, Where-Object selects only those policies where the MinPasswordLength property is greater than (-gt) 10. The filtered set of policies is then passed to Set-CsPinPolicy, which takes each policy in the collection and changes the value of the MaximumLogonAttempts property to 25.