Any suggestions? Export (0) Print
Expand All

New-ExchangeCertificate

 

Applies to: Exchange Server 2016

This cmdlet is available only in on-premises Exchange Server 2016.

Use the New-ExchangeCertificate cmdlet to create a self-signed certificate, renew an existing self-signed certificate, or generate a new certificate request for obtaining a certificate from a certification authority (CA).

For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.

New-ExchangeCertificate [-BinaryEncoded <SwitchParameter>] [-GenerateRequest <SwitchParameter>] [-RequestFile <String>] <COMMON PARAMETERS>
New-ExchangeCertificate [-Services <None | IMAP | POP | UM | IIS | SMTP | Federation | UMCallRouter>] <COMMON PARAMETERS>
COMMON PARAMETERS: [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-DomainName <MultiValuedProperty>] [-Force <SwitchParameter>] [-FriendlyName <String>] [-IncludeAcceptedDomains <SwitchParameter>] [-IncludeAutoDiscover <SwitchParameter>] [-IncludeServerFQDN <SwitchParameter>] [-IncludeServerNetBIOSName <SwitchParameter>] [-Instance <X509Certificate2>] [-KeySize <Int32>] [-PrivateKeyExportable <$true | $false>] [-Server <ServerIdParameter>] [-SubjectKeyIdentifier <String>] [-SubjectName <X500DistinguishedName>] [-WhatIf [<SwitchParameter>]]

This example creates a self-signed certificate. If you don't want this certificate to replace the existing self-signed certificate that was created during Exchange setup, be sure to select no in the prompt that asks you overwrite the existing default SMTP certificate.

New-ExchangeCertificate

This example generates a new certificate request that has the following attributes:

  • Base64 encoding is used.

  • The request is generated on-screen and is also written to the text file C:\Cert Requests\woodgrovebank.cer

  • Subject name: c=ES,o=Woodgrove Bank,cn=mail1.woodgrovebank.com

  • Subject alternate names: woodgrovebank.com and fabirkam.com

  • The private key is exportable

New-ExchangeCertificate -GenerateRequest -RequestFile "C:\Cert Requests\woodgrovebank.cer" -SubjectName "c=US,o=Woodgrove Bank,cn=mail1.woodgrovebank.com" -DomainName woodgrovebank.com,fabrikam.com -PrivateKeyExportable $true
noteNote:
If the CA requires a DER encoded certificate request, use the BinaryEncoding switch.

Exchange uses certificates for SSL and TLS encryption.

New self-signed certificates that you create by using this cmdlet have the following default properties:

  • The certificate has the fully qualified domain name (FQDN) of the local computer as the subject name.

  • The Network Services local security group is granted read access to the private key that's associated with the certificate.

  • The certificate is published to Active Directory so that Exchange direct trust can validate the authenticity of the server for mutual TLS.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Certificate management" entry in the Exchange infrastructure and PowerShell permissions topic.

 

Parameter Required Type Description

BinaryEncoded

Optional

System.Management.Automation.SwitchParameter

The BinaryEncoded switch specifies whether to encode the new certificate request by using Distinguished Encoding Rules (DER). You don't need to specify a value with this switch.

If you don't use this switch, the request is encoded by using Base64.

noteNote:
This switch is available only when you use the GenerateRequest switch.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.

  • Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: -Confirm:$false.

  • Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the domain controller that's used by this cmdlet to read data from or write data to Active Directory. You identify the domain controller by its fully qualified domain name (FQDN). For example, dc01.contoso.com.

The DomainController parameter isn't supported on Edge Transport servers. An Edge Transport server uses the local instance of Active Directory Lightweight Directory Services (AD LDS) to read and write data.

DomainName

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The DomainName parameter specifies one or more FQDNs or server names to be populated in the Subject Alternative Name field of the new certificate request or self-signed certificate.

You can specify multiple domain name values separated by commas. Values can contain the characters a through z, 0 through 9, and the hyphen (-). The length of the domain name can't exceed 255 characters.

noteNote:
If you don't use this parameter, and you if you don't use the IncludeAcceptedDomains, IncludeAutoDiscover, IncludeServerFQDN, or IncludeServerNetBIOSName switches, the host name and FQDN of the Exchange server are included by default.

Force

Optional

System.Management.Automation.SwitchParameter

The Force switch specifies whether to override the confirmation prompt and set the new self-signed certificate as the default certificate for TLS encryption of internal SMTP communication. You don't need to specify a value with this switch.

If you don't use this switch, a confirmation message is displayed when you attempt to set a new certificate as the default certificate for TLS encryption of internal SMTP communication.

FriendlyName

Optional

System.String

The FriendlyName parameter specifies a friendly name for the certificate. The value must be less than 64 characters.

The default friendly name is Microsoft Exchange.

GenerateRequest

Optional

System.Management.Automation.SwitchParameter

