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. You may choose to specify a userid claim, if you do the returned access token will be limited to the abilities and access level of that user. That user must be in your office or sub offices.

Tokens generated for eMoney Components must include this userid claim with a valid eMoney user/client UUID. This is for security reasons as the token will be used by front-end code running on your user’s browser and so is therefore accessible to them if they choose to inspect the page source. Tokens generated without the userid claim have access to all data in your office at an “admin” role level.

When generating tokens for eMoney Components we highly recommend you use the eMoney user/client UUID associated with the user currently logged in and viewing your system. Not following this recommendation would allow users of your system to access eMoney data they do not normally have access to.

For the same reason, to use eMoney Components we also require you to specify specific platform scopes when requesting the token and not the global “API” scope.  See the documentation for each individual component to see what scopes they need. The scope claim on the token passed into a component does not need to exactly match the scopes required by that component. The scope claim may contain more scopes than are needed by any individual component so that you can use the same token for all components on a single page, but we recommend you limit the requested scopes to only what is required by the components you are using. You may also request individual tokens for each component if you so choose.

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