Creates a new client PIN authentication policy. 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
New-CsPinPolicy -Identity <XdsIdentity> [-AllowCommonPatterns <$true | $false>] [-Confirm [<SwitchParameter>]] [-Description <String>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-MaximumLogonAttempts <Nullable>] [-MinPasswordLength <UInt32>] [-PINHistoryCount <UInt64>] [-PINLifetime <UInt64>] [-WhatIf [<SwitchParameter>]] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Required |
XdsIdentity |
Indicates the unique Identity to be assigned to the policy. PIN policies can be created at the site or per-user scope. To refer to a policy at the site scope use syntax similar to this: -Identity site:Redmond. To refer to a policy at the per-user scope use syntax similar to this: -Identity RedmondPinPolicy. |
|
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. |
|
AllowCommonParameters |
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. |
|
InMemory |
Optional |
Switch Parameter |
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. |
|
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 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). You can use the New-CsPinPolicy cmdlet to create new PIN authentication policies; these new policies can be configured at either the site or the per-user scope. (There is also a global PIN policy. However, you cannot create a second global PIN policy; all you can do is modify the existing global policy.)
If you pass New-CsPinPolicy the Identity of a policy that already exists the command will fail; if you need to change the properties of an existing policy use the Set-CsPinPolicy cmdlet instead.
Return Types
Creates a new instance of the Microsoft.Rtc.Management.WriteableConfig.Policy.UserPin.UserPolicy object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
New-CsPinPolicy -Identity "site:Redmond" -MinPasswordLength 10 |
|
In Example 1, New-CsPinPolicy is used to create a new PIN policy with the Identity site:Redmond. This command includes just one optional parameter, -MinPasswordLength, which is used to set the MinPasswordLength property to 10. All the remaining policy properties will be configured using the default values.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
New-CsPinPolicy -Identity "site:Redmond" -MinPasswordLength 10 -PINHistory 10 -PINLifetime 30 |
|
The command shown in Example 2 creates a new policy with the Identity site:Redmond. This command uses the parameters -MinPasswordLength, -PINHistory, and -PINLifetime to explicitly configure three different property values.
-------------------------- Example 3 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsPinPolicy -Identity "site:Redmond" -InMemory $x.MinPasswordLength = 10 $x.PINHistory = 10 $x.PINLifetime = 30 Set-CsPinPolicy -Instance $x |
|
The set of commands shown in Example 3 demonstrate how you can create a new PIN policy in memory only, manipulate the property values for that policy, then use Set-CsPinPolicy to turn that in-memory-only policy into an actual PIN policy. In the first line above, New-CsPinPolicy, and the –InMemory parameter, are used to create an in-memory policy with the Identity site:Redmond; this policy is stored in the variable $x. If the policy was not assigned to a variable then it would be created in memory, then immediately disappear as soon as the command completed.
After the policy has been assigned to the variable $x, the next three commands are used to modify property values for that policy; for example, line 2 sets the value of the MinPasswordLength property to 10. After all the properties have been configured, Set-CsPinPolicy is used to create an actual policy with the Identity site:Redmond; this is done by using the -Instance parameter and passing the variable $x as the parameter value. After Set-CsPinPolicy has been called, you will be able to view the policy and its property values by using the Get-CsPinPolicy cmdlet.
-------------------------- Example 4 ------------------------
| Copy Code |
|
|---|---|
$x = Get-CsPinPolicy -Identity "site:Redmond" New-CsPinPolicy -Identity "site:Paris" -MinPasswordLength $x.MinPasswordLength |
|
The commands used in Example 4 create a new PIN policy (site:Paris) that uses one of the property values found in the existing policy site:Redmond. To achieve this, the first command uses Get-CsPinPolicy to the PIN policy site:Redmond; the information retrieved for this policy is then stored in the variable $x. In the second command, New-CsPinPolicy is used to create the policy site:Paris. In addition, the -MinPasswordLength parameter is used to specify the value of the MinPasswordLength property. Instead of using a hard-coded numeric value, however, the command uses $x.MinPasswordLength as the parameter value; this tells New-CsPinPolicy to set the minimum password length to the value of the MinPasswordLength property found in the policy site:Redmond. The net result is that the value of the MinPasswordLength property is copied from the existing policy site:Redmond to the new policy site:Paris.