OAuth

J.P. Morgan uses OAuth 2.0 to enable third-party applications to obtain limited access to user accounts on an HTTP service. This process uses access tokens for authentication, instead of credentials, and grants permissions for information exchange through digital signatures.

Depending on the product and environment you use, the following different flavors of OAuth may be used.

Basic OAuth - When in the Mock environment, a client secret shared with J.P. Morgan is used for authentication.
OAuth with JSON Web Tokens (JWT) - When in the Client Testing and Production environments, JWT is used with modern APIs on the Payments Developer Portal to securely transmit information between parties as a JSON object with public key cryptography to avoid sharing a client secret with J.P. Morgan.
Legacy OAuth - When working with legacy APIs on the J.P. Morgan Developer Portal, you can generate a Certificate Signing Request (CSR) and use OAuth as an authentication method.

This page gives instructions for using the current version of OAuth dependent on your environment as well as the legacy version of OAuth.

Using OAuth in the Mock environment

To authenticate your requests in the Mock environment:

In the Payments Developer Portal, navigate to the Security page.
Select the Mock tab.
Use the provided credentials (Access token URL, Client Id, and Client secret) to retrieve an access token that will allow you to authenticate your requests. Refer to the Quick start guide for more details.

Using OAuth with JWT in the Client Testing and Production environments

The steps to authenticate your requests in the Client Testing and Production environment are the same. The following items, however, are different and must be unique for each environment:

Client certificates
Client IDs
Public keys
Private keys
API endpoints

The URI used to create access tokens is the same for both environments.

Tip

If you are using a CA signed X.509 certificate, it is your responsibility to ensure the certificate is updated before it expires. New certificates need to be provided to J.P. Morgan to prevent service interruptions.

To use OAuth with JWT for Client Testing and Production environment access, perform the following steps. Detailed instructions for each step are found in the sections that follow.

Generate an authority-signed or self-signed certificate.
Provide your OAuth certificate to J.P. Morgan by adding it to the Payments Developer Portal.
Sign a JWT.
Generate an access token.
Use the access token to send requests to the environment endpoints.

Generate a signed certificate

Generate an authority-signed certificate through a Certificate Authority (CA) or a self-signed certificate using the J.P. Morgan authentication utility or OpenSSL. For detailed instructions, see Authentication.

Add your OAuth certificate

Provide your signed OAuth certificate to prove identity and authorization:

In the Payments Developer Portal, navigate to the Security page.
For the environment you plan to use (Client Testing or Production), select the corresponding tab.
In the Request section, click Add Security.
The "Add certificate" dialog appears.
For the "Certificate use" dropdown, select OAUTH.
In the "Certificate upload" box, drag and drop, or browse for the desired certificate. Add up to five public key certificates here.
Click Add Certificate.
The "Add security" dialog closes.
The added OAuth certificate is listed.

Sign a JWT

To generate a signed JWT assertion, review the following JavaScript sample.

JavaScript code sample to generate a signed JWT assertion

Javascript

const getJwtHeader = (kid) => {
  return {
    'alg': 'RS256',
    'kid': kid
  }
}
const getJwtBody = (sub, jti) => {
  var currentTimestamp = Math.floor(Date.now() / 1000);
  const tokenLifetime = 30; // this is in seconds
  let jwtBody = {
    'iat': currentTimestamp,
    'exp': currentTimestamp + tokenLifetime,
    'expires_in': tokenLifetime,
    'sub': sub,
    'aud': 'https://login.test.jpmorgan.com/oauth2/token',
    'iss': sub,
    'jti': jti,
    'nbf': currentTimestamp
  };
  if (jti) {
    jwtBody['jti'] = jti; // optional unique id of this JWT assertion
  }
  return jwtBody;
}
const generateJWTJoseWithInput = async() => {
  const fs = require('fs').promises;
  const jose = require('jose');
  const options = {
    kid: { cliParamName: '--kid' },
    sub: { cliParamName: '--sub' },
    privateKey: { cliParamName: '--private_key_file' },
    jti: { cliParamName: '--jti' }
  };
  for (let i=0; i < process.argv.length; i++) {
    for (const [key, value] of Object.entries(options)) {
      if (value.cliParamName === process.argv[i]) {
        options[key].value = process.argv[i+1];
      }
    }
  }
  const fileToLoad = options.privateKey.value;
  const fileContents = await fs.readFile(fileToLoad, { encoding: "utf8" });
  const body = getJwtBody(options.sub.value, options.jti.value);
  const header = getJwtHeader(options.kid.value);
  const privateKey = await jose.importPKCS8(fileContents, 'RSA-SHA256');
  const signature = await new jose.SignJWT(body)
      .setProtectedHeader(header)
      .sign(privateKey);
  return signature;
};
var jwt = generateJWTJoseWithInput();
jwt.then(function(result) {
  console.log(result);
})

