Skip to main content

Certificate Rotation Guide

The digital certificate used for JWT Bearer authentication has an expiration date. When it approaches expiration, you need to rotate it by downloading a new certificate from aprity and uploading it to your Salesforce Connected App. This process requires no downtime.

When to Rotate​

Certificate expiration​

aprity sends email notifications when your certificate is approaching expiration:

  • 30 days before expiration -- Initial reminder.
  • 7 days before expiration -- Urgent reminder.

You can also check the certificate status in the aprity Settings tab, which displays the current certificate's validity period.

danger

If the certificate expires before rotation, aprity will be unable to authenticate to your Salesforce org. All scans, including scheduled scans, will fail until a new certificate is uploaded.

Proactive rotation​

You may also choose to rotate certificates proactively as part of your organization's security policy (for example, annual certificate rotation). The process is the same regardless of whether the current certificate has expired.

Rotation Steps​

Step 1: Download the new certificate from aprity​

  1. Open the aprity app in Salesforce.
  2. Navigate to the Settings tab.
  3. In the JWT Configuration section, click Download Certificate.
  4. Save the new .crt file to your computer.
info

Each time you click Download Certificate, aprity generates a new certificate and key pair. The previous certificate remains valid until its original expiration date, giving you time to complete the rotation.

Step 2: Upload the certificate to your Connected App​

  1. Go to Setup > App Manager in Salesforce.
  2. Find the aprity Connected App and click Edit.
  3. In the API (Enable OAuth Settings) section, locate the digital signature setting.
  4. Click Choose File and select the new .crt file you downloaded in Step 1.
  5. Click Save.
caution

Salesforce may take 2 to 10 minutes to propagate Connected App changes. Do not test the connection immediately after saving.

Step 3: Verify the connection​

  1. Wait at least 2 minutes after saving the Connected App changes.
  2. Return to the aprity Settings tab.
  3. Click Test Connection.
  4. Confirm that the connection test shows a green success message.

If the test succeeds, the rotation is complete.

Zero-Downtime Rotation​

Certificate rotation does not cause downtime because:

  • The new certificate is generated before the old one is replaced.
  • Salesforce accepts the new certificate as soon as the Connected App is saved.
  • Any scans in progress at the time of rotation continue using their existing access tokens, which remain valid until they expire naturally.

There is no need to pause scheduled scans or coordinate the rotation during a maintenance window.

Troubleshooting​

Connection test fails after uploading new certificate​

Wait longer. Salesforce Connected App changes can take up to 10 minutes to propagate. Retry the connection test after waiting.

"invalid_grant" error after rotation​

This typically means the new certificate was not uploaded correctly:

  1. Go to Setup > App Manager > aprity > Edit.
  2. Verify that Use digital signatures is still checked.
  3. Re-upload the .crt file.
  4. Save and wait 2-10 minutes before testing again.

Old certificate expired before rotation​

If the certificate has already expired:

  1. Follow the normal rotation steps above (Steps 1-3).
  2. Any scheduled scans that failed during the expiration window will not retry automatically. After the new certificate is in place, manually trigger a new scan or wait for the next scheduled run.

Multiple Connected Apps​

If your org has multiple Connected Apps (for example, from a previous aprity installation), ensure you are updating the correct one. The Connected App name should be aprity and should reference the Consumer Key shown in your aprity Settings tab.

Best Practices​

  • Set a calendar reminder 30 days before certificate expiration, even though aprity sends email reminders.
  • Document the rotation procedure in your org's runbook so any admin can perform it.
  • Test after every rotation -- always verify the connection from the aprity Settings tab.
  • Keep the old certificate file until the new one is confirmed working, in case you need to revert.