SfSkills Domains Docs GitHub

Home / security / certificate-and-key-management

certificate-and-key-management

Use this skill when creating, uploading, or rotating certificates in Salesforce, configuring mutual TLS (mTLS) client authentication, managing the Java KeyStore for CA-signed certificates, diagnosing certificate expiry. NOT for Shield Platform Encryption key management or Named Credential setup — use integration/named-credentials-setup.

Open the skill folder on GitHub

Certificate and Key Management

This skill activates when an org needs to create, upload, rotate, or diagnose certificates in Salesforce's Certificate and Key Management UI (Setup > Security > Certificate and Key Management). It covers self-signed and CA-signed certificates, mutual TLS client authentication, Java KeyStore management, and safe certificate rotation procedures. It does NOT cover Named Credential configuration (use the named-credentials-setup skill), and it does NOT address Shield Platform Encryption tenant secret management (use the platform-encryption skill).

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Self-Signed Certificates

Self-signed certificates are generated directly in Salesforce Setup under Certificate and Key Management. Salesforce creates the certificate and private key internally; the private key never leaves Salesforce storage.

Key facts:

CA-Signed Certificates

CA-signed certificates are signed by a trusted Certificate Authority (e.g., DigiCert, Entrust, Let's Encrypt, or an internal enterprise CA). The process in Salesforce has two paths:

Path 1 — Salesforce generates the CSR:

  1. In Setup > Certificate and Key Management, create a new certificate and choose "CA-Signed Certificate."
  2. Salesforce generates a Certificate Signing Request (CSR) and holds the private key internally.
  3. Submit the CSR to your CA. The CA returns a signed certificate file.
  4. Upload the signed certificate back into the same Salesforce record to activate it.

Path 2 — Upload an externally generated certificate and key pair:

  1. Your security team generates the key pair and CSR externally (e.g., using OpenSSL).
  2. The CA signs the CSR and returns a certificate chain.
  3. Assemble the certificate, private key, and any intermediate CA certificates into a Java KeyStore (JKS) file or PKCS#12 file.
  4. Convert to JKS if needed (see Keystore Management section below).
  5. Upload via Setup > Certificate and Key Management > "Import from Keystore."

CA-signed certificates are required for any mTLS flow where the external system validates the client certificate against a known CA trust store, which is the standard for enterprise and government API gateways.

Mutual TLS (mTLS) Client Authentication

In standard TLS, only the server presents a certificate. In mTLS, both client and server present certificates to authenticate each other. In the Salesforce context:

Certificate Rotation

Certificates expire. Rotating them without downtime requires:

  1. Create the new certificate first — before touching anything in production. Generate or upload the replacement certificate in Salesforce and confirm it is valid.
  2. Update all references — find every connected app, Named Credential, Apex callout configuration, or external system that uses the old certificate. Update them to point to the new certificate. For JWT flows: update the connected app's consumer key/secret and upload the new public certificate to the connected app.
  3. Coordinate with the external system — if the external system trusts your certificate explicitly (common with mTLS), they must add trust for the new certificate before you switch. Request this in advance with enough lead time.
  4. Deactivate the old certificate — after confirming the new certificate is working in production, delete or archive the old certificate. Do not delete it immediately after cutover; wait at least 24–48 hours to catch any missed references.
  5. Confirm the platform's own expiry notifications are reaching a monitored inbox. Salesforce does email certificate-expiration warnings — at 60 days, 30 days and 10 days before expiry, and on the day of expiry. Configure who receives them via the expired-certificate notification permission (Setup > Certificate and Key Management → "Set Expired Certificate Notification Permission"). The common failure is not that the platform is silent; it is that the notifications land on a departed admin's address or in an unmonitored alias. A calendar reminder is a useful belt-and-braces addition on top of a working notification channel, not a substitute for one you wrongly believe is missing.

Common Patterns

Pattern 1: JWT OAuth Flow — Self-Signed Certificate Rotation

When to use: A server-to-server integration using the JWT Bearer OAuth flow has a self-signed certificate approaching expiry, or the certificate has already expired and the integration is failing with authentication errors.

How it works:

  1. In Setup > Certificate and Key Management, create a new self-signed certificate with an appropriate expiry. Give it a distinct name (e.g., jwt_auth_v2).
  2. In Setup > Apps > Connected Apps, open the connected app used by the integration.
  3. Under "Use Digital Signatures," upload the public certificate of the new self-signed certificate (download it from Certificate and Key Management using the "Download Certificate" button).
  4. If the integration server generates the JWT locally using the Salesforce-held private key (via Apex Auth.JWT), update the Apex code or Named Credential to reference the new certificate name.
  5. Test the JWT flow end-to-end in a sandbox before cutting over in production.
  6. After confirming production success, delete the old certificate or let it expire naturally.

Why not just re-use the old certificate name: Salesforce certificates have immutable validity periods. You cannot extend an existing certificate's expiry. A new certificate must be created.

Pattern 2: CA-Signed Certificate Upload for mTLS Client Authentication

When to use: An external API gateway requires Salesforce to present a CA-signed client certificate during mTLS handshake, and the security team manages the PKI externally.

How it works:

  1. Obtain the signed certificate chain (leaf cert + any intermediate CA certs) and the private key from your PKI team.
  2. Assemble the JKS keystore:
    # Convert PEM cert + key to PKCS#12 first
openssl pkcs12 -export \
  -in salesforce_client.crt \
  -inkey salesforce_client.key \
  -certfile intermediate_ca.crt \
  -out salesforce_client.p12 \
  -name "salesforce-mtls"

# Convert PKCS#12 to JKS
keytool -importkeystore \
  -srckeystore salesforce_client.p12 \
  -srcstoretype PKCS12 \
  -destkeystore salesforce_client.jks \
  -deststoretype JKS
  3. In Salesforce: Setup > Certificate and Key Management > Import from Keystore. Upload the JKS file and provide the keystore password.
  4. The certificate now appears in Certificate and Key Management with the alias you assigned.
  5. Reference this certificate in the Named Credential's "Client Certificate" field (see named-credentials-setup skill) or in the connected app's mTLS configuration.
  6. Retain the original .p12 and .jks files in your secure vault. Once imported, the private key cannot be retrieved from Salesforce.

Keystore Management

Java KeyStore (JKS) is the format Salesforce's UI uses for CA-signed certificate import. Key operational notes:

Decision Guidance

SituationRecommended ApproachReason
JWT-based server-to-server OAuth, private key managed by SalesforceSelf-signed certificate generated in SetupSalesforce holds the private key; CSR process not needed; simpler to create
mTLS client auth where external system validates against a CA trust storeCA-signed certificate uploaded via JKS importExternal API gateways reject self-signed certs unless explicitly trusted
mTLS where external system will explicitly trust any cert you provideSelf-signed certificate is acceptableSimpler; eliminates CA dependency; external team adds your public cert to their trust store
SAML assertion signing for SSOSelf-signed certificate (Salesforce-generated) or CA-signedSalesforce-generated is standard; CA-signed required if your IdP enforces CA validation
Certificate needs to be migrated to another org or sandboxCA-signed (Path 2 with external key): migrate the JKS file. Self-signed: impossible — private key cannot be exportedSelf-signed certs are org-bound; CA-signed certs with external key generation are portable
Integration failing with auth errors and certificate is older than 1 yearRotate: create new self-signed cert, update connected app, test, cut overDefault self-signed expiry is 1 year; expired certs cause immediate auth failures

Step-by-step instructions for an AI agent or practitioner working on certificate management:

  1. Identify the certificate's role — determine whether the cert is used for JWT OAuth, mTLS outbound client auth, mTLS inbound (connected app trust), or SAML. The role dictates the certificate type and where it must be configured.
  2. Inventory existing certificates — navigate to Setup > Security > Certificate and Key Management and list all certificates, their expiry dates, and any certificates that appear in connected apps or Named Credentials. Check the 50-certificate org limit.
  3. Create or obtain the certificate — for self-signed: generate directly in Setup. For CA-signed: either generate a CSR in Setup and get it signed, or assemble the JKS from an externally generated key pair using the openssl and keytool commands in the Keystore Management section.
  4. Update all references before deactivating the old certificate — for JWT flows: update the connected app's digital signature. For mTLS: update Named Credentials and coordinate with the external system to trust the new cert. Never delete the old cert before confirming the new one works.
  5. Test end-to-end in a lower environment — for JWT: trigger the OAuth flow and confirm a valid access token is returned. For mTLS: make an authenticated callout through the Named Credential and confirm a 200 response from the external system.
  6. Cut over production and monitor — update production references, monitor integration logs for authentication errors for 24–48 hours, then deactivate the old certificate.
  7. Record expiry dates and set calendar reminders — Salesforce sends no automatic expiry alerts. Track expiry dates in your operations runbook or monitoring tool.

Review Checklist

Run through these before marking certificate setup or rotation complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Private key is permanently non-exportable after import — When you import a JKS containing a private key into Salesforce, the private key cannot be retrieved from Salesforce under any circumstances. There is no export function in the UI or API. If the source keystore is lost, the certificate's private key is gone. Always retain the JKS file externally before importing.
  2. Certificates cannot be deployed via Metadata API or SFDX — The Certificate metadata type exists in the Metadata API, but it only deploys the public certificate, not the private key. Full certificate migration between orgs (e.g., sandbox to production) requires manual re-import of the JKS in each target org. Automated deployment pipelines cannot carry certificates. Teams that assume certificates deploy automatically are surprised when integrations fail post-deployment.
  3. Salesforce sends no certificate expiry notifications — Unlike some certificate management systems, Salesforce does not send email alerts or platform notifications as a certificate approaches its expiry date. The first sign of an expired certificate is often a broken integration or failed OAuth flow. Expiry tracking must be implemented externally (calendar reminder, monitoring script, or a third-party tool).
  4. CN mismatch causes mTLS handshake failure with no clear error message — When Salesforce presents a client certificate during mTLS, the external API validates the CN/SAN against its expected value. If there is a mismatch, the TLS handshake fails before any HTTP response is sent. The Salesforce debug log shows a generic callout exception, not a CN mismatch error. Always verify the CN with the external system's API team before uploading.
  5. Self-signed certificates are org-bound and cannot be migrated — Salesforce generates the private key for self-signed certificates and never exposes it. This means a self-signed certificate created in a sandbox cannot be migrated to production. Each org needs its own self-signed certificate. For JWT flows, the connected app in production must have the production org's certificate public key uploaded, not the sandbox certificate.

Output Artifacts

ArtifactDescription
Certificate rotation runbookStep-by-step procedure for rotating a specific certificate with zero-downtime sequencing, pre/post-validation steps, and rollback guidance (see templates/)
Certificate inventoryTable of all org certificates with expiry dates, assigned integrations, and renewal owner
JKS assembly commandsOpenSSL and keytool commands customized for the specific certificate chain being imported
mTLS coordination checklistList of items to align with the external API team (CN/SAN, CA trust, testing schedule)

Package files