Update the Service 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.
Service Provider signing certificate
This certificate is provided by Citrix via the Citrix Cloud SAML metadata and is updated during the advertisement phase of the SP signing certificate rotation. This occurs at least once per calendar year.
SAML signing certificates need to be rotated before their expiration date occurs to give Citrix Cloud adminstrator’s time to prepare for deployment. Certificate rotation is required by both Service Providers and Identity Providers to ensure alignment and prevent any downtime.
If a selected SAML provider does not support automated rotation of the SP SAML signing certificate, a manual rotation of the SAML signing certificate within your SAML provider must be performed in order to replace the expiring certificate.
Important:
All existing guides within this SAML eDoc section include details of how to configure signing on both sides of the SAML connection. Citrix only recommends signed SAML configurations as these are more secure and are required by some SAML providers for logout (SLO) to succeed.
FAQ
What is SAML signing?
The SAML Protocol uses messages to request authentication and to send assertions of identity. The security of these messages depends on both transport and message level security. The messages are XML documents which are signed in accordance with the XML Signature syntax. This provides both integrity assurance of the message, but also authentication of the sender by proving they hold the private key. The trust model is described by: SAML Security and Privacy Considerations. The public keys used to define which private keys are trusted can be distributed in any suitable format. Citrix uses X.509 certificates as suitable containers to distribute and consume keys.
What is SAML signed request enforcement?
Just because Citrix Cloud is configured to send signed requests within the SAML connection this does not guarantee that the SAML provider will enforce the use of signatures and reject any unsigned incoming SAML requests. Most SAML IdPs have an option to enforce signed requests. If an unsigned request to log into the SAML provider is received then the SAML logon will fail. Some SAML IdPs like Duo do not even offer this option. It is the responsibility of the SAML IdP admin to check the status of the SAML IdP configuration. Citrix support does not control or have any visibility of whether signed requests are enforced within your SAML application.
How frequently does Citrix rotate its Service Provider SAML signing certificate?
In order to allow plenty of overlap between the active Service Provider signing certificate and the newly issued one, Citrix rotates the Service Provider signing certificate approximately every 11 months. This is to ensure a valid certificate is available to Citrix Cloud customers 30 days before the new certificate is to be activated.
What is the Service Provider SAML signing certificate advertisement phase?
During the advertisement phase the current and replacement SAML signing certificates will be present in the Citrix Cloud metadata. Only the active certificate can be used for SAML request verification until the rotation date and time. This is the date and time specified within the Citrix Cloud emails and Citrix Cloud console notifications.
Important:
The date of signing certificate expiry is not the same as the date of activation. It is the activation date that the Citrix and IdP admins need to pay attention to NOT the date of certificate expiry. The Citrix Cloud signing cert will always be rotated before it expires.
You can check the advertisement and activation date and time using this link Rotation plan.
The date and times are provided as Unix epoch time stamps for each event in the service provider signing certificate rotation process.
Use Epoch converter to convert unix epoch time stamps into a human readable date and time format.
Why has Citrix decided to use a self signed Citrix Cloud SAML signing certificate rather than a certificate signed by a public certificate authority such as Digitcert?
The Issuer: within the latest version of the SAML signing certificate you should upload into your SAML applications is now “samlsigning.cloud.com, Citrix Systems Inc.” instead of a public certificate authority like Digicert. The use of self signed SP signing certificates is to mitigate against a known SAML vulnerability with externally issued certificates, referred to as “Silver SAML”.
Why have I received a notification via email and within the Citrix Cloud console indicating that the current Citrix Cloud SAML signing certificate is about to expire and must be replaced?
SAML providers (IdP) require a valid and in date certificate to verify the signature of incoming SAML requests from Service Providers such as Workspace and the Citrix Cloud console. Citrix Cloud customers using SAML for Workspace or Citrix Cloud console logon will be contacted to advise them of an imminent SAML signing certificate rotation.
How do I know if my Citrix Cloud customer is affected by the Citrix Cloud SAML signing certificate rotation or not?
This will affect Citrix Cloud customers with the following SAML configuration.
- Your SAML connection within Citrix Cloud is configured with Sign Authentication Requests = Yes
- You have configured your SAML provider such as Azure Active Directory, ADFS, or Okta to reject unsigned SAML requests (signing enforcement).
- You have Single Logout (SLO) configured within your Citrix Cloud SAML connection and within your SAML provider. SLO requests need to be signed as part of security best practice.
How do I check the signing configuration of my Citrix Cloud SAML connection?
Navigate to Identity and Access Management > SAML 2.0 > View to check if you have Sign Authentication Requests enabled within your Citrix Cloud SAML connection. All new SAML connections within Citrix Cloud will default to Identity Provider Sign Authentication/Logout Requests = Yes for both logon (SSO) and logout (SLO).
How do I check whether signing enforcement is configured within my SAML app?
This varies depending on the SAML provider you are using. All Citrix documented SAML solutions include steps to enable Signing Enforcement as part of security best practice.
EntraID Signing Enforcement Example:
Okta Signing Enforcement Example:
Where do I obtain a copy of the latest Service Provider (SP) signing certificate?
This certificate is provided by Citrix through the Citrix Cloud SAML metadata and is updated periodically during the advertisement phase of the SP signing certificate rotation. This occurs at least once per calendar year.
US, EU, and APS: https://saml.cloud.com/saml/metadata
JP: https://saml.citrixcloud.jp/saml/
GOV: https://saml.cloud.us/saml/metadata
When is it safe to remove the old Citrix Cloud SAML signing certificate if my SAML app supports multiple verification certificates?
Only remove the old Citrix Cloud signing certificate from your SAML applications after the certificate activation date and time given in the email and Citrix Cloud console notification. Some SAML IdPs such as Okta only allow one signing certificate to be uploaded at a time. In this situation there is no choice but to overwrite the current certificate with the new one after the activation date and time. This should not be done before the activation date and time.
Use metadata exchange to automatically update the SAML Provider with the latest Citrix Cloud SP SAML Signing Certificate
Using SAML metadata exchange, the SAML provider consumes the Citrix Cloud SAML metadata automatically by monitoring the metadata URL, such as https://saml.cloud.com/saml/metadata. If your SAML provider supports SAML metadata exchange, then the SP signing certificate might already be updated automatically. Verify that your SAML provider supports metadata exchange. Afterward, you can verify whether the update has occurred before the current SAML signing certificate expires.
Important
There is a large amount of variation regarding the SAML features that each third-party SAML provider supports. It is the Citrix Cloud administrator’s responsibility to know and understand the capabilities and requirements of the SAML provider you are using. This is necessary to ensure that both the Citrix Cloud SAML connection configuration (SP) and SAML provider (IdP) configuration match. Refer to your SAML provider’s documentation to determine if it supports signature verification and whether SAML requests and responses need to be signed.
Manually update the SAML Provider with the latest Citrix Cloud SP SAML Signing Certificate
Important
SP Certificate rotation must be done every time a new certificate is published from Citrix Cloud otherwise SAML logon will be impacted and you will incur downtime.
-
Acquire the latest SAML metadata from Citrix Cloud by viewing your current SAML connection within Identity and Access Management, click Authentication, select SAML Connection and click View. The following image is an example of what this file might look like for Citrix Cloud regions such as US, EU and APS:
https://saml.cloud.com/saml/metadata
In this metadata XML file example, there are two x.509 Citrix Cloud SAML signing certificates.
- It is possible to extract the x.509 certificate from the metadata by uploading the XML file to a third-party tool or providing the metadata URL.
- Navigate to https://www.rcfed.com/SAMLWSFed/MetadataCertificateExtract
-
Enter the SAML metadata URL that corresponds to your Citrix Cloud customer region:
- US, EU and APS: https://saml.cloud.com/saml/metadata
- JP: https://saml.citrixcloud.jp/saml/metadata
- GOV: https://saml.cloud.us/saml/metadata
Download the SAML signing certificate from https://www.rcfed.com/SAMLWSFed/MetadataCertificateExtract.
-
Upload the newly extracted Citrix Cloud SP SAML certificate to your SAML provider. This process will be different for every SAML provider. Verify the proper SP signing certificate rotation procedure using your specific SAML provider documentation.
Depending on your SAML provider, the existing SAML signing certificate might need to be replaced by the new one. In some cases, the SAML provider might support multiple SP signing certificates at the same time, thus only uploading the new one will be enough. It is recommended you remove the old certificate once it has expired.
Upload a replacement Citrix Cloud SAML signing certificate to your Azure Active Directory SAML application
Before configuring the Azure Active Directory SAML app, see SAML Request Signature Verification for more information.
- Navigate to Azure Active Directory, select Enterprise Applications and click Your SAML App.
-
Locate the SAML certificates section within the SAML application.
-
Select Upload Certificate and upload the replacement Citrix Cloud SAML signing certificate obtained from the SAML metadata.
Note:
Azure Active Directory SAML apps can have multiple signing verification certificates configured so it is possible to upload a replacement certificate long before the current certificate has expired. The following screenshot shows two valid certificates. One of the certificates is due to expire in the near future. Provided at least one of the uploaded certificates is valid and has not yet expired, a SAML login to Citrix Workspace and Citrix Cloud will continue to succeed and you will not experience an outage.
Important:
Do not remove the existing verification certificate until after the SAML rotation date and time given in the email and Citrix Cloud console notification has passed. The new Citrix Cloud certificate becomes active only on the date and time given within those two notifications.
Upload a replacement Citrix Cloud SAML signing certificate to your Okta SAML application
Okta does not support multiple SP SAML signing certificates at the same time. You have no choice but to overwrite the existing Citrix Cloud SP signing certificate you are currently using with the new one. It is recommended you do this in a scheduled maintenance window.
-
Navigate to Applications, select Applications and search for your Okta SAML App
-
From General, navigate to SAML Settings, click Edit, select Configure SAML, select Show Advanced Settings, and click Signature Certificate in order to upload a replacement. Okta does not display the current Citrix Cloud SAML signing certificate in the upload UI. It will only display the replacement certificate after this has been uploaded.
-
Select Signature Certificate, click Browse Files and upload the replacement Citrix Cloud SAML signing certificate obtained from the Citrix Cloud SAML metadata.
Important
Do not overwrite the existing verification certificate until the SAML rotation date and time given in the email and Citrix Cloud console notification. The new Citrix Cloud certificate only becomes active on the date and time given within those two notifications.
In this article
- Service Provider signing certificate
- FAQ
- Use metadata exchange to automatically update the SAML Provider with the latest Citrix Cloud SP SAML Signing Certificate
- Manually update the SAML Provider with the latest Citrix Cloud SP SAML Signing Certificate
- Upload a replacement Citrix Cloud SAML signing certificate to your Azure Active Directory SAML application