Authentication Technical Guide

Third party authentication to Arab Bank is based on access tokens. To be able to call our transactional APIs, you must call our OAuth API, which is included with many of our API products by default. Our authentication mechanism currently supports OAuth's "client assertion" described below.

 

OAuth API: The details

You can obtain an access token to Arab Bank's APIs by calling the OAuth API endpoint (/token). You need the following settings to successfully call this endpoint:

Request Attributes Value
HTTP Verb          POST
Path URL       https://tapi.arabbank.com/sandbox/oauth/v1/token
Request Headers
  • apikey: (your API Key)
  • Content-Type: application/x-www-form-urlencoded
Request Body
  • grant_type: client_credentials
  • client_assertion: (JSON Web Token - explained below)
  • client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  • scope: (optional - "accounts" or "payments")

 

JSON Web Token (Client Assertion)

The request body will contain a JSON payload with an attribute named "client_assertion". This attribute must be a JSON Web Token (JWT), which is used to authenticate your app and send back an access token in response.

JSON Web Token is an open standard that defines a self-contained way for securely transmitting information between parties as a hashed JSON object. This information can be verified and trusted because it is digitally signed. A JWT is a string consisting of three parts, each part is separated by a dot "header.payload.signature". The JWT must be generated by the third party app (API consumer). Below are the steps on how to generate a JWT.

  1. Create a public/private key pair for your app

Generating a JWT requires signing by a private key from at least a 2048 bit size public/private key pair. The keys should be in PEM format.

The Public Key MUST be shared with Arab Bank. Use the below commands to generate a 2048 bit size public/private key pair.

#generates RSA private key of 2048 bit size
openssl genrsa -out private_rsa.pem 2048

#generates public key from the private key
openssl rsa -in private_rsa.pem -outform PEM -pubout -out public_rsa.pem

Important Note! JWT generation will not work unless Arab Bank associates your public key with your app. Please provide us with your Public Key along with you app name and developer email at GMDevportal@arabbank.com.jo. Your public key will immediately be associated with your app and saved on our API management platform.

     2. Create the JWT header

        The header mandates how the signature should be generated. You can copy the below header and paste it on jwt.io to generate a sample JWT.

{
  "typ": "JWT",
  "alg": "RS256"
}

    3. Create the payload

        The payload of the JWT stores the data that will be passed in the JSON web token. The payload is referred to as "claims" in JWT terms. The claim contains a mandatory field called "iss" - the issuer identification -  which is essentially your API key. Claim has the following JSON format; type the below on jwt.io payload section of your sample JWT.

{
    "iss":"YourAPIKey"
}

    4. Create the JWT signature

        The signature is essentially a base 64 encoding of the header and payload created in the above two steps. it is created using the below psuedocode:

data = base64urlEncode( header ) + “.” + base64urlEncode( payload )
signature = Hash( data, secret );

As seen from the above pseudocode, the algorithm joins the encoded strings with a dot in between them, and the resulting string is assigned to the "data" variable.

This variable is hashed with the private key that you generated in step one using the hashing algorithm specified in the JWT header in step two.

The Client Assertion JWT will look something like:

eyJhbGdvcml0aG0iOiJSUzI1NiIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJiU3VleEM0QkJvSGtBdDVDZllVMDBFbzRHNGw0SEpwZCJ9.FReSZMjR7rXr3C7B1MMXJsMm8PfBTlq0CWOAkTN-In0Xv58_cA_eGH84zOKGGtN0jgbC80V_bx-kBwsQR9hjX1VQJDCEB60tWtTqjrXUF7F5IusGmJT3nlhHWd0x1GAQ1aqxQZu7_kleUKtL2nhtayhfWoley4ueflU6FT-whEvvdUwwu4rjcNMSoMFAG86GssBpAp1pogGGB-Oxxo-xjDnkrBKVllGTtnFd48BzPar0Ziif6ntgq394Pk8chFclyAfusWmJctIdcIJHmtL225GwTjkxoptiAGzvVj_dkIrH19mrxST5-cRKyd8C3Crv6cemqcXToMj73LZn5uzn8Q

Note: You can use jwt.io to generate sample JSON web tokens for testing. You can also use the node.js code snippet found here to generate a JWT. 

 

A successful API call made with curl should look something like:

curl -X POST https://tapi.arabbank.com/sandbox/oauth/v1/token -H "Content-Type: application/x-www-form-urlencoded" -H "API-Key: YOURKEYHERE" -d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=client_credentials&client_assertion=eyJhbGdvcml0aG0iOiJSUzI1NiIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJiU3VleEM0QkJvSGtBdDVDZllVMDBFbzRHNGw0SEpwZCJ9.FReSZMjR7rXr3C7B1MMXJsMm8PfBTlq0CWOAkTN-In0Xv58_cA_eGH84zOKGGtN0jgbC80V_bx-kBwsQR9hjX1VQJDCEB60tWtTqjrXUF7F5IusGmJT3nlhHWd0x1GAQ1aqxQZu7_kleUKtL2nhtayhfWoley4ueflU6FT-whEvvdUwwu4rjcNMSoMFAG86GssBpAp1pogGGB-Oxxo-xjDnkrBKVllGTtnFd48BzPar0Ziif6ntgq394Pk8chFclyAfusWmJctIdcIJHmtL225GwTjkxoptiAGzvVj_dkIrH19mrxST5-cRKyd8C3Crv6cemqcXToMj73LZn5uzn8Q&scope=accounts

The response to a successful request looks like:

{
  "access_token": "bvZuyx7jATAuV7c9glSzTyDIAXNU",
  "token_type": "Bearer",
  "expires_in": 1799
}

Once you have the Bearer token, you will be able to access Arab Bank's resources by providing the access token in the Authorization Header of the transactional API as such:

Bearer bvZuyx7jATAuV7c9glSzTyDIAXNU

You can now use our APIs with confidence by using our Sandbox Environment!