How to Rotate Your Foundry Certificate

This page contains instructions for rotating the Foundry X.509 certificate. You must perform steps 4, 5 and 6 below 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.

If your identity provider does not support multiple signing certificates, then you should perform Steps 4 and 5 at the same time, or at least as soon as possible, to minimize downtime for single sign-on.

We highly recommend testing single sign-on and single logout after each update in Steps 4, 5 and 6 as described in Step 7.

• Step 1: Save the current EVERFI X.509 Certificate file
• Step 2: Identify where the IDP uses Foundry Certificate
• Step 3: Download the new Foundry Certificate 
• Step 4: Update IAM System
• Step 5: Update IDP Configuration in Foundry
• Step 6: Remove Old Certificate From Identity Provider
• Step 7: Test the Update
  
  

See  this article for answers to frequently asked questions around certificate rotation.

See this article for answers to frequently asked questions around Single Sign on. 

 

 

Step 1: Save the current 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.

Step 2: Identify the places where your IDP uses 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.

Caution: Be sure that you rotate only the EVERFI Foundry certificate. Do not make any changes to settings in your identity provider or in Foundry to your organization’s own certificate, which is different. In single sign-on, both the identity provider (your organization) and the service provider (Foundry) has their own separate certificates. This process pertains only to the Foundry certificates.

Question: What if my identity doesn’t reference the Foundry certificate at all?
Answer: While not common, some identity providers do not use a service provider certificate at all. In that case, there is no certificate to rotate. If this is the case, then skip ahead to Step 5.

Question: I’m not very familiar with how my identity provider works. Is there a way to know for sure whether or not my identity provider uses the Foundry certificate?
Answer: There isn’t an absolute failsafe way to determine this for certain. You will need to work with you identity provider vendor to know for sure.

Step 3: Download the new Foundry Certificate

Log in as an admin to Foundry’s customer admin portal and navigate to Settings → Single Sign-on, click View EVERFI SAML Metadata, then click Download encryption certificate.

Download the Foundry SAML 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.

Step 4: Update IAM 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.

If you normally sign in to Foundry via SSO and you have the Use SSO Exclusively option enabled, then after performing Step 4, you may not be able to sign back into Foundry for Step 5. If this is the case, then before you do Step 4, temporarily disable Use SSO Exclusively and make sure you can sign in to Foundry with a Foundry username and password instead of SSO. Alternately, just before doing Step 4, first sign into Foundry and make sure you are ready to do Step 5 right after Step 4 so you don’t get logged out.

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:

1. 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.

2. 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.

Step 5: Update IDP 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.
 

1. Log in as an admin to Foundry’s customer admin portal and navigate to Settings > Single Sign-on, and edit your Identity Provider.
2. View the list of identity providers in Foundry and edit it.
3.  In the identity provider page, select the newest EVERFI SAML Certificate.
4.  Change the Foundry certificate in your identity provider.
5. 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.

Step 6: Remove Old Certificate From Identity Provider

In your identity provider, in the service provider entry for Foundry, remove any references to the old certificate while keeping the new  certificate. Make sure you remove the correct one.

Step 7: Test the Update

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.