Configure mTLS
Set up Mutual Transport Layer Security (mTLS) on your Klarna account to add an extra layer of authentication on top of API key credentials, including issuing, enforcing, and rotating client certificates.
4 min read
Mutual Transport Layer Security (mTLS) is an enhanced communication security mechanism that adds extra layers of protection to make it more difficult for attackers to misuse leaked credentials. It ensures that both the client and server authenticate each other, making the communication more secure.
Klarna recommends Partners to enable mTLS to strengthen the security of their integration. mTLS can be enabled and enforced by the Partner at any time, on top of the standard API key authentication.
Configuration details
- Create and store your private key using elliptic curve cryptography with the
prime256v1specification.- Example: creation command for certificate key
BASH
1
2
openssl ecparam -genkey -name prime256v1 -out my-key-file.pem
- Create a Certificate Signing Request (CSR)
- The Common Name (CN) in the CSR is optional and can be any value of up to 64 characters.
- Without a valid CN, Klarna sets a default that is different for each certificate, for example
LYABCDEI-3f9a1c0b7d2e4a68. - Example: creating a Certificate Signing Request (CSR)
BASH
1
2
openssl req -new -key my-key-file.pem -out csr.pem -subj "/CN=LYABCDEI-mtls-1"
- With the Certificate Signing Request (CSR) previously generated, create a certificate using the createCredentialsClientCertificate
endpoint and the certificate will be returned in the API-response. Now your account is in an mTLS enabled state, but not enforced. This is done so that the status of the mTLS configuration can be verified safely before enforcing access. - Store the generated certificate and configure it to be used in your runtime environment together with the private key.
- Example using curl which will list the newly created certificate
BASH
1
2
curl --cert certificate.pem --key my-key-file.pem -H "Authorization: Basic $API_TOKEN" https://api-global.klarna.com/v2/account/integration/credentials/client-certificate
- After the certificate has been returned, the APIs will return a response header including the status of the mTLS verification. The header returned is
Klarna-Mtls-Verification-Statusand the value is one ofNOT_,PRESENT VALIDandINVALIDso that the configuration can be verified before enforcing. - When the integration has been set up and requests return
VALIDstatus it's time to enforce access security. This can be done using the enforceMTLSAuthorization endpoint.
- Example using curl to enforce mTLS to a specific time in the future.
- The
enforced_timestamp should meet the following criteria:from - The enforcement time cannot be in the past.
- The enforcement time can be
NOW. - The enforcement time must be less than 90 days in the future.
- Note: The enforcement takes up to 5 minutes from the configured timestamp.
- The response from the request shows the applied enforcement via status verbs,
ENFORCEDorREPORTING.
BASH
1
2
curl -X PUT --cert certificate.pem --key my-key-file.pem -H "Content-type: application/json" -H "Authorization: Basic $API_TOKEN" https://api-global.klarna.com/v2/account/integration/client-certificates/enforcement -d '{"enforced_from": "2027-01-15T09:00:00Z"}'
- There is a readMTLSAuthorizationEnforcementStatus endpoint available to get the enforcement status.
- Example using curl to get mTLS enforcement status.
- Make sure to use the certificate in the request if the enforcement time used in the previous step has passed.
BASH
1
2
curl -X GET --cert certificate.pem --key my-key-file.pem -H "Authorization: Basic $API_TOKEN" https://api-global.klarna.com/v2/account/integration/client-certificates/enforcement
- At the enforcement time the mTLS client certificate will be verified on all API-requests and the status header will stop being returned.
Disable mTLS enforcement for your Klarna account
- A scheduled mTLS enforcement can be removed with the removeEnforcementOfMTLSAuthorization endpoint before the enforcement time is reached. In the live environment it can't be removed through the API after that time, so contact Klarna support.
- Example using curl to delete mTLS enforcement.
BASH
1
2
curl -X DELETE --cert certificate.pem --key my-key-file.pem -H "Authorization: Basic $API_TOKEN" https://api-global.klarna.com/v2/account/integration/client-certificates/enforcement
Important notes
- CSR Requirements: The CSR should only include the CN and no extra attributes.
- Certificate Validity: The issued certificate is valid for 3 years. You need to monitor its expiration and initiate the renewal process in advance.
- Multiple Certificates: You can have up to 10 active certificates at a time.
- Revoking Certificates: Before revoking an active certificate, ensure a new certificate is issued and installed. Use the revokeCredentialsClientCertificate endpoint to revoke the certificate.
Certificate rotation process
- 1.Generate a new private key and CSR, and issue a new certificate with them. Klarna rejects a CSR that reuses the private key of an existing certificate.
- 2.Install and test the new certificate, ensuring it works correctly.
- 3.Revoke the old certificate using the Partner API after confirming the new one is functioning.
- 4.By following these steps, you can ensure a secure and smooth setup of mTLS for your Klarna account.
Jump to section...