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.
SAML Provider signing certificate
This certificate is provided by your SAML provider and uploaded into Citrix Cloud™ when you configure the SAML connection.
SAML signing certificates need to be rotated before their expiration date occurs to give Citrix Cloud admins time to prepare for deployment. Certificate rotation is required by both Service Providers and Identity Providers in order to ensure alignment and prevent any downtime.
FAQ
What is the SAML provider certificate used for?
The SAML provider certificate is used to verify the signature of SAML responses sent from the SAML provider to Citrix Cloud during the authentication process.
Where do I obtain a copy of the latest Identity Provider (IdP) signing certificate?
This certificate is provided by your SAML provider such as Azure AD, Okta, PingFederate, or ADFS. Citrix does not control the rotation and update of this certificate. This certificate is uploaded into Citrix Cloud when you initially create the SAML connection. The date of expiry on IDP Signing Certificates is usually long lived. They might need replacing every few years and at a lower frequency than the SP Signing Certificate
How will I know if my SAML provider signing certificate is about to expire and impact my Citrix Cloud SAML connection?
Citrix Cloud will display warnings 30 days before the date of expiry approaches for your SAML provider signing certificate.
Certificate Expiring Soon: <certExpirationDate>
It will also display an error once the certificate has actually expired as shown below.
Can I update the SAML provider certificate whilst still using the SAML connection without downtime?
No. It is necessary to perform a SAML disconnect and reconnect during a scheduled maintenance window. Update the Identity Provider (IdP) Signing Certificate
-
Select an alternative IdP within Workspace Configuration, select Authentication whilst you perform the SAML disconnect/reconnect operation such as Active Directory.
- Backup your existing GO URL such as
https://citrix.cloud.com/go/<yourgourl>used for SAML logon to Citrix Cloud. - Take a backup of your existing SAML endpoints. These can be copied from the Citrix Cloud console. Backup the following SAML endpoints from within your existing SAML connection.
Can I update the SAML IdP certificate while still using the Citrix Cloud SAML connection without triggering an outage?
Backup the EntityID, the SSO URL, and the logout URL.
> **Important:**
>
> Ensure you have a copy of both the existing and replacement IDP signing certificate before performing the disconnect. This is so you have the ability to rollback to the old certificate if the new SAML provider certificate is invalid and causes any logon issues. You will not be able to obtain a copy of the old certificate from the Citrix Cloud UI before performing the disconnect. You will need to obtain it from your SAML application.
- Disconnect SAML within Identity and Access Management, navigate to Authentication, select the SAML connection, Click the ellipse and select Delete Identity Provider
-
Reconnect SAML within Identity and Access Management and click Authentication
- Accept all of the default SAML connection settings.
- Reenter all of the SAML application endpoints you backed up earlier or obtain these again for your SAML app from within your SAML provider UI.
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.
When should I remove the “old” Identity Provider (IdP) signing certificate from my SAML connection inside Citrix Cloud?
The old Identity Provider (IdP) signing certificate should only be removed from the Citrix Cloud SAML connection AFTER you have proven that the “new” signing certificate has been activated within your SAML application AND you have successfully logged into Workspace and/or Citrix Cloud using it. It is easier to rollback a failed IdP certificate rotation maintenance task if both IdP certificates are still present in the Citrix Cloud connection. Citrix Cloud can trust both certificates provided they are both still in date. If the IdP certificate has already expired then rolling back to it is not possible.
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:
If you are using the Scoped EntityID feature, you will also need to update your SAML application with the new scope ID after performing the SAML disconnect/reconnect. For more information on the Scoped EntityID feature, see Configure a SAML application with a scoped Entity ID in Citrix Cloud. Copy the newly generated scope ID from the Citrix Cloud SAML UI and update your SAML application Entity ID with the replacement scope ID. EntityID should be updated to
https://saml.cloud.com/<new scope ID after reconnect>. ======= 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.