Getting Started

The API certificates must be signed by an external, trusted Certificate Authority (CA).

• Wildcard certificates are not accepted
• All certificates must be valid for 2 years or less
• Must use SHA256 or stronger hashing algorithm.

An EV certificate, although preferred, is not a requirement. Standard certificates are acceptable if they satisfy the above. Certificate options will vary by provider.

The eMoney Security Team has identified the following acceptable CAs:

• Globalsign
• Godaddy
• Symantec
• Verasign
• Digicert
• Cetum
• Geotrust
• Comodo

Sample JWT Request

{

   "grant_type": "client_credentials",
   "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
   "client_assertion": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQ1MzU5MUU2MTFGREVF....................................",
   "scope": "API"

}

Header

The header includes information about the key and algorithm used to sign the payload like below. The alg and typ are required. The kid is optional.

Payload

The associated payload should look like this. All fields are required. Using your Client ID provided by the eMoney team, replace the below tag {Client ID} with your Client ID. The Subject Claim (sub), Expiry (exp), Issuer (iss) and Audience (aud) are all required in the payload. The Audience claim should be the OAuth server token endpoint that you received from the eMoney team.

Signature

The signature is used to verify that the correct private key was used to sign the JWT assertion and that the JWT assertion was not modified after being signed.  Signing the JWT Assertion will vary depending on the programming language you are using.  JWT.io has pre-made libraries that can handle this process for you, written in a variety of languages.  Otherwise, see rfc7519 for the JWT specification.

1. Go to https://jwt.io
2. Select 'RS256' as the algorithm
3. One of the payload attributes of the Client Assertion is an expiration timestamp for the assertion itself.  For testing in a non-Production environment, we recommend you set this to expire 2 hours from current time (extended testing may require you re-generate a new JWT). Use public site https://www.epochconverter.com/ to get Epoch time stamp. First select date and time till when the client assertion being generated will be valid and then click the button 'Human date to Timestamp' to get it.  
4. Update the payload with the following info:
    {
   "sub": "{APIClientID}",
   "exp": {Epochtimestampexpiration},
   "iss": "{APIClientID}", 
   "aud": "{eMoneyAuthServerTokenRequestEndpointURL}"
}
   An example of this would be:
    {
   "sub": "87c5fe3b53b44ee1aae0daf6d055dbcd",
   "exp": 1560350834,
   "iss": "87c5fe3b53b44ee1aae0daf6d055dbcd",
   "aud": "https://signin-externalbeta2.emaplan.com/connect/token"
}
5. Copy the private key extracted from the private certificate (key.pem if you generated the certificate per above instructions) and paste into the 'PRIVATE KEY' text area in the jwt.io debugger Signature area. The private will be the content beginning with the line '-----BEGIN PRIVATE KEY-----' and ending with the line '-----END PRIVATE KEY-----' including the content in between.  If there is any issue in the paste, the token will not be generated. 
   
   You can verify the signature by pasting the PRIVATE key into the 'Public' key form field in jwt.io to see the "Signature Verified" confirmation beneath the Debugger. Note that while jwt.io performs all encoding and debugging locally within the browser, please do not use this utility with certificates meant for production use with eMoney.
6. The Base64 'Encoded' output of the jwt.io debugger (or via your own local code option below) is your JWT and what you will use in the eMoney token request as your Client Assertion

If you are familiar with JWT and have a local development environment, you can generate the JWT using eMoney inputs provided and by connecting to your certificate store. 

C# Example

using System;
using System.Collections.Generic;
using System.Security.Cryptography.X509Certificates;
using System.Net.Http;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using Microsoft.IdentityModel.Tokens;
 
namespace eMoneyAPITestTool
{
    public class eMoneyAuthorization
    {      
        public string GetClientAssertionToken(string clientId, X509Certificate2 certificate, string tokenEndpoint)
        {
            SecurityToken st = null;
            SecurityTokenHandler sth = null;
            SecurityTokenDescriptor std = null;
 
            sth = new JwtSecurityTokenHandler { SetDefaultTimesOnTokenCreation = false };
            std = new SecurityTokenDescriptor
            {
                Subject = new ClaimsIdentity(new[] { new Claim(JwtRegisteredClaimNames.Sub, clientId) }),
                SigningCredentials = new SigningCredentials(new X509SecurityKey(certificate), SecurityAlgorithms.RsaSha256Signature),
                Audience = tokenEndpoint,
                Expires = DateTime.UtcNow.AddMinutes(600), //for 10 hrs
                Issuer = clientId
            };
            st = sth.CreateToken(std);
 
            return sth.WriteToken(st);
        }
 
