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

Returns information about the client PIN authentication policies configured for use in your organization. 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). Client PIN policies can be configured at the global, site, or per-user scope.

Syntax


Get-CsPinPolicy [-Identity <XdsIdentity>] [-LocalStore <SwitchParameter>]


Get-CsPinPolicy [-Filter <String>] [-LocalStore <SwitchParameter>]

Parameters

Parameter	Required	Type	Description
Identity	Optional	XdsIdentity	Indicates the 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 this syntax: -Identity site:Redmond. To refer to a policy at the per-user scope use syntax similar to this: -Identity RedmondPolicy. Note that wildcard characters such as the asterisk (*) cannot be used with the -Identity parameter. To do a wildcard search for policies, use the -Filter parameter instead.
Filter	Optional	String	Enables you to do a wildcard search for PIN policies. For example, to find all the policies configured at the site scope use this Filter: site:. To find the site policies Seattle, Seville, and Saskatoon (all of which start with the letter "S") use this Filter: site:S. Note that the -Filter parameter can only be applied to the policy Identity.
LocalStore	Optional	Switch Parameter

Parameter

Required

Type

Description

Identity

Optional

XdsIdentity

Indicates the 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 this syntax: -Identity site:Redmond. To refer to a policy at the per-user scope use syntax similar to this: -Identity RedmondPolicy.

Note that wildcard characters such as the asterisk (*) cannot be used with the -Identity parameter. To do a wildcard search for policies, use the -Filter parameter instead.

Filter

Optional

String

Enables you to do a wildcard search for PIN policies. For example, to find all the policies configured at the site scope use this Filter: site:*. To find the site policies Seattle, Seville, and Saskatoon (all of which start with the letter "S") use this Filter: site:S*. Note that the -Filter parameter can only be applied to the policy Identity.

LocalStore

Optional

Switch Parameter

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 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 Get-CsPinPolicy cmdlet to retrieve information about the PIN policies currently configured for use in your organization.

Return Types

Get-CsPinPolicy returns one or more instances of the Microsoft.Rtc.Management.WriteableConfig.Policy.UserPin.UserPinPolicy object.

Examples

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

	Copy Code
Get-CsPinPolicy

The command shown in Example 1 returns a collection of all the PIN policies configured for use in the organization. Calling Get-CsPinPolicy without specifying an identity returns the complete set of PIN policies/

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

	Copy Code
Get-CsPinPolicy -Identity "site:Redmond"

Example 2 returns a single PIN policy: the policy with the Identity site:Redmond.

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

	Copy Code
Get-CsPinPolicy -Filter "tag:*"

The command shown in Example 3 uses the -Filter parameter to return all the policies that have been configured at the per-user scope. This is done by using the filter value tag:*; this value tells Get-CsPinPolicy to return only those policies that have an Identity that begins with the characters tag:. Only policies configured at the per-user scope will have Identities that begin with those characters.

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

	Copy Code
Get-CsPinPolicy \| Where-Object {$_.AllowCommonPatterns -eq $True}

Example 4 shows an alternate way to retrieve a subset of PIN policies. In this example, Get-CsPinPolicy is called without any additional parameters; that returns a collection of all the PIN policies configured for use in the organization. That collection is then passed to the Where-Object cmdlet, which picks out only those policies where the AllowCommonPatterns property is equal to (-eq) True ($True). The net result: only policies where AllowCommonPatterns is True are returned.

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

	Copy Code
Get-CsPinPolicy \| Where-Object {$_.PinLifetime -gt 30}

Like Example 4, the command shown in example 5 uses Where-Object to return a subset of the existing PIN policies. In this case, Where-Object retrieves only those policies where the PinLifetime property is greater than (-gt) 30. That means only policies that have PIN expiration times of more than 30 days will be returned.