Here's an example of a command to run the JWT assertion code:

Example of a command to run the JWT assertion code

Plaintext

node sign_jwt_assertion.js --private_key_file ./try2.key --kid testKid --sub testSub --jti w00p

The following is an example of a JWT returned from the J.P. Morgan identity provider.

JWT returned from JWT authentication utility

Plaintext

eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3RLaWQifQ.eyJpYXQiOjE3MzA3MjgxNjUsImV4cCI6MTczMDcyODE5NSwiZXhwaXJlc19pbiI6MzAsInN1YiI6InRlc3RTdWIiLCJhdWQiOiJodHRwczovL2xvZ2luLnRlc3QuanBtb3JnYW4uY29tL29hdXRoMi90b2tlbiIsImlzcyI6InRlc3RTdWIiLCJqdGkiOiJ3MDBwIiwibmJmIjoxNzMwNzI4MTY1fQ.aZQDPMq3p0ew8WqSO1nHxR9OxiItoe-nKwLobKja73Chn1wfauIEyu2wNBSL9E-LCZ63taU8z-SnS52aszcvogPedZ0SGIv3qsaHB5AQKgkIn-vyEfisYTPlj6DSrL4tfEryuF-l-6Nq8djC4sFS27QmBBAjG9kpg8B7EXdWggILcz5fr05MJSWvan950LqkD9oDHW7PwiXzUydzkL446UCg-DH337QYpQcq_nVpyEIMty-56ZhQXXSzSNFoCH5kWUg0hcB7ON8KKVxaEqXE5AAazAg4uqEeUUbeWNKk1wYzhD_3A-GWd57Ac762JGl4hYdEBwW0yBQdDgnO6m3B9Q

Tip

Use jwt.io to look inside the token and see the decoded output.

Generate an access token

To generate an access token, send a POST HTTP request to the token URI with the header and body as follows.

Header

content-type: application/x-www-form-urlencoded

Body

grant_type — client_credentials.
client_assertion_type — urn:ietf:params:oauth:client-assertiontype:jwt-bearer.
client_assertion — This is the <signed JWT>. Ensure it does not contain any white spaces or new lines.
audience — Defines what API resource you want to request access.
scopes — Optional. Defines the capabilities on the API resource.

cURL to get a a bearer token under a specific audience

Curl

curl --request POST https://login.jpmorgan.com/oauth2/token --data "grant_type=client_credentials" --data "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" --data "audience=jpm:uri:prod:payments" --data "client_assertion=<JWT signed by client machine>"

Note

To define access to products within a platform, use scopes.

The following is an example of an access_token returned from the identity provider.

Example of an access token returned from the identity provider

Json