        public eMoneyAuthInfo GetAccessToken(string certName, string api_clientId, string authTokenURL)
        {
            eMoneyAuthInfo info = new eMoneyAuthInfo();
            X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
 
            store.Open(OpenFlags.ReadOnly);
            X509Certificate selectedCertificate = null;
 
            foreach (X509Certificate cert in store.Certificates)
            {
                if (cert.Subject.Contains(certName))
                {
                    selectedCertificate = cert;
                    break;
                }
            }
 
            try
            {
                info.ClientAssertion = new eMoneyAuthorization().GetClientAssertionToken(api_clientId, (X509Certificate2)selectedCertificate, authTokenURL);
                var requestContent = new FormUrlEncodedContent(new Dictionary<string, string>
                {
                    { "grant_type", "client_credentials" },
                    { "client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" },
                    { "client_assertion", info.ClientAssertion },
                    { "scope", "API" }
                });
                 
                using (var client = new HttpClient())
                {
                    client.BaseAddress = new Uri(authTokenURL);
                    client.DefaultRequestHeaders.Clear();
 
                    HttpResponseMessage response = client.PostAsync(authTokenURL, requestContent).Result;
 
                    if (response.IsSuccessStatusCode)
                    {
                        string callResponse = response.Content.ReadAsStringAsync().Result;
                        eMoneyAccessToken x = Newtonsoft.Json.JsonConvert.DeserializeObject<eMoneyAccessToken>(callResponse);
                        if (x != null)
                        {
                            info.BearerToken = x;
                        }
                    }
                }
                return info;
            }
            catch (Exception e)
            {
                throw new Exception("Error occurred in getting an Access Token.\r\n" + e.ToString());
            }
        }
 
        public T SimpleGETRequest<T>(string endpointURL, string accessToken)
        {
            object result = new object();
            using (var client = new HttpClient())
            {
                client.BaseAddress = new Uri(endpointURL);
                client.DefaultRequestHeaders.Clear();
                client.DefaultRequestHeaders.Add("Authorization", "Bearer " + accessToken);
                client.DefaultRequestHeaders.Add("apikey", "**** consumerKey goes here ****");
 
                HttpResponseMessage response = client.GetAsync(endpointURL).Result;
 
                if (response.IsSuccessStatusCode)
                {
                    string callResponse = response.Content.ReadAsStringAsync().Result;
                    result = Newtonsoft.Json.JsonConvert.DeserializeObject<T>(callResponse);
                }
            }
            return (T)Convert.ChangeType(result, typeof(T)); ;
        }
    }
    public class eMoneyAccessToken
    {
        public string access_token { get; set; }
        public string token_type { get; set; }
        public long expires_in { get; set; }
    }
 
    public class eMoneyAuthInfo
    {
        public string ClientAssertion { get; set; }
        public eMoneyAccessToken BearerToken { get; set; }
    }
}

Javascript Example

import axios from 'axios';
import { sign } from 'jsonwebtoken'; // https://www.npmjs.com/package/jsonwebtoken
import { stringify } from 'querystring';
import { exec } from 'child_process';

// Get an access token from the Authentication server
const getAuthorization = async () => {
  const config = {
    headers : {
    'Content-Type': 'application/x-www-form-urlencoded'
    }
  }
  const payload = {
    "grant_type": "client_credentials",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": createClientAssertionJWT(),
    "scope": "API",
  }
  const url = `${this.authUrl}/connect/token`
  return axios.post(url, stringify(payload), config)
    .then((response) => {
      return response.data.access_token;
    })
    .catch(e => {
      throw 'Failed to get token'
    })
}
// Craft the JWT according to the specs from the Auth document
const createClientAssertionJWT = () => {
  const certThumbprint = getSHA1Fingerprint(this.publicCert)
  const header = {
    algorithm: "RS256",
    kid: certThumbprint,
    typ: "JWT"
  }
  const payload = {
    sub: this.clientId,
    exp: Math.trunc(Date.now() / 1000) + 600,
    iss: this.clientId,
    aud: this.authUrl + '/connect/token'
  }
  // Necessary since we pass in the private cert from an ENV var
  const cert = this.privateCert.replace("\\n", "\n");
  const jwt = sign(payload, cert, { header, algorithm: 'RS256' })
  return jwt
}
// We use openssl to create the fingerprint for the public cert.
// This function can be avoided by generating the fingerprint manually and adding it
// but requires another step when the public and private certs need to be updated.
const getSHA1Fingerprint = async (cert: string) => {
  let publicCert = cert
  let fingerprint: string
  publicCert = publicCert.replace("\\n", "\n");
  exec(`touch publicCert.crt && echo "${publicCert}" >> publicCert.crt`)
  exec('openssl x509 -noout -fingerprint -sha1 -inform pem -in publicCert.crt', (err, stdout, _stderr) => {
    if (err) {
      console.log(err)
      return
    }
    fingerprint = stdout
    if (fingerprint && fingerprint.includes('SHA1 Fingerprint=')) {
      fingerprint = fingerprint.replace('SHA1 Fingerprint=', '').replace(/:/g, '').replace('\n', '')
      return fingerprint
    } else {
      return null
    }
  })
}

Sample Successful Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"Bearer",
   "id_token": "9dfjak398djfkgjh",
   "expires_in":3600
}

Possible Success Response Parameters

Sample Error Response

HTTP/1.1 400 Bad Request
   Content-Type: application/json
   Cache-Control: no-store
   Pragma: no-cache
   {
      "error": "invalid_request"
   }

Possible Error Response Parameters

Possible Error Codes that can be returned in the "error" parameter from the response