When you configure EVERFI Foundry as a service provider in your identity management system, you will provide the Foundry X.509 public certificate that you get from the SAML metadata file you download from Foundry’s platform, or from downloading the certificate directly.
Every X.509 certificate has an expiration date. To safeguard the security and integrity of your members’ data, you should use Foundry’s newest certificate. Moreover, if you continue to use an expired certificate, errors may occur. Therefore, be sure your Foundry service provider configuration always has an active Foundry X.509 certificate.
Around three months before the Foundry certificate expires, EVERFI releases a new replacement certificate. Between that release and the expiration of the predecessor certificate, both certificates are active and supported. During this three-month window, Foundry clients using the older certificate must rotate to the new certificate. EVERFI will contact every client who is using an older certificate to alert you when the new certificate is released, and follow up several times with each client until everyone has rotated from the older to the newer certificate.
If you are currently live with an older Foundry X.509 certificate, and you are ready to update to the newer certificate, follow these instructions.
These instructions may vary based on your organization’s own identity management solution.
Foundry Certificate History
Immediate Predecessor Certificate
How to Rotate the Foundry Certificate
This page contains instructions for rotating the Foundry X.509 certificate. You must perform steps 4, 5 and 6 in that order for single sign-on to operate without disruption.
If your identity provider is able to add two signing certificates to a service provider like Foundry, for example Microsoft ADFS and Shibboleth, then be sure to follow the variations that pertain to that capability. This variation enables you to perform these steps with no interruption to single sign-on, and you are not required to perform the updates in your identity provider and Foundry at the same time, giving you flexibility in scheduling the different steps of the rotation.
You can determine if this is possible by going to a service provider in your identity provider and checking to see if you are able to add multiple signing certificates, or if you are limited to at most one signing certificate. While the SAML specification allow for multiple signing certificates, some identity provider products do not provide that feature. If you aren’t sure, then follow the standard directions.
Video series of how to rotate the EVERFI Foundry SAML certificate – Introduction
1. Save the older EVERFI X.509 Certificate file
Before making any changes, keep handy the older Foundry SAML X.509 certificate file you use today, in the unlikely event that you need to roll back your changes.
You may already have this certificate from when you first configured EVERFI as a service provider in your identity access management solution, or you may be able to extract/download it from the current service provider configuration in your system. If not, you can get the certificate from the link above on this page.
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 1
2. Identify the places in your Identity Provider that use the Foundry Certificate
Note the places in your identity management system that currently use the Foundry certificate, so you’ll know exactly where you need to make these updates. Depending on your identity provider and how you have configured the EVERFI service provider, the EVERFI certificate might be present in one or multiple settings. Generally, a SAML service provider may use a certificate for two separate but related functions: signature and encryption. While some applications use a different certificate for each function, Foundry uses the same certificate for both functions. When you update the Foundry certificate, be sure to update it in every place your identity system uses it.
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 2
3. Download New Foundry Certificate
Put the downloaded certificate file in a location that is accessible to your identity provider. For example, if your identity provider is located on a remote server, you will need to put that file where it can be accessed.
Note: some identity providers may require the encoded certificate text, but not a file. In this case, Copy the certificate text and paste it into a text editor (using a program that will not auto-format the text) for later use.
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 3
4. Update your Identity Access Management System
In your identity access management system’s service provider configuration for Foundry, update that configuration to have the newer Foundry certificate in all the place(s) the certificate is used. Depending on your specific identity provider and configuration, you will likely need to update the signing certificate and encryption certificate.
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 4 in Microsoft ADFS
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 4 in Okta
Variation for identity providers that support multiple signing certificates for a service provider – if your identity provider has this capability, then perform the following two updates:
- Add the new Foundry certificate as a second signing certificate. Do not remove the old Foundry certificate from the list of signing certificates; you will do that in the next step.
- If your identity provider encrypts its SAML messages, then replace the encryption certificate with the new Foundry certificate. If you do not encrypt, then skip to the next step.
5. Update Identity Provider configuration in Foundry
As soon as you update your identity access management solution to use Foundry’s latest X.509 certificate, you will need to make a corresponding update in Foundry to indicate which EVERFI certificate your identity provider is using, the old or the new.
Login as an admin to Foundry’s customer admin portal and navigate to Settings → Single Sign-on, and edit your Identity Provider:
In the identity provider page, select the newest EVERFI SAML Certificate.
After updating this setting to use the newer certificate, go to the bottom of the page and press Save to save your identity provider settings in Foundry.
Note: if your identity provider allows a service provider to have multiple signing certificates, and you performed that variation of update in the prior step, then you need to perform this step, but it doesn’t have to be done immediately. Single sign-on and single logout will operate continuously even if the updates in this step are not performed right away. You do still need to perform this update prior to the expiration of the old certificate, and we recommend doing it as soon as practical. It has been observed that some identity provider systems may require some additional time for the newly added signing certificate (added in Step 4) to be recognized because of caching or other delays. If this is the case for your identity provider product, then you may need to allow for sufficient time between steps 4 and 5, or else manually restart your identity provider services to accelerate this. EVERFI cannot advise you on how to do this in your system but we raise this issue based on a few observations from Foundry customers.
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 5
Do Not Change Your Own Certificate in Foundry
6. Remove the Old Signing Certificate from Your Identity Provider
This step is relevant only if your identity provider allows a service provider to have two or more signing certificates and you didn’t remove the old Foundry signing certificate in the previous step. Otherwise, skip this step.
In your identity provider, in the service provider entry for Foundry, remove the old signing certificate while keeping the new signing certificate. Make sure you remove the correct one.
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 6
7. Test the Update
Last, test single sign-on scenarios, including a sign-in initiated from the identity provider website, and also from the service provider (Foundry) if you have enabled SSO initiated from the service provider.
Also test single logout if you have this enabled, testing SLO initiated from Foundry and from your identity provider, as applicable.
Video series of how to rotate the EVERFI Foundry SAML certificate – Step 7
Q: I have a couple of certificate files. How can I figure out which one is which?
A: Open the file in a text editor that won’t try to format the certificate as though it’s a normal document. Then go here https://www.sslshopper.com/certificate-decoder.html and follow the instructions. See certificate history for a list of EVERFI Foundry X.509 certificates.
Q: We use InCommon with Foundry. How will the certificate rotation be handled?
A: EVERFI is rotating all the InCommon entries and the related Foundry configuration in December 2020 through January 2021. This time period is normally a less active time in the academic year so any potential disruption to single sign-on at that time should be minimal. See Foundry SAML Certificate Rotation for InCommon Members for more details.
Q: My own organization’s x509 certificate is expiring. How do I update this in Foundry?
A: Log in to Foundry as an administrator and navigate to Settings –> Single Sign-On. Edit your identity provider configuration. Copy the certificate text or fingerprint and update the field. Save the IDP configuration. Be sure to make any necessary updates to the Foundry service provider entry in your identity provider at the same time.
Q: Which EVERFI products does this apply to?
A: EVERFI has single sign-on in various products, but the information on this page applies only to Foundry, which also include our Financial Education elective learning platform.
A: If your identity provider does not use the Foundry certificate at all for token encryption or for validating the signature in Foundry’s SAML messages, then there is no need to update your identity provider, however we request that you update your Foundry identity provider configuration to the latest Foundry certificate as described in step 5 above. This way EVERFI will know that you have completed the process and are not using the older certificate at all.
Q: I have multiple identity providers in Foundry. How do I manage that?
A: For each identity provider configuration you have in Foundry, you will need to rotate the certificate.
Q: The expiration date has passed by we haven’t rotated our certificate. What’s going to happen?
A: First of all, please rotate your certificate as soon as possible.
We cannot say for sure what will happen because each identity provider is different. Foundry will not stop SSO from happening if the Foundry certificate is expired, but your identity provider might not allow SSO to succeed if the Foundry certificate is expired.
Q: My identity provider does not encrypt the SAML Assertion, so we do not need to rotate the encryption certificate because there is no encryption. How does that affect Foundry certificate rotation?
A: You will still need to rotate to the new certificate for signing even if you are not encrypting.
Q: My identity provider encrypts the SAML Response’s Assertion with the Foundry X.509 certificate. How does Foundry decrypt?
A: In Foundry, there is an identity provider settings that describes your identity provider to Foundry. In those settings, there is a field for the Foundry certificate. Based on that setting, Foundry digitally signs its outgoing SAML messages (
LogoutResponse) with that certificate. Your identity provider should use the Foundry signing certificate(s) it stores with the Foundry service provider to validate the signature.
For encryption, Foundry will attempt to decrypt the identity provider’s SAML Assertion with that same Foundry certificate, with one variation: if Foundry cannot decrypt successfully, and if that certificate is not the newest certificate, then Foundry will attempt a second chance decryption with Foundry’s newest certificate.
The rationale for this support for up to two encryption certificates is that it gives you the ability to stagger the steps in certificate rotation. You can perform step 4 above (update your identity provider to use the newest certificate for signing and encryption) without having to make an immediate update in the Foundry identity provider settings at the same time, as long as your identity provider can have two or more signing certificates.
This is especially helpful if you have one person who needs to update your identity provider (steps 4 and 6), and a different person who needs to update Foundry (step 5). With this methodology, it’s OK if these steps have hours, days or even weeks between them, as long as you complete Step 5 prior to the expiration of the outgoing Foundry certificate; Step 6 is essentially housekeeping. Single sign-on will operate continuously without interruption.
Q: Why is the Foundry x509 certificate date range two years?
A: The steps are different for the signing certificate and the encryption certificate and you need to provide the Foundry certificate only in certain conditions.
If you have single logout enabled, then you must rotate the signing certificate. See steps 17-27 in the instructions on Foundry Single Sign-on with Okta. Also, see How to replace a Service Provider Signing Certificate In OKTA in Okta’s help site. This page refers to the signing certificate of a service provider like EVERFI.
If you have opted to encrypt your SAML Response Assertions, then you must rotate the encryption certificate. To replace the encryption certificate with the newer Foundry certificate, go to the same page as above and follow the similar steps for the Encryption Certificate. This option is hidden unless you have set Assertion Encryption to “Encrypted”. If Assertion Encryption is “Unencrypted” then this means you are not encrypting the SAML response and you do not need to rotate the certificate for encryption.
To see how to do this, watch the video in Step 4.
Q: My identity provider is Microsoft Azure. How do I rotate the certificate?
A: On Foundry Single Sign-on with Microsoft Azure, download the instructions that explain how to rotate the Foundry certificate.
Q: After Foundry was switched to the new certificate, we started seeing 400 response errors from our identity provider during SSO initiated in Foundry. Why is this?
A: Your server or environment may have a size limit. The new Foundry certificate is larger than the prior certificate and might be tripping a limit that the previous certificate did not. The byte size of the querystring parameter that Foundry sends during SSO initiated in Foundry is more than 3,500 bytes. If you are able to attribute the error to this reason, then work with your IT staff to examine any potential size, querystring or packet limits and increase the limit.