You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

This page describes the process of certificate rollover for Shibboleth Identity Providers. The procedure described below allows replacing certificates without any service disruptions.

In SWAMID default installation we have both an Encryption and a Signing certificate.

Step 0 : Create new certificate

  • Use the following commands to create the encryption and signing certificates. Change the values needed.
$ADFSDnsName = "[ADFS DNS Name]"
# Encryption Certificate
$encryptionCertificate = New-SelfSignedCertificate -CertStoreLocation "cert:\LocalMachine\My" -DnsName "encryption.$ADFSDnsName" -KeyExportPolicy Exportable -KeyLength 4096 -NotAfter (Get-Date).AddYears(10) -KeySpec KeyExchange

# Signing Certificate
$signingCertificate = New-SelfSignedCertificate -CertStoreLocation "cert:\LocalMachine\My" -DnsName "signing.$ADFSDnsName" -KeyExportPolicy Exportable -KeyLength 4096 -NotAfter (Get-Date).AddYears(10) -KeySpec KeyExchange
  • We recommend to turn off automatic certificate rollover to ensure that you have control of the process.
  • Check if automatic certificate rollover is turned on with the following command:
Get-AdfsProperties | Select AutoCertificateRollover
  • To turn it off, use the following command:
Set-AdfsProperties -AutoCertificateRollover $false

Step 1 : Export certificates and import on all ADFS servers in the farm

  • Export the certificates on the server where you created them. Change FilePath if needed
# Encryption Certificate
$encryptionPassword = Read-Host "Type a secure password for the encryption PFX file" -AsSecureString
Export-PfxCertificate -Cert $encryptionCertificate -FilePath ("C:\{0}.pfx" -f $ADFSDnsName -Password $password

# Signing Certificate
$signingPassword = Read-Host "Type a secure password for the signing PFX file" -AsSecureString
Export-PfxCertificate -Cert $signingCertificate -FilePath ("C:\{0}.pfx" -f $ADFSDnsName -Password $password
  • Copy the certificates to all ADFS servers in the farm and import them.
$ADFSDnsName = "[ADFS DNS Name]"

# Encryption Certificate
$encryptionPassword = Read-Host "Type the previous password for the encryption PFX file" -AsSecureString
Import-PfxCertificate -FilePath 'C:\encryption.ADFS DNS Name.pfx' -Exportable:$true -Password $encryptionPassword -CertStoreLocation "cert:\LocalMachine\My"

# Signing Certificate
$signingPassword = Read-Host "Type the password for the signing PFX file" -AsSecureString
Import-PfxCertificate -FilePath 'C:\signing.ADFS DNS Name.pfx' -Exportable:$true -Password $signingPassword -CertStoreLocation "cert:\LocalMachine\My"

Step 1 : Add Certificates to ADFS

  • Token-Signing
Add-AdfsCertificate -CertificateType "Token-Signing" -Thumbprint "thumbprint of signing cert"
  • Token-Decrypting
Add-AdfsCertificate -CertificateType "Token-Decrypting" -Thumbprint "thumbprint of decrypting cert"

Step 2 : Upload new Metadata

ADFS normally publish new signing-certs in the step and rolls the encryption-cert in step 4!!!

  • Upload the XML from https://adfs.example.com/federationmetadata/2007-06/federationmetadata.xml to metadata.swamid.se/admin.
  • Remove the SP / IdP part if the ADFS isn't going to be used as both roles.
  • Use "Merge missing from published" to copy over all EntityCategory's and MDUI information from the old Entity
  • Request publication.
  • Wait until you get confirmation of publication and then for at least 8 h more (recommended 24 h if in SWAMID and  48 h in eduGAIN) for all entities to pick up the new cert/key. 

Step 3 : Certificate rollover 

Automatic rollover

When does this happen? In the Get-AdfsProperties command, you can check the value for CertificateCriticalThreshold.

The default setting is 2 and it means that ADFS will switch the certificates two days before their expiration date weather you want it to or not.

The next parameter of interest is CertificatePromotionThreshold, the default value of 5 means the old certificate will be present as a secondary certificate for five days after rollover.

Manual rollover

This can be done in the console by right clicking on the certificate and select "Set as primary" or by powershell

Set-AdfsCertificate -CertificateType "Token-Decrypting/Token-Signing" -Thumbprint "thumbprint of cert" -IsPrimary

Step 4 : Upload new Metadata again

ADFS should now have removed the old signing cert in XML and replaced the encryption cert in https://adfs.example.com/federationmetadata/2007-06/federationmetadata.xml

  • Upload the XML from https://adfs.example.com/federationmetadata/2007-06/federationmetadata.xml to metadata.swamid.se/admin.
  • Remove the SP / IdP part if the ADFS isn't going to be used as both roles.
  • Use "Merge missing from published" to copy over all EntityCategory's and MDUI information from the old Entity
  • Request publication.
  • Wait until you get confirmation of publication and then for at least 8 h more (recommended 24 h if in SWAMID and  48 h in eduGAIN) for all entities to pick up the new cert/key. 

Step 5 : Disable / remove key from software. 

Remove old certificates from console or with powershell

Remove-AdfsCertificate -CertificateType "Token-Signing or Token-Decrypting" -Thumbprint "thumbprint"
  • No labels