Update the Identity Provider SAML Signing Certificate
SAML connections which use signed requests and responses depend on two different SAML signing certificates. One for each side of the SAML connection. The IdP certificate rotation process is not to be confused with the Service Provider yearly rotation of the samlsigning.cloud.com certificate in use by all Citrix Cloud customers. Citrix does not control the rotation of your SAML application’s IDP certificate. Your Citrix Cloud and IdP administrator does.
FAQ
What is the SAML application’s signing certificate used for?
Your SAML application’s signing certificate is uploaded into Citrix Cloud when you initially create the SAML connection. During the initial SAML connection creation process only one IdP signing certificate needs to be provided. The IdP certificate is obtained from within your SAML provider such as Azure AD, Okta, PingFederate, or ADFS. Citrix Cloud uses the IdP signing certificate to verify the signature of SAML responses sent from your SAML application to Citrix Cloud during the SAML authentication process. The IdP certificate will be trusted by Citrix Cloud until its date of expiry.
What is a SAML application signing certificate rotation?
An IdP Signing Certificate Rotation is a planned maintenance task that is required when your SAML application’s signing certificate is approaching its date of expiry. Admins need to pay attention to the IdP signing certificate used by SAML connections within Citrix Cloud. When the certificate is about to expire within 30 days, upload an in-date replacement certificate into your Citrix Cloud SAML connection. Do this replacement before the current certificate expires.
How frequently do I need to rotate my SAML application’s signing certificate?
Cloud SAML application certificates typically have very long lifespans such as 16 years for Duo, 10 years for Okta and 3 years for Entra ID SAML applications. Certificates used within on premise SAML IdPs such as PingFederate or ADFS are created and maintained like any other x509 certificate in your environment so are typically replaced yearly by commercial certificate authorities such as Digicert.
How will I know if my SAML application’s signing certificate is about to expire?
You are required to check the date of expiry of the certificate that is currently active inside your IdP’s SAML application.
Citrix Cloud will display a warning on your SAML IDP connection within Identity and Access Management > Authentication on the SAML connection 30 days before your SAML application’s signing certificate expires.
Click manage Certificates to be redirected to the View > SAML connection page where you can upload a new or remove an expired certificate.
Citrix Cloud will also display an error on the SAML connection if the IdP certificate has actually already expired as shown below. An expired IdP certificate renders the SAML connection unusable until the certificate is replaced.
Can I update the SAML IdP certificate while still using the Citrix Cloud SAML connection without triggering an outage?
Yes. The introduction of a second IdP certificate to the SAML IdP connection allows for seamless SAML application certificate rollovers. Upload the new certificate at least 24 hours before the current certificate expires. Your Workspace end users or Citrix Cloud admin users should be unaffected provided you have followed this article correctly.
Where do I obtain a copy of the latest Identity Provider (IdP) signing certificate from my SAML application?
Certificates used within on-premise SAML IdPs such as PingFederate are obtained from either private certificate authorities within your organization or from commercial certificate authorities like Digicert. Cloud-based SAML IdP SAML apps can generate new IdP certificates on demand at any time within the SAML app UI. New IdP signing certificates can be generated at any time and set to Inactive.
Can Citrix Cloud trust two different IdP signing certificates at the same time?
Yes. Seamless IdP certificate rollovers depend on this. Citrix Cloud SAML connections trust SAML responses. These responses must be signed with either of the two trusted IdP signing certificates that have been uploaded into the SAML connection. If one of the certificates has expired it can no longer be trusted by Citrix Cloud and should not be used by your SAML application anymore.
Citrix Cloud SAML connections can store either one or two SAML application certificates.
Slot1: contains the certificate you uploaded into the Citrix Cloud SAML connection when you first created it. This certificate needs to be replaced before it expires to prevent outages.
Slot2: is always empty after your SAML connection has been created but can be used to upload a new SAML app certificate before the certificate in Slot1 expires. It is intended to provide an alternative trusted certificate to take over from the expiring Slot1 signing certificate.
How can I tell which IdP signing certificate my SAML application is currently using to sign the SAML response?
Your SAML application uses only one certificate at a time to sign the SAML response. It uses the certificate that is currently set as active in your SAML application. The active IdP signing certificate is also present in the SAML application metadata.
The screenshots below show examples from Entra ID.
The screenshot below shows an example from Okta.
Perform a SAML Application IdP Certificate Rotation as a Scheduled Maintenance Task
Important:
At least one of your IdP certificates within your SAML Connection must be in date and active within your IdP to prevent an outage. If you have just a single IdP certificate configured within the Citrix Cloud certificate and that certificate expires, your users will experience an outage and your SAML logon will fail. This situation impacts Workspace users or Citrix Cloud admin users depending on how your SAML connection is used.
-
Plan to perform the IdP certificate rotation several days before the date of expiry of your current certificate.
-
Obtain a copy of the replacement IdP certificate from within your SAML application that you want to rotate to. Ensure the IdP certificate is in either PEM, CER or CRT format ready for upload into your Citrix Cloud SAML connection.
-
Upload the replacement IdP certificate into your Citrix SAML connection at least 24 hrs before you want to trigger the rotation of the certificate within your SAML application.
Navigate to your SAML connection inside Identity and Access Management > Authentication. Select the 3 dots on a SAML connection with a certificate expiring in the next 30 days and Click View.
Or,
Click Manage certificates.
-
Upload the second IdP certificate using the Slot2 upload option within the Citrix Cloud SAML connection.
-
Save the SAML connection after you have uploaded the new certificate.
-
Wait approximately 24 hours then perform the rollover action inside your IdP and set the secondary IdP certificate to active. The method to rollover the certificate is different for every SAML IdP.
Important:
Citrix’s authentication platform performs caching of all IDP settings for resiliency and performance reasons. You cannot upload the replacement certificate into Citrix Cloud and then immediately rotate the certificate within your SAML application due to cached values. A delay between upload of the new certificate and activation of the new certificate within your SAML app is required. This delay allows the Citrix authentication cache to be updated with the newly uploaded certificate. A 24-hour delay is longer than the TTL value of the cache. This duration ensures that the new certificate is available when the SAML application switches to use it the next day.
Entra ID SAML Application:
Okta SAML Application:
-
Test the SAML logon succeeds using either your Workspace URL and/or the Citrix Cloud SAML Sign In URL and check the value of the signing certificate inside the SAML assertion.
Upload a Secondary SAML IdP certificate to an existing Workspace Custom Domain SAML connection?
If you are required to update the IDP certificate in use by a secondary SAML application that is configured to support a Workspace Custom domain then follow the same steps as documented above.
- Navigate to Workspace Configuration > Access > Custom Workspace URL > Select the 3 dots > Edit.
Troubleshooting IdP Signing Certificate Rotations
If you encounter any SAML logon issues after performing an IdP certificate rotation then collect a SAML tracer file and examine the certificate base64 data inside the SAML response.
-
Start the SAML tracer capture before entering either the Workspace URL or Citrix Cloud GO URL into your browser. Ensure you capture the entire authentication process from start to end.
-
Perform a SAML logon to either Workspace or Citrix Cloud using your IdP and complete the authentication step when you are prompted for credentials.
-
Locate the SAML response from your IdP sent to the Citrix Cloud SAML endpoint
https://saml.cloud.com/saml/acsand the entry inside SAML tracer file here.
-
Locate the certificate section within the SAML XML and copy the IDP signing certificate’s base64 data to a suitable tool to decode it.
Important:
This step assumes that you have followed Citrix’s SAML recommended configuration and used HTTP POST as the SAML binding within your Citrix Cloud SAML Connection.
-
Decode the certificate from its base64 data and check it corresponds to the active certificate in the SAML IdP with the correct date and time.
-
If the certificate obtained from the SAML response in steps 4 and 5 is not as expected, activate the correct certificate inside your IdP. Check the active certificate within your SAML application. This certificate is included in the SAML response.