Note: The 2023 Certificate Rollover is complete. This article is presented here for archival purposes.
Vault is scheduled to roll over the certificate used to sign SAML Single Sign-on (SSO) requests and Spark messaging connections.
What Action is Required?
SAML SSO with Vault uses SAML 2.0 standards. As part of this standard, Vault digitally signs authentication requests to the identity provider (IdP). This occurs during a Vault-initiated login, which is when the user visits Vault and is redirected to the IdP.
In a Vault-initiated login, your IdP requires Vault’s service provider certificate (SP certificate) to verify our signature. This means when Vault changes SP certificates, you must provide the new certificate to your IdP for this step to work.
Manually uploading the new certificate is not always required. Some IdPs can discover the certificate dynamically based on the SP Metadata URL configured in the SAML profile. Please contact your IdP provider for more detailed, IdP-specific instructions as needed. The table below describes whether action is required for some of the most popular IdPs used with Vault:
SAML SSO
| Third-Party IdP | Action |
|---|---|
| Microsoft ADFS | Action required: Upload the new SP certificate to ADFS. During the rollover period, ADFS can support two certificates (old and new) at the same time. |
| Microsoft Azure AD | No action required on the Identity provider side. |
| Okta | No action required on the Identity provider side. |
| PingFederate | Optional: See PingFederate’s documentation. |
Spark Messaging
Vault digitally signs all outbound Spark messages with the signing certificate. For external connections, the external application verifies this signature to ensure the received message is the expected secure Spark message from Vault.
When Vault rolls over certificates, the code for your external application to verify the message signature should not require changes. However, it’s possible that your external application has cached the old signature. Customers should ensure that the external application receiving Spark messages has not cached the old signature. Learn more about the code required to verify the message signature in the Developer Portal.
The following table illustrates whether action is required for different types of Connection records which utilize Spark messaging:
| Connection | Action |
|---|---|
| External | Ensure that the external application receiving Spark messages has not cached the old signature. |
| Vault to Vault | No action needed. |
| Local | No action needed. |
When Do I Need to Take Action?
You can also find the following dates on Veeva Trust:
| Date and Time | Event | Action |
|---|---|---|
| February 3, 2023 7:00 pm PT (February 4, 2023 03:00:00 UTC) | New Certificate Publishing The new certificate is available to download. You can download and begin testing with the new certificate. |
Test the new certificate by configuring Vault and your IdP to use the new certificate. We also recommend checking the Include SP Certificate in the SP Initiated requests option on all SAML profiles. |
| From February 3, 2023 7:00 pm PT (February 4, 2023 03:00:00 UTC) To March 3, 2023 6:00 pm PT (March 4, 2023 02:00:00 UTC) |
New Certificate Testing Period You can test the new certificate during this period. Both the old and new certificates are supported. |
Continue testing the new certificate. When ready, configure your production Vault to use the new certificate. |
| March 3, 2023 6:00 pm PT (March 4, 2023 02:00:00 UTC) | New Certificate Rollover with Rollback Option Vault automatically upgrades all Vaults to use the new signing certificate on all SAML profiles and Spark connections. |
If you run into issues, you can roll back your certificate to the old certificate. |
| From March 3, 2023 6:00 pm PT (March 4, 2023 02:00:00 UTC) To March 24, 2023 6:00 pm PT (March 25, 2023 01:00:00 UTC) |
Support for New and Old Certificate To provide time for additional testing, both the old and new certificates are supported. |
If you rolled back your certificate, test your SAML SSO profiles and Spark messaging integrations and configure the new certificate as soon as possible. |
| March 24, 2023 6:00 pm PT (March 25, 2023 01:00:00 UTC) | Final Certificate Rollover The old signing certificate is no longer supported. For any Vaults which rolled back to the old certificate, Vault automatically upgrades all Vaults to use the new signing certificate. If your new certificate is not yet configured, you may experience blocking issues. |
If you run into issues, configure your new certificate as soon as possible. |
Why is Action Required?
If you do not test and configure the new certificate in time, you may run into blocking issues when Vault automatically upgrades to the new certificate.
SAML SSO
Failure to configure the new certificate for SAML profiles may block Vault users from logging in. Vault users who have SAML SSO profiles which are not configured to use the new certificate may see this message when attempting to log in:
If this occurs during the New Certificate Rollover with Rollback Option period, a Vault Admin can immediately allow users to log in by rolling back the user’s SAML SSO profile to the old certificate. Admins must then test and configure the new certificate before the Final Certificate Rollover date.
If this occurs after the Final Certificate Rollover, users will be unable to log in until the new certificate is configured. Admin must configure the new certificate with their IdP.
Spark Messaging
If your external Spark messaging integrations are not prepared to use the new certificate, these integrations may begin failing when Vault upgrades to the new certificate. Integration failures may be highly disruptive to business processes.
If integration failures occur during the New Certificate Rollover with Rollback Option period, a Vault Admin can immediately unblock the integration by rolling back the Connection to the old certificate. Admin must then test and configure the new certificate before the Final Certificate Rollover date.
If this occurs after the Final Certificate Rollover, the Spark messaging integration will continue to fail until the new certificate is configured.
How to Update your Vault Configuration for the New Certificate
Vault Admins must configure their Vault’s affected SAML SSO profiles or Connection records to use the new certificate.
SAML SSO
To configure your SAML SSO profile with the new certificate:
- From Vault Admin, navigate to Settings > SAML Profiles and select a profile.
- Click the Edit button.
- In the SP Certificate section, select the checkbox next to the new certificate. If you need to provide this certificate to your IdP, you can click the download icon next to the certificate.
- If your IdP allows it, we highly recommend checking the Include the SP Certificate in the SP initiated request checkbox.
- Click Save to activate the selected certificate.
Spark Messaging
To configure your Connection records with the new certificate:
- From Vault Admin, navigate to Admin > Connections and select a Connection record.
- From the Actions menu, select Manage Signing Certificate.
- From the Manage Signing Certificate dialog, select the checkbox next to the new certificate. If you need to download the new certificate, click the Download icon.
- Click Save to activate the new certificate for Spark messaging.
How to Configure the New Certificate with your IdP
The new certificate must be configured on your provider’s system prior to the initial rollover event. Download the Vault Signing Certificate and provide it to your IdP.
Please contact your IdP admin for details on the process to update the certificate on their servers. Some SAML SSO IdPs can automatically update to the new SP certificate, but some cannot. If you have other questions, contact Veeva Support.
How to Roll Back to the Old Certificate
If you run into issues during the certificate rollover, a Vault Admin can quickly roll back to the old certificate within the Vault UI without involving the IdP Admin. While we recommend configuring your IdP profile as soon as possible, we understand you may need to unblock your users or Spark messaging integrations as quickly as possible.
SAML SSO
To roll back to the old certificate for your SAML SSO profile:
- From Vault Admin, navigate to Settings > SAML Profiles and select a profile.
- Click the Edit button.
- In the SP Certificate section, select the checkbox next to the old certificate.
- If your IdP allows it, we highly recommend checking the Include the SP Certificate in the SP initiated request checkbox.
- Click Save to activate the selected certificate.
If you rolled back your certificate, you must configure the new certificate before the Final Certificate Rollover.
Spark Messaging
To roll back your Connection records to the old certificate:
- From Vault Admin, navigate to Admin > Connections and select a Connection record.
- From the Actions menu, select Manage Signing Certificate.
- From the Manage Signing Certificate dialog, select the checkbox next to the old certificate.
- Click Save to activate the old certificate for Spark messaging.
If you rolled back your certificate, you must configure the new certificate before the Final Certificate Rollover.
Does this affect Veeva Snap or other mobile applications?
No. Veeva Snap leverages OAuth / OpenID Connect, not SAML. The certificate rollover does not impact Veeva Snap, Vaut Mobile, or any other mobile applications.
Can I test this on pre-release Vaults?
Yes. The New Certificate Testing Period is applicable to all Vaults, including pre-release, general release, and limited release Vaults.