Topic Last Modified: 2011-03-31

Provides a way to request certificates for use with servers running Microsoft Lync Server 2010 and server roles. Also provides a way to check the status of existing certificate requests and, if needed, to cancel any (or all) of those requests.

Syntax

Request-CsCertificate -New <SwitchParameter> -Type <CertType[]> [-CA <String>] [-CaAccount <String>] [-CaPassword <String>] [-City <String>] [-ClientEKU <$true | $false>] [-ComputerFqdn <Fqdn>] [-Confirm [<SwitchParameter>]] [-Country <String>] [-DomainName <String>] [-Force <SwitchParameter>] [-FriendlyName <String>] [-GlobalCatalog <Fqdn>] [-GlobalSettingsDomainController <Fqdn>] [-KeyAlg <RSA | ECDH_P256 | ECDH_P384 | ECDH_P521>] [-KeySize <Int32>] [-Organization <String>] [-OU <String>] [-Output <String>] [-PrivateKeyExportable <$true | $false>] [-Report <String>] [-State <String>] [-Template <String>] [-WhatIf [<SwitchParameter>]]
Request-CsCertificate -List <SwitchParameter> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-RequestId <Int32>] [-WhatIf [<SwitchParameter>]]
Request-CsCertificate -Retrieve <SwitchParameter> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-RequestId <Int32>] [-WhatIf [<SwitchParameter>]]
Request-CsCertificate -Clear <SwitchParameter> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-RequestId <Int32>] [-WhatIf [<SwitchParameter>]]

Parameters

Parameter Required Type Description

Type

Required

String

Type of certificate being requested. Certificate types include (but are not limited to):

AccessEdgeExternal

AudioVideoAuthentication

DataEdgeExternal

Default

External

Internal

PICWebService (Microsoft Lync Online 2010 only)

ProvisionService (Microsoft Lync Online 2010 only)

WebServicesExternal

WebServicesInternal

WsFedTokenTransfer

For example, this syntax requests a new Default certificate: -Type Default.

You can specify multiple types in a single command by separating the certificate types with commas:

-Type Internal,External,Default

CA

Optional

String

Fully qualified domain name (FQDN) that points to the CA. For example: -CA "atl-ca-001.litwareinc.com\myca". To obtain a list of known CAs, type the following at the Windows PowerShell prompt, and then press ENTER:

certutil

The Config property returned by Certutil indicates the location of a CA.

CaAccount

Optional

String

Account name of the user requesting the new certificate, using the format domain_name\user_name. For example: -CaAccount "litwareinc\kenmyer". If not specified, Request-CsCertificate will use the credentials of the logged-on user when requesting the new certificate.

CaPassword

Optional

String

Password for the user requesting the new certificate (as specified using the CaAccount parameter).

City

Optional

String

City where the certificate will be deployed.

Clear

Optional

Switch Parameter

When present, deletes any pending certificate requests made by using Request-CsCertificate.

ClientEKU

Optional

Boolean

Set this parameter to True if the certificate is to be used for client authentication. This type of authentication is required if you want your users to be able to exchange instant messages with people who have accounts with AOL. The EKU portion of the parameter name is short for extended key usage; the extended key usage field lists the valid uses for the certificate.

ComputerFqdn

Optional

String

FQDN of the computer for which the certificate is being requested. When present, this parameter forces Request-CsCertificate to connect to the Central Management store in order to locate the specified computer. You should always use the computer name when requesting a certificate, even when requesting a pool certificate. The Request-CsCertificate cmdlet will automatically add the pool name to the Subject Name of any certificate obtained using this cmdlet.

Country

Optional

String

Country/region where the certificate will be deployed.

DomainName

Optional

String

Comma-separated list of fully-qualified domain names that should be added to the certificate’s Subject Alternative Name field. For example:

-DomainName "atl-cs-001.litwareinc.com, atl-cs-002.litwareinc.com,atl-cs-003.litwareinc.com"

FriendlyName

Optional

String

User-assigned name that makes it easier to identify the certificate.

GlobalCatalog

Optional

String

FQDN of a global catalog server in your domain. This parameter is not required if you are running Request-CsCertificate on a computer with an account in your domain.

GlobalSettingsDomainController

Optional

String

FQDN of a domain controller where global settings are stored. If global settings are stored in the System container in Active Directory Domain Services (AD DS) then this parameter must point to the root domain controller. If global settings are stored in the Configuration container then any domain controller can be used and this parameter can be omitted.

KeyAlg

Optional

PS List Modifier

Indicates the type of cryptographic algorithm to be used in generating the public and private keys for the new certificate. Valid key algorithms include:

RSA

ECDH_P256

ECDH_P384

ECDH_P521

KeySize

Optional

Integer

Indicates the size (in bits) of the private key used by the certificate. Larger key sizes are more secure, but require more processing overhead in order to be decrypted.

Valid key sizes are 1024; 2048; and 4096. For example: -KeySize 2048.

List

Optional

Switch Parameter

When present, lists any pending certificate requests made by using Request-CsCertificate.

New

Optional

Switch Parameter

When present, indicates that you want to request a new certificate.

Organization

Optional

String

Name of the organization requesting the new certificate. For example: -Organization "Litwareinc".

OU

Optional

String

Active Directory organizational unit for the computer that will be assigned the new certificate.

Output

Optional

String

Path to the certificate file. If you want to create an offline certificate request use the Output parameter and specify a file path for the certificate request; for example: -Output C:\Certificates\NewCertificate.pfx. That will create a certificate request file that can then be emailed to a certification authority for processing.

PrivateKeyExportable

