How to generate a self-signed certificate for Salesforce SAML integrations

Background

When integrating Salesforce with single sign-on (SSO) a typical use-case is to use the SAML protocol.  By default, Salesforce generates the SAML service provider metadata using a certificate that expires in 1 year.  CalNet will ask that you instead configure a 10 year self-signed certificate.

Rationale:

In SAML, the certificate in the metadata is primarily used to verify the integrity and authenticity of SAML assertions or messages. It's not used for establishing an initial trusted connection, as is the case with SSL/TLS. Since the metadata exchange is typically pre-trusted, a self-signed certificate serves the purpose.  SAML metadata doesn't change frequently, and we want to avoid frequent updates to certificates. Using a long-lived certificate reduces the administrative overhead of changing metadata and propagating those changes between identity providers and relying parties.  It also reduces potential downtime for applications.

Further reading:  https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631506/SecurityAndNetworking#Keys-and-Certificates

Process

Salesforce requires an outdated and deprecated certificate container format.   If you do not feel comfortable following these steps, please reach out to CalNet for help generating the certificate when you request your SSO integration.

Important:  The keystore file you will generate contains a sensitive private key.  Please treat the generated file as a secret, do not attach it to any tickets or correspondence.  After you upload the file into Salesforce be sure to delete the file from your workstation.

1. Install Java so that you have the keytool application.
2. Open a command line and run the following command, replacing the alias name with something that makes sense for your site.
   
   

   keytool -genkeypair -keyalg RSA -keysize 4096 -validity 3650 -alias mysalesforcesite -keystore keystore.jks -storetype jks

    

3. You will be prompted for a keystore password, enter something memorable and store this in a safe place.
4. When prompted for "first and last name" enter the alias you used for step 2.  For example: "mysalesforcesite"
   
   

   Enter keystore password:
   Re-enter new password:
   What is your first and last name?
     [Unknown]:  mysalesforcesite

    

5. You can fill in the remaining questions using the examples provided below.  None of these are critical.
   
   

   What is the name of your organizational unit?
     [Unknown]:  IT
   What is the name of your organization?
     [Unknown]:  University of California, Berkeley
   What is the name of your City or Locality?
     [Unknown]:  Berkeley
   What is the name of your State or Province?
     [Unknown]:  CA
   What is the two-letter country code for this unit?
     [Unknown]:  US
   Is CN=mysalseforcesite, OU=IT, O="University of California, Berkeley", L=Berkeley, ST=CA, C=US correct?
     [no]:  yes

    

6. Answer "yes" after validating the certificate name.
7. When prompted for the "key password", just press <RETURN> without typing anything in.
   
   

   Enter key password for <mysalesforcesite>
           (RETURN if same as keystore password):

    

8. Ignore the warning message.
9. You now have a file named "keystore.jks".
10. Log into your Salesforce Service Console.
11. Within the Service Console, click on the gear icon at the top right and select Setup.
    
    
    
    
12. Navigate to Settings > Security > Certificate and Key Management.
    
    
    
    
13. Select Import from Keystore.
    
    
    
    
14. On the import screen, select Browse and select the keystore.jks file you generated earlier.  Enter the password you used when generating the file and then click Save.
    
    
    
    
15. You should now see your imported certificate.
    
    
    
    

New SSO Settings

Follow these steps if you are creating a new SSO integration.

1. Navigate to Settings > Identity > Single Sign-On Settings.
2. Create a new SSO setting.
   
3. For the Request Signing Certificate select the certificate you just created.
   
   
   
   
4. Click Save.
5. Select the Single Sign-On setting by clicking on the Name link.
   
   
   
   
6. Select Download Metadata.  Provide this file in your SSO Service Request to CalNet.
   
   

Existing SSO Settings

If you are updating the certificate for an existing SSO integration follow these steps to ensure you do not have a service interruption.

1. You should still see the new certificate you created, for example:
   
   
2. Click on the underlined certificate name, in the example above that would be mysalesforcesite.
3. You will be taken to the Certificate and Key Detail page.  Select Download Certificate.
   
   
4. Open a service request with the CalNet team to change an existing SSO integration.
5. When the service request form loads, select "Change to existing SSO integration" in the first drop down box.
6. In the description field enter something like "I would like to rotate the SAML certificate with the new certificate provided below:"
7. Open the downloaded certificate, note that the first line must be -----BEGIN CERTIFICATE----- and last line must be -----END CERTIFICATE-----.  This is the public cert and is safe to share.
   
8. Copy and paste that certificate into the same description field of the service request or attach the file to the service request.
   
9. Fill out the rest of the service request form, including the Entity ID.
10. CalNet will add the new certificate to your registration, keeping the old certificate in place.
11. After CalNet confirms that the new certificate is registered go back to your Salesforce settings.
12. Navigate to Settings > Identity > Single Sign-On Settings.
13. Edit the SSO Settings.
14. For the Request Signing Certificate select the new certificate.
    
    
15. Click Save.
16. Test authentication to your site using an incognito/private browser window.  If you see an error you can revert to the old certificate and open an incident with CalNet to trouble-shoot.