{
  "access_token": "eyJhbGciOiJFUzUxMiIsImtpZCI6IjY0YjlmOGQwLTU3MTktNDAzZi1hMjE5LTYzZTQ0NzFkMzY1OSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJqcG1jOnVyaTpwcm9kOnBheW1lbnRzOmNvbW1lcmNlIiwiYXV0aF90aW1lIjoxNzMxNTkxNTQzLCJleHAiOjE3MzE2MjAzNDMsImlhdCI6MTczMTU5MTU0MywiaXNzIjoiaHR0cHM6Ly9sb2dpbi5qcG1vcmdhbi5jb20vb2F1dGgyL3Rva2VuIiwianRpIjoiNTc0OTY4NWUtODRkMi00OWZiLTgyNGUtZWMzZjBkOGFjZDI4Iiwic2NvcGUiOiJvbmxpbmVwYXltZW50czphY2Nlc3MiLCJzdWIiOiI5ODljYzc3ZS0yNGEwLTQ4NjEtOWRjZC0xNWIwOTg2ZjRlODEifQ.xxxxx",
  "token_type": "Bearer",
  "expires_in": 28800
}

Use the access token

When sending an HTTP request to the project API, use the access token as the bearer token.

Example of cURL with bearer token

Curl

curl --request GET --url 'https://api.payments.jpmorgan.com/payment/helloworld' --header 'Accept: application/json' --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI9IwJEYXo0Ke5jZ0Y2eHRsY0RfVDl6bzFUU1BaCDJ8.eyJhdWQiOiJKU E1DOlVSSTpSUy0xMDMyNTctMjQ5KWEtQ29ubmVjdFBheW1lbnRzVWF0QXBwLVVBVCIsImlzcyI6Imh0dHA6Ly9pZGF1YXQuanBt b3JnYW5jaGFzZS5jb20vYWRmcy9zZXJ2aWNlcy90cnVzdCIsImlhdCI6MTU3NDM3MzU3NCwiZXhwIjoxNTc0NDAyMzc0LCJKUE1 DSWRlbnRpZmllciI6IkY2Nzc4NDQiLCJSb2xlIjpbIk1TQ29ubmVjdFVhdENvbnRyb2xHcm91cC0yNDk0MS0xMDMyNTctVUFUIi wiQ29ubmVjdFBheW1lbnRzVWF0QXBwX0FMTC0yNDk0MS0xMDMyNTctVUFUIl0sIkNsaWVudElQQWRkcmVzcyI6IjE3Mi4yNi4xN jMuMjMyIiwiYXV0aG1ldGhvZCI6WyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvYXV0 aGVudGljYXRpb25tZXRob2QvdGxzY2xpZW50IiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW5 0aXR5L2F1dGhlbnJqY2F0aW9ubWV0aG9kL3g1MDkiXSwiYXBwdHlwZSI6IkNvbmZpZGVudGlhbCIsImFwcGlkIjoiQ0MtMTAzMj U3LUY2Nzc4NDQtMzgzNzEtVUFUIiwiYXV0aF90aW1lIjoiMjAxOS0xMS0yMVQyMTo1OTozNC4wMTlaIiwidmVyIjoiMS4wIn0.O 1LeuTzHpCZ9eja4sBgpl9Ypf71s747alq0uOQ4XJ-
198AKRzvPzeltJotl063qfxShHrfpP1Z9jBh2bt7iu8yh3EeUZc_dpl7cjAlllZSAmKuDyP8d2evHxp0P4gfIAixTeaNBIwwbiAu-CczN30g2RgQvWyTqhRpw2uLXvTFR4QnVSztgcAgKqq-
PmMYXACNziWqzUMGsHEK8Qw5eQP0v6pXdx4LLiJBxNIc0R1OFN-
GT8X8bsQVasHF0ASBG9UuawbpV6h3qoySgZgfDjOpJcpAHsdz4xDKNkOsMfLGah51wgNumt4wz-
S6XYkWPgobe4TOqk9FdWnimgruaOg'

Note

An expired token returns an HTTP status of 401. Create a new token before proceeding.

Using legacy OAuth

If the APIs in your project use the https: idauat.jpmorganchase.com/adfs/services/trust endpoint, follow these steps:

Generate a Certificate Signing Request (CSR) and upload it to your J.P. Morgan Developer project (see Configuring API Credentials on the J.P. Morgan Developer site).
Receive your Client ID, Public Certificate, and Token URI from J.P. Morgan (these credentials will be uploaded to your J.P. Morgan Developer project).
Follow the steps in the OAuth onboarding guide to receive your OAuth credentials.