mTLS with digital signature
Depending on the API capability, the use of a mTLS with a digital signature may be required. This article provides instructions for making requests to J.P. Morgan APIs by using mTLS and a digital signature, if applicable.
Before you start
It is required you have:
- Have an account on the J.P. Morgan Payments Developer Portal. For instructions, see Get started with the Payments Developer Portal.
- Create a developer project and add the applicable API products.
- Belong to a J.P. Morgan client organization.
- Have the private key associated with your mTLS certificate.
To invoke an API call, you must belong to a JPMC client organization and obtain security credentials, including a client certificate and private key. After activating your account, you will see your dashboard and be ready to proceed.
Obtain an mTLS certificate
You can obtain an mTLS certificate in either of the following ways:
- Obtain a certificate from a J.P. Morgan-approved Certificate Authority (CA) and upload it to the Payments Developer Portal.
- Submit a Certificate Signing Request (CSR) through the Payments Developer Portal for issuance by the J.P. Morgan Private CA.
Use an approved certificate authority
If you use an external CA, follow its instructions to generate your certificate.
Your certificate must meet J.P. Morgan’s certificate requirements and chain to an approved root and intermediate certificate. For supported certificate authorities, see Authentication.
After your CA issues the certificate, follow the steps in the Add an externally issued mTLS certificate section.
Request a certificate from the J.P. Morgan Private CA
The J.P. Morgan Private CA issues certificates for mTLS client authentication.
This option does not support digital signature certificates. If your API requires a digital signature, obtain and add a separately issued digital signature certificate as described in the Add your digital signature certificate section.
Prepare your CSR
Generate the private key and Certificate Signing Request (CSR) within your organization.
Keep the private key secure. Do not include private key material in the CSR or share your private key with J.P. Morgan.
Your CSR must:
- Include country, state or province, locality, organization, organizational unit, and common name in the certificate subject.
- Use a common name of 64 characters or fewer containing only letters, numbers, hyphens, and dot separators.
- Use a domain associated with your organization.
- Not include a subject alternative name or wildcard.
Use a different common name for Client Testing and Production.
You can use an existing authorized domain or one of its subdomains. For a new domain, the Payments Developer Portal validates that the domain is associated with your organization using the email domains of your Access SA and API security contacts.
Submit your CSR
- In the Payments Developer Portal, navigate to the Security page for your project.
- Select the applicable environment.
- Select Add mTLS, and then choose the CSR option.
- Upload and submit your CSR.
The Payments Developer Portal validates the CSR. If validation is successful, the portal issues and installs the mTLS certificate in real time.
You don’t need to upload the certificate after it’s issued.
Add an externally issued mTLS certificate
Complete this procedure only if you obtained your mTLS certificate from an external CA. If you requested the certificate from the J.P. Morgan Private CA, the Payments Developer Portal installs it for you.
- In the Payments Developer Portal, navigate to the Security page for your project.
- Select the applicable environment.
- In the Request section, select Add Security.
- For Certificate use, select mTLS.
- Drag-and-drop the certificate into the certificate upload area, or browse for the certificate.
- Select Add Certificate.
The dialog closes, and the mTLS certificate appears on the Security page.
A maximum of two active certificates can have the same common name.
Add your digital signature certificate
If your API requires a digital signature, add a separately issued digital signature certificate. The digital signature helps confirm the integrity and authenticity of your request.
- In the Payments Developer Portal, navigate to the Security page for your project.
- Select the applicable environment.
- In the Request section, select Add Security.
- For Certificate use, select digital signature.
- Drag-and-drop the certificate into the certificate upload area, or browse for the certificate.
- Select Add Certificate.
The dialog closes, and the digital signature certificate appears on the Security page.
You can add up to two digital signature certificates.
Call a J.P. Morgan API
After you configure the required certificates, you can make requests to J.P. Morgan APIs.
The request format depends on whether the API capability requires a digital signature.
Make a request without a digital signature
If your API doesn’t require a digital signature, use your mTLS certificate and its associated private key to establish the connection.
curl --request GET \
--url <API-endpoint> \
--header "Content-Type: application/json" \
--cert <mTLS-certificate-file> \
--key <mTLS-private-key-file>Replace the variables as follows:
<API-endpoint>: The endpoint for the API operation.<mTLS-certificate-file>: The file containing your mTLS certificate.<mTLS-private-key-file>: The private key associated with your mTLS certificate.
For an operation that requires a request body, include the payload using the appropriate cURL option:
--data '<JSON-payload>'Replace <JSON-payload> with the request body required by the API operation.
Use the media type specified in the API documentation. For example, an API that accepts JSON typically uses:
Content-Type: application/jsonSend the request and review the API response.
Make a request with a digital signature
If your API requires a digital signature, create a signed JSON Web Signature (JWS) payload using the private key associated with your digital signature certificate.
The signing process uses the RS256 algorithm.
Generate the signed JWS payload
To generate the JWS:
- Convert the JSON payload to a UTF-8-encoded string.
- Apply Base64 URL encoding to the payload.
- Create the JWS header and set its alg parameter to RS256.
- Apply Base64 URL encoding to the JWS header.
- Sign the encoded header and payload using the private key associated with your digital signature certificate.
- Construct the JWS in the following format:
<encoded-header>.<encoded-payload>.<encoded-signature>Java example
The following Java example retrieves the private key from a file, signs the encoded data using the private key, and constructs the JWS containing the signed payload.
import java.security.InvalidKeyException;
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.PKCS8EncodedKeySpec;
import java.io.IOException;
import org.apache.commons.io.IOUtils;
/* Retrieve the Private Key from a file */
public PrivateKey getPrivateKey(String privateKeyFileName)
throws IOException, NoSuchAlgorithmException, InvalidKeySpecException {
byte[] keyBytes = IOUtils.toByteArray(getResource(privateKeyFileName).getInputStream());
PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
KeyFactory kf = KeyFactory.getInstance("RSA");
return kf.generatePrivate(spec);
}
/* Sign the data using the private key that is stored in keyFile path */
public byte[] signPayload(String encodedPayload, String keyFileName)
throws InvalidKeyException, Exception {
Signature rsa = Signature.getInstance("SHA256withRSA");
rsa.initSign(getPrivate(keyFileName));
rsa.update(encodedPayload.getBytes());
return rsa.sign();
}
/* Construct the JWS with the signed payload */
public void generateJWS(DigitalSignature sig) throws InvalidKeyException {
String encodedHeader = encodeBase64URL(getHeader());
String encodedBody = encodeBase64URL(getBody());
String jws = encodedHeader.concat(".")
.concat(encodedBody).concat(".")
.concat(encodeBase64URL(signPayload(
encodedHeader.concat(".").concat(encodedBody),
getKeyFileName())));
}Run the code and copy the resulting signed JWS payload.
Send the signed request
Use the signed JWS as the request body:
curl --request POST \
--url <API-endpoint> \
--header "Content-Type: application/jose" \
--cert <mTLS-certificate-file> \
--key <mTLS-private-key-file> \
--data '<signed-JWS-payload>'Replace the variables as follows:
<API-endpoint>: The endpoint for the API operation.<mTLS-certificate-file>: The file containing your mTLS certificate.<mTLS-private-key-file>: The private key associated with your mTLS certificate.<signed-JWS-payload>: The output from your JWS-signing implementation.
Use the media type specified in the API documentation. APIs that accept a signed JWS payload commonly use:
Content-Type: application/joseSend the request and review the API response.