Test-CsClientAuth
[This is preliminary content that is currently being developed, reviewed, and updated for the latest release of Lync Server. As a result, it may be incomplete or out of date. Blank topics are included as placeholders. Please send us your feedback, including what content you hoped to find or would find most useful.]
Determines whether or not a user can log on to Lync Server by using a certificate downloaded from the certificate provisioning service. This cmdlet was introduced in Microsoft Lync Server 2010.
Syntax
Test-CsClientAuth -UserCredential <PSCredential> -UserSipAddress <String> [-Force <SwitchParameter>] [-LiveIdAuthentication <SwitchParameter>] [-OutLoggerVariable <String>] [-OutVerboseVariable <String>] [-RegistrarPort <Int32>] [-TargetFqdn <String>] [-TargetUri <String>]
Examples
EXAMPLE 1
The commands shown in Example 1 test the ability of the user litwareinc\kenmyer to log on to the Registrar pool atl-cs-001.litwareinc.com by using a client certificate. To carry out this task, the first command in the example uses Get-Credential to create credential object for the user in question. The resulting credential object (which requires you to enter the password for the user) is stored in a variable named $cred1.
The second command then calls Test-CsClientAuth, specifying the FQDN of the Registrar pool (TargetFqdn), the user’s SIP address (UserSipAddress) and the credential object created in the initial command (UserCredential).
$cred1 = Get-Credential "litwareinc\kenmyer"
Test-CsClientAuth -TargetFqdn atl-cs-001.litwareinc.com -UserSipAddress "sip:kenmyer@litwareinc.com" -UserCredential $cred1
Detailed Description
Client certificates provide an alternate way for users to be authenticated by Lync Server. In order to determine whether or not a user can log on to the system by using a client certificate, you can run the Test-CsClientAuth cmdlet. When you run this Test-CsClientAuth you must specify the Registrar pool and SIP address of the user account being tested; you must also be able to supply the user’s logon name and password. After calling Test-CsClientAuth, the cmdlet will contact the certificate provisioning service and download a copy of any client certificates for the specified user. If a client certificate can be found and downloaded, Test-CsClientAuth will then attempt to log on using that certificate. If logon succeeds, Test-CsClientAuth will log off and report that the test succeeded.
If a certificate cannot be found or downloaded, or if the cmdlet is unable to logon using that certificate, then Test-CsClientAuth will report that the test failed.
Who can run this cmdlet: 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 "Test-CsClientAuth"}
Parameters
Parameter | Required | Type | Description |
---|---|---|---|
UserCredential |
Required |
System.Management.Automation.PSCredential |
User credential object for the user account to be used in the test. The value passed to UserCredential should be an object reference obtained by using the Get-Credential cmdlet. For example, this code returns a credentials object for the user litwareinc\kenmyer and stores that object in a variable named $x: $x = Get-Credential "litwareinc\kenmyer" You need to supply the user password when running this command. |
UserSipAddress |
Required |
System.String |
SIP address of the user to be used in the test. For example: -UserSipAddress sip:kenmyer@litwareinc.com. |
Force |
Optional |
System.Management.Automation.SwitchParameter |
Suppresses the display of any non-fatal error message that might occur when running the command. |
LiveIdAuthentication |
Optional |
System.Management.Automation.SwitchParameter |
Verifies the ability of the test user to log on using their OrgId (Business LiveId) credentials. |
OutLoggerVariable |
Optional |
System.String |
When present, detailed output from running the cmdlet will be stored in the specified variable. This variable includes a pair of methods – ToHTML and ToXML – that can then be used to save that output to either an HTML or an XML file. To store output in a logger variable named $TestOutput use the following syntax: -OutLoggerVariable TestOutput Note: Do not use prepend a $ character when specifying the variable name.To save the information stored in the logger variable to an HTML file, use a command similar to this: $TestOutput.ToHTML() > C:\Logs\TestOutput.html To save the information stored in the logger variable to an XML file, use a command similar to this: $TestOutput.ToXML() > C:\Logs\TestOutput.xml |
OutVerboseVariable |
Optional |
System.String |
When present, detailed output from running the cmdlet will be stored in the specified variable. For example, to store output in a variable named $TestOutput use the following syntax: -OutVerboseVariable TestOutput Do not prepend a $ character when specifying the variable name. |
RegistrarPort |
Optional |
System.Int32 |
SIP port used by the Registrar service. This parameter is not required if the Registrar uses the default port 5061. |
TargetFqdn |
Optional |
System.String |
Fully qualified domain name (FQDN) of the Registrar pool where client authentication is to be tested. For example: -TargetFqdn "atl-cs-001.litwareinc.com". |
TargetUri |
Optional |
System.String |
URL of the certificate provisioning service. If this parameter is not included then the Test-CsClientAuth will use the certificate provisioning service configured for the Registrar pool. |
Input Types
None.
Return Types
Test-CsClientAuth returns an instance of the Microsoft.Rtc.SyntheticTransactions.TaskOutput object.