Replace the STS certificate for SharePoint Server
APPLIES TO: 2013 2016 2019 Subscription Edition SharePoint in Microsoft 365
This topic provides information on replacing the SharePoint Security Token Service (STS) certificate in a SharePoint farm.
Certificate Requirements
Purchase a certificate from a trusted Certificate Authority, create a new certificate from a self-hosted PKI infrastructure (such as Active Directory Certificate Services), or create a self-signed certificate (created through certreq.exe
or New-SelfSignedCertificate
). The certificate must be using 2048 bit encryption or higher.
To replace the STS certificate, you will need the public certificate (CER) and public with private key certificate (PFX) and the friendly name of the certificate.
The certificate should be replaced during a maintenance window as the SharePoint Timer Service (SPTimerV4) must be restarted.
As public certificates and by default, private certificates expire within 1 to 3 years depending on the specified validity period, this procedure should be followed when the certificate requires renewal.
Note
The default STS certificate does not need to be renewed. Renewal only applies after the STS certificate has been replaced.
Creating a Self-Signed Certificate
To create a self-signed certificate, choose the method of creation and follow these steps.
Tip
The Common Name and DNS Name may be set to any value.
Note
Certificate private keys and passwords are sensitive. Use a strong password and securely store the PFX file.
New-SelfSignedCertificate
New-SelfSignedCertificate -DnsName 'sts.contoso.com' -KeyLength 2048 -FriendlyName 'SharePoint STS Certificate' -CertStoreLocation 'cert:\LocalMachine\My' -KeySpec KeyExchange
$password = ConvertTo-SecureString "P@ssw0rd1!" -Force -AsPlainText
$cert = Get-ChildItem "cert:\localmachine\my" | ?{$_.Subject -eq "CN=sts.contoso.com"}
Export-PfxCertificate -Cert $cert -Password $password -FilePath C:\sts.pfx
Export-Certificate -Cert $cert -Type CERT -FilePath C:\sts.cer
This example creates a new certificate with the DNS Name of 'sts.contoso.com' and a Common Name of 'CN=sts.contoso.com'. The Common Name is automatically set by the New-SelfSignedCertificate
cmdlet. Using a secure password, we then export the PFX (sts.pfx) and public certificate (sts.cer).
Certreq
Create a new file, request.inf, for the certificate. Adjust the Subject as needed from the below example.
[Version]
Signature="$Windows NT$
[NewRequest]
FriendlyName = "SharePoint STS Certificate"
Subject = "CN=sts.contoso.com"
KeyLength = 2048
KeyAlgorithm = RSA
KeyUsage = "CERT_KEY_ENCIPHERMENT_KEY_USAGE | CERT_DIGITAL_SIGNATURE_KEY_USAGE"
KeySpec = "AT_KEYEXCHANGE"
MachineKeySet = true
RequestType = Cert
ExportableEncrypted = true
[Strings]
szOID_ENHANCED_KEY_USAGE = "2.5.29.37"
szOID_PKIX_KP_SERVER_AUTH = "1.3.6.1.5.5.7.3.1"
szOID_PKIX_KP_CLIENT_AUTH = "1.3.6.1.5.5.7.3.2"
[Extensions]
%szOID_ENHANCED_KEY_USAGE%="{text}%szOID_PKIX_KP_SERVER_AUTH%,"
_continue_ = "%szOID_PKIX_KP_CLIENT_AUTH%"
From an elevated Command Prompt, run the following to create and install the certificate in the local machine store. When the certificate has been installed, a save dialog will appear. Change the Save as type to Certificate Files
and save the file as C:\sts.cer
.
certreq -new request.inf
certutil -store My "sts.contoso.com"
copy the SerialNumber output from the second command and use it in the following command. Replace <SerialNumber> with the actual value.
certutil -exportPFX -p "P@ssw0rd1!" CA <SerialNumber> C:\sts.pfx
The first step creates the certificate based on the above request. The second step allows us to find the Serial Number of our new certificate. Finally, the last step exports the certificate to a PFX secured by a password.
Replacing the STS certificate
This procedure must be performed on every server in the farm. The first step is to import the PFX to the Trusted Root Certification Authorities container in the Local Machine store.
Import-PfxCertificate
To import a PFX using Import-PfxCertificate
, follow the example.
$password = Get-Credential -UserName "certificate" -Message "Enter password"
Import-PfxCertificate -FilePath C:\sts.pfx -CertStoreLocation Cert:\LocalMachine\Root -Password $password.Password
In this example, we first create a credential. The username isn't used in this example, but must be set. The password will be the value of the exported PFX password; in our example, "P@ssw0rd1!".
Certutil
certutil -f -p "P@ssw0rd1!" -importpfx Root C:\sts.pfx
In this example, we import the PFX file using certutil
, specifying the password we used when exporting the PFX and importing into the Trusted Root Certification Authorities container in the Local Machine store.
Replace the STS Certificate in SharePoint
Once the PFX has been imported on all SharePoint servers in the farm, we must replace the certificate that is in use by the STS. You must be a SharePoint Shell Administrator (see Add-SPShellAdmin for details on how to add a SharePoint Shell Administrator) to perform this operation.
Using the SharePoint Management Shell, we will specify the path to the PFX file, set the password, set the STS to use the new certificate, restart IIS, and finally restart the SharePoint Timer Service (SPTimerV4).
$path = 'C:\sts.pfx'
$pass = 'P@ssw0rd1!'
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($path, $pass, 20)
Set-SPSecurityTokenServiceConfig -ImportSigningCertificate $cert
iisreset
Restart-Service SPTimerV4
Complete the previous steps on all SharePoint server in the farm. This completes the STS certificate replacement process. If you are using a hybrid farm, see Use a Microsoft 365 SharePoint site to authorize provider-hosted add-ins on an on-premises SharePoint site for additional steps required to upload the STS certificate to Azure.