April 29, 2024
Author: Mark Dear
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 periodically and uploaded into your SAML application or obtained via the Citrix Cloud SAML metadata.
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 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?
SAML signing certificates are X.509 certificates used to verify data sent between the Service Provider (SP) and SAML provider (IdP). Your SAML provider (IdP) uses the Citrix Cloud SAML signing certificate to verify the signature sent by Citrix Cloud within its SAML authentication request. Citrix Cloud uses the SAML provider signing certificate to verify the SAML response came from a trusted and connected IdP.
What is SAML signed request enforcement?
Just because Citrix Cloud is configured to send signed requests this does not guarantee that the SAML provider will enforce the use of signatures and reject any unsigned incoming SAML requests. Most SAML providers have an option to enforce signed requests meaning if an unsigned request to log into the SAML provider is received then the logon will fail. It is the responsibility of the SAML provider admin to check the status of the 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 existing certificate expires.
What is the Service Provider SAML signing certificate advertisem*nt phase?
During the 30 day advertisem*nt phase both the current and replacement SAML signing certificates will be present in the Citrix Cloud metadata and both are valid and can be used. Once the current certificate expiry date passes it will be removed from the Citrix Cloud metadata.
Why have I received a notification via email and within the Citrix Cloud admin 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 administrator console. Citrix Cloud customers using SAML for Workspace or Citrix Cloud admin 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 (signed request enforcement).
- You have Single Logout (SLO) configured within your Citrix Cloud SAML connection and within your SAML provider. Your SAML provider might require SLO requests to be signed such as for Okta and PingFederate.
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. Some might not even offer this option. AzureAD, ADFS, Okta, and PingFederate all support signing enforcement. It is critical the SAML admin be aware of the capabilities of your SAML provider and its current configuration. Citrix support has no control or visibility of this.
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 advertisem*nt phase of the SP signing certificate rotation. This occurs at least once a 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
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 x509 Citrix Cloud SAML signing certificates.
- It is possible to extract the x509 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
- 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.
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.