Optional

Boolean

Set this parameter to True if you want to make the certificate’s private key exportable. When a private key is exportable, the certificate can be copied and used on multiple computers.

RequestID

Optional

Integer

Identification number associated with a certificate request. The RequestID parameter provides a way for you to list, retrieve, or clear an individual certificate.

Retrieve

Optional

Switch Parameter

When present, retrieves any pending certificate requests made by using Request-CsCertificate and attempts to complete the operation and import the requested certificate.

State

Optional

String

U.S. state where the certificate will be deployed. For example: -State WA.

Template

Optional

String

Indicates the certificate template to be used when generating the new certificate; for example: -Template "WebServer". The requested template must be installed on the CA. Note that the value entered must be the template name, not the template display name.

Force

Optional

Switch Parameter

Suppresses the display of any non-fatal error message that might occur when running the command.

Report

Optional

String

Enables you to specify a file path for the log file created when the cmdlet runs. For example: -Report "C:\Logs\Certificates.html"

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

Lync Server 2010 uses certificates as a way for servers and server roles to verify their identities; for example, an Edge Server uses certificates to verify that the computer it is communicating with really is a Front End Server and vice versa. In order to fully implement Lync Server, you will need to have the appropriate certificates assigned to the appropriate server roles.

One way to request certificates for use with Lync Server is to call the Request-CsCertificate cmdlet. Although it is possible to use other standard Windows tools in order to request certificates for use with Lync Server, one major advantage to using Request-CsCertificate is the fact that the cmdlet will analyze your topology before contacting the certification authority (CA). Based on that analysis, Request-CsCertificate will automatically request a certificate with the proper subject name and subject alternative name fields.

Request-CsCertificate is designed to request certificates specifically for use with Lync Server. It is not designed to be an all-purpose certificate management tool.

In addition to requesting new certificates, this cmdlet can also be used to review any pending certificate requests, provided those requests were made using Request-CsCertificate. Request-CsCertificate can also be used to delete pending certificate requests, as long as those requests were made using the cmdlet.

When attempting to retrieve certificate requests you might receive an error message if you have any revoked requests; currently Request-CsCertificate only supports these request types: Issued, Denied, and Pending. If you encounter problems due to a revoked certificate use a command similar to this to clear the revoked request (where 224 is the RequestID of the revoked certificate request):

Request-CsCertificate –Clear –RequestID 224

After that you should be able to retrieve certificate requests.

Who can run this cmdlet: You must be a local administrator and have rights to the specified certification authority in order to run the Request-CsCertificate cmdlet locally. 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 "Request-CsCertificate"}

Input Types

None. Request-CsCertificate does not accept pipelined input.

Return Types

None. Instead, Request-CsCertificate helps manage instances of the Microsoft.Rtc.Management.Deployment.CertificateReference object.

Example

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

Copy Code 
Request-CsCertificate -New -Type WebServicesExternal -CA "atl-ca-001.litwareinc.com\myca"

The command shown in Example 1 creates a new certificate request: it contacts the CA atl-ca-001.litwareinc.com\myca and requests a new WebServicesExternal certificate.

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

Copy Code 
Request-CsCertificate -List

The preceding command lists all the pending certificate requests made by using Request-CsCertificate.

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

Copy Code 
Request-CsCertificate -New -Type WebServicesExternal -Output C:\Certificates\WebServicesExternal.cer

Example 3 uses the Output parameter to create an offline certificate request.

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

Copy Code 
Request-CsCertificate -New -Type Default,WebServicesInternal,WebServicesExternal -ComputerFqdn "atl-cs-001.litwareinc.com" -CA "atl-ca-001.litwareinc.com\myca" -FriendlyName "Standard Edition Certficate" -Template jcila -PrivateKeyExportable $True -DomainName "atl-cs-001.litwareinc.com,atl-ext.litwareinc.com"

The preceding example is a more detailed (and more realistic) example of how to use Request-CsCertificate. This example requests a certificate for use with the Standard Edition of Lync Server

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

Copy Code 
Request-CsCertificate -New -Type Default,WebServicesInternal,WebServicesExternal -ComputerFqdn "atl-cs-001.litwareinc.com" -CA "atl-ca-001.litwareinc.com\myca" -FriendlyName "Enterprise Edition Pool Certificate" -Template jcila -PrivateKeyExportable Ttrue -DomainName "pool1.litwareinc.com,pool1int.litwareinc.com,pool1ext.litwareinc.com"

In Example 5, a pool certificate is requested for use with the Enterprise Edition of Lync Server

-------------------------- Example 6 -----------------------

Copy Code 
Request-CsCertificate -New -Type Internal -ComputerFqdn "atl-edge-001" -CA "atl-ca-001.litwareinc.com\myca" -FriendlyName "Internal Edge Certificate" -Template jcila -PrivateKeyExportable $True -DomainName "atl-edge-001.litwareinc.com, ap.litwareinc.com"

The preceding example shows how you can request a certificate for the internal Edge Server.

-------------------------- Example 7 -----------------------

Copy Code 
Request-CsCertificate -New -Type AccessEdgeExternal,DataEdgeExternal,AudioVideoAuthentication -ComputerFqdn "atl-edge-001" -CA "atl-ca-001.litwareinc.com\myca" -FriendlyName "External Edge Certificate" -Template jcila -PrivateKeyExportable $True -DomainName "atl-edge-001.litwareinc.com,ap.litwareinc.com,dp.litwareinc.com,atl-edge-001"

Example 7 is a variation of the command shown in Example 6, In this case, however, the request is for the external Edge Server.

See Also