Key Pair
A Key Pair is the mathematical pairing of a public key and a private key used in asymmetric cryptography (also called public-key cryptography).
Definition
A Key Pair is the mathematical pairing of a public key and a private key used in asymmetric cryptography (also called public-key cryptography). The public key can be shared openly and is used to encrypt data or verify signatures; the private key is kept secret and is used to decrypt data or generate signatures. The pair is generated together such that operations performed with one can only be reversed with the other: data encrypted with the public key requires the private key to decrypt, and signatures made with the private key can only be verified with the matching public key.
In Salesforce, key pairs underpin several integration patterns. JWT-based OAuth flows use key pairs: Salesforce holds the public key to verify the JWT signature; the integration holds the private key to sign the JWT. SAML SSO uses key pairs for signature verification: the Identity Provider signs assertions with a private key; the Service Provider verifies with the matching public key. Mutual TLS (mTLS) for callouts uses key pairs to authenticate both client and server. Understanding the asymmetric model is foundational for any Salesforce integration architecture work.
How Key Pairs work in Salesforce integrations
Symmetric versus asymmetric encryption
Symmetric encryption (AES) uses one key for both encryption and decryption; both parties must share the same key, which makes key distribution a challenge. Asymmetric encryption uses a key pair: the public key is freely shared; the private key never leaves its owner. Asymmetric is slower than symmetric but solves the key distribution problem. Most real systems use hybrid: asymmetric to negotiate a session key, symmetric for bulk encryption. TLS works this way.
Key pair generation
Key pairs are generated together by a cryptographic library. The most common algorithm is RSA (typically 2048-bit or 4096-bit keys). Modern alternatives include ECDSA (elliptic curve, smaller key size for equivalent security) and Ed25519. Salesforce supports RSA key pairs for most integration scenarios. Key pairs cannot be modified after generation; you generate, use, and eventually rotate to a new pair.
Public key for verification
Public keys are stored in certificates: an X.509 certificate wraps the public key with metadata (subject name, issuer, validity period). Certificate Authorities (CAs) sign certificates to vouch for their authenticity, producing a trust chain. For integrations where both parties cooperate, self-signed certificates are sometimes acceptable; for public-facing scenarios, CA-signed certificates are standard.
Private key custody
The private key must never leak. Compromise of the private key allows attackers to impersonate the key's owner. In Salesforce, private keys for outbound integrations are stored in the Certificates and Key Management setup area (Setup > Security > Certificate and Key Management). The platform stores them encrypted; export is restricted. For inbound scenarios where Salesforce signs (acting as IdP), the platform manages the private key entirely without exposing it.
JWT OAuth flow
The JWT OAuth flow lets an integration authenticate to Salesforce without a user-facing login. The integration generates a JWT, signs it with their private key, and submits it to Salesforce's token endpoint. Salesforce verifies the signature using the public key stored in a Connected App configuration. If the signature is valid and the integration is authorized, Salesforce issues an access token. The pattern enables server-to-server integration without exposing user credentials.
SAML signature verification
SAML SSO involves the IdP signing assertions with a private key; the SP verifies with the matching public key embedded in the IdP's metadata. Salesforce-as-IdP holds the private key; downstream SPs hold the public key. Salesforce-as-SP holds the public key of the external IdP. Rotation of either side requires coordination: the new public key must be deployed to the verifier before the new private key is used.
Rotation and operational discipline
Key pairs rotate on a schedule, typically annually or per the certificate's expiration. Rotation requires coordination: generate the new pair, deploy the new public key to verifiers, switch to signing with the new private key, retire the old. The rollover window where both pairs are active is when integrations transition cleanly without downtime. Plan rotations as scheduled maintenance with clear runbooks.
Set up a key pair for JWT OAuth
Setting up a key pair for a Salesforce integration is a coordinated effort across the integration side and the Salesforce configuration. The steps below cover the standard JWT OAuth flow setup.
- Generate the key pair
On the integration side, generate an RSA 2048-bit (or stronger) key pair. OpenSSL command: openssl req -newkey rsa:2048 -nodes -keyout private.key -x509 -days 365 -out public.crt
- Secure the private key
Store the private key in a secure vault on the integration side. Restrict file permissions; rotate the wrapping passphrase if applicable.
- Create a Connected App
Setup > App Manager > New Connected App. Enable OAuth. Upload the public certificate (public.crt). Configure scopes (api, refresh_token, etc.) and Use Digital Signatures.
- Approve the Connected App
Edit Policies > Permitted Users > Admin approved users are pre-authorized. Assign profiles or permission sets that should be able to use this Connected App.
- Build the JWT in the integration
Construct a JWT with iss (Connected App consumer key), sub (Salesforce username), aud (login URL), exp (expiration). Sign with the private key. Submit to the token endpoint.
- Verify the flow works
Test the full flow end-to-end. Confirm Salesforce returns an access token and the integration can call subsequent APIs.
- Plan rotation cadence
Set a calendar reminder for key pair rotation. Annual is common; align with certificate expiration. Coordinate the rollover with the integration team to avoid downtime.
Standard key size. Sufficient for most enterprise use cases.
Stronger key. Slower but more resistant to future cryptanalysis.
Elliptic curve. Smaller key size for equivalent security.
Acceptable for cooperating internal integrations. Public-facing scenarios need CA signing.
Signed by a Certificate Authority. Standard for public-facing scenarios.
- Private key leakage is catastrophic. Treat private key storage with the same rigor as production passwords; use vaults, restrict permissions.
- Smaller key sizes (1024-bit RSA, deprecated algorithms) are rejected by modern security policies. Use 2048-bit RSA or stronger.
- Rotation requires coordination across both sides. New public key must be deployed before the new private key is used; otherwise verification fails.
- Certificate expiration is the silent killer of integrations. The integration works until the day the certificate expires; set monitoring well before expiration.
- Self-signed certificates do not provide third-party trust. Acceptable for cooperating internal scenarios; not for public-facing.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Key Pair?
Q2. What's a common Salesforce use of key pairs?
Q3. How should private keys be managed?
Discussion
Loading discussion…