The GenerateRequest switch specifies whether the command generates a certificate request for a public key infrastructure (PKI) certificate (PKCS #10) in the local request store. Use this switch to create certificate requests instead of self-signed certificates. You don't need to specify a value with this switch.

To turn this certificate request into a certificate, you need to send the certificate request output to a CA. For example:

  • A CA within your organization.

  • A trusted CA outside your organization.

  • A commercial CA.

How you send the information depends on the CA, but typically you paste the output in an email message or in the request form on the CA's web site.

If you don't use this switch, the cmdlet creates a self-signed certificate in the local computer certificate store.

IncludeAcceptedDomains

Optional

System.Management.Automation.SwitchParameter

The IncludeAcceptedDomains switch specifies whether all accepted domains in the organization are included in the Subject Alternative Name field of the certificate request or self-signed certificate. You don't need to specify a value with this switch.

You can also specify one or more domain names using the DomainName parameter in addition to the accepted domains. The resulting certificate or request contains the specified domains and all accepted domains.

noteNote:
When you use this switch, any accepted domains you specify in the DomainName parameter aren't duplicated.

IncludeAutoDiscover

Optional

System.Management.Automation.SwitchParameter

The IncludeAutoDiscover switch specifies whether to add a Subject Alternative Name with the prefix autodiscover for each accepted domain in the Exchange organization. You don't need to specify a value with this switch.

For example, if the organization has the accepted domains woodgrovebank.com and woodgrovebank.co.uk, using this switch results in the addition of the following Subject Alternative Names:

  • autodiscover.woodgrovebank.com

  • autodiscover.woodgrovebank.co.uk

You can use this switch only on Exchange servers that have the Client Access role installed.

The autodiscover prefix isn't added if the domain name already contains the prefix.

IncludeServerFQDN

Optional

System.Management.Automation.SwitchParameter

The IncludeServerFQDN switch specifies whether to include the FQDN of the server in the Subject Alternative Name field of the new certificate request or self-signed certificate. You don't need to specify a value with this switch.

noteNote:
When you use this switch, any FQDNs you specify in the DomainName parameter aren't duplicated.

IncludeServerNetBIOSName

Optional

System.Management.Automation.SwitchParameter

The IncludeServerNetBIOSName switch specifies whether to include the NetBIOS name of the server in the Subject Alternative Name field of the new certificate request or self-signed certificate. You don't need to specify a value with this switch

noteNote:
When you use this switch, any NetBIOS names you specify in the DomainName parameter aren't duplicated.

Instance

Optional

System.Security.Cryptography.X509Certificates.X509Certificate2

The Instance parameter is no longer used and will be deprecated.

KeySize

Optional

System.Int32

The KeySize parameter specifies the size (in bits) of the RSA public key that's associated with the new certificate.

Valid values are 4096, 2048, and 1024. The default value is 2048.

PrivateKeyExportable

Optional

System.Boolean

The PrivateKeyExportable parameter specifies whether the new certificate has an exportable private key. Valid values are:

  • $true   The new certificate allows you to export the private key when you export the certificate.

  • $false   The new certificate doesn't allow you to export the private key when you export the certificate, This is the default value.

RequestFile

Optional

System.String

The RequestFile parameter specifies the name and path of the file that contains the certificate request. If the value contains spaces, enclose the value in quotation marks ("). The file contains the same information that's displayed on-screen when you generate a new certificate request.

You can use this parameter only when you use the GenerateRequest switch.

Server

Optional

Microsoft.Exchange.Configuration.Tasks.ServerIdParameter

The Server parameter specifies the Exchange server where you want to run this command. You can use any value that uniquely identifies the server. For example:

  • Name

  • FQDN

  • Distinguished name (DN)

  • Exchange Legacy DN

If you don't use this parameter, the command is run on the local server.

Services

Optional

Microsoft.Exchange.Management.SystemConfigurationTasks.AllowedServices

The Services parameter specifies the services that are used by a new self-signed certificate. Valid values are:

  • Federation

  • IIS

  • IMAP

  • None

  • POP

  • SMTP

  • UM

  • UMCallRouter

You can specify multiple values separated by commas. The default values are IMAP, POP, and SMTP.

importantImportant:
You use this parameter only when you create self-signed certificates. If you're generating a certificate request for a CA by using the GenerateRequest switch, you install the certificate after it's issued by the CA, and then specify the services by using the Enable-ExchangeCertificate cmdlet.

SubjectKeyIdentifier

Optional

System.String

The SubjectKeyIdentifier parameter specifies the subject key identifier extension for the certificate, which isn't required for normal operation.

SubjectName

Optional

System.Security.Cryptography.X509Certificates.X500DistinguishedName

The SubjectName parameter specifies the subject name of the resulting certificate. A subject name is an X.500 distinguished name that consists of one or more relative distinguished names (also known as RDNs).

The subject name of a certificate is the field used by Domain Name System (DNS)-aware services. It binds a certificate to a particular server or domain name.

If the SubjectName parameter isn't specified, the host name of the server where the cmdlet is run is used as the common name (CN) in the resulting certificate. For example, for the server EXMBX01, the SubjectName parameter value CN=EXMBX01 is used.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.

 
Show:
© 2016 Microsoft