This article describes how to connect your CAS to your website via the Operator Sample Website (OSW) API.

BEFORE YOU BEGIN: carefully review the entire process.

Hire a professional if you’re uncomfortable with any aspect of the process.
Sloppy work can result in the loss of funds. Don’t take chances with your money; do it right.

WEBSITES: Creating any website (even the sample provided) is your responsibility and beyond the scope of this article and General Bytes’ support.

At this point, you should already have an existing (and operating) CAS installation.

See: https://generalbytes.atlassian.net/l/c/iZMbqUFz

1. Load the Operator Sample Website (OSW) extension:

The OSW extension is part of the default CAS distribution - but it is not automatically loaded by the master service by default. Enable it before starting the master service.

SSH into your CAS host, and modify the extensions file to enable the OSW extension.

Create the /batm/config/extensions file and adjust it's permissions:

sudo mkdir -p /batm/app/master/extensions
sudo touch /batm/config/extensions
sudo chown batm:batm /batm/config/extensions

Use nano (or any another editor) to modify the “extensions” file:

sudo nano /batm/config/extensions

set autoload=true for the OSW’s jar extension, e.g.
- com.generalbytes.batm.server.extensions.website.SellExtension.autoload=true

Save the file and exit nano (Ctrl+X and Enter).

CAS is now configured to start the OSW extension.

2. Configure a proxy.

The OSW is exposed internally at [master IP]:7743 and is unreachable by the public. To share/expose the OSW, you’ll have to use an intermediary to “proxy” the web page, and a method of exposing the proxy to the world. This is a security measure.

Configure the NGINX proxy server to protect CAS from “URL path traversal” attacks.

https://generalbytes.atlassian.net/l/cp/nfb1x7Xd

A detailed, secure Let’s Encrypt NGINX server block example is provided below, click here.

3. Serve the proxy.

Choose a method to serve the TLS/SSL endpoints:

Use the free Let’s Encrypt: https://generalbytes.atlassian.net/wiki/spaces/ESD/pages/2942631937/NGINX+as+a+Reverse+Proxy+Server#Let%E2%80%99s-Encrypt
Use a non-free cloudflared tunnel: https://generalbytes.atlassian.net/wiki/spaces/ESD/pages/2944073731/Cloudflare+Zero+Trust+for+REST+API#Use-with-NGINX
- Configure the tunnel as HTTPS pointing to 127.0.0.1:8705

Expose the proxied port (either 8743 or 8705 were suggested) in your firewall(s).

4. Create the CAS API key.

Create a security key (+ ADD API ACCESS) to enable the new API to communicate with your secure website.

Log into CAS.

Create a Terminal Tag.

At least one tag is required to create the API key. Assign that tag to at least one machine.

Create a new API key:

Navigate to: Third-party
Select: Operators sample website API
Click the green [ +ADD API ACCESS ]

Save the key.

Hit the submit button after saving the API Key.

5. Test it.

Test the connection using curl. Each test reveals a level of success.

Replace your_api_key with the key provided in the step immediately preceding this one.

Test that the extension is loaded:
1. curl -k -i -H "X-Api-Key: your_api_key" https://10.3.2.1:7743/extensions/website/terminals
Test that the proxy is working behind any firewall:
1. Let’s Encrypt:
  curl -k -i -H "X-Api-Key: your_api_key" https://127.0.0.1:8743/terminals
2. cloudflared: replace 8743 with the correct port (8705 was suggested).
Test that the NGINX proxy is exposed to the world:
1. curl -k -i -H "X-Api-Key: your_api_key" https://your_cas_IP:8743/terminals
2. cloudflared: replace 8743 with the correct port (8705 was suggested).
Test that your DNS (Let’s Encrypt or cloudflared) is resolving the IP properly:
1. Let’s Encrypt:
  curl -k -i -H "X-Api-Key: your_api_key" https://your_cas_domain:8743/terminals
2. cloudflared: omit the port and add the subdomain:
  curl -k -i -H "X-Api-Key: your_api_key" https://osw.your_cas_domain/terminals
If all these tests return valid data (and curl responds with “200 ok”), then your OSW and API access are properly configured.

(Optional) Inspect the connection using Postman:

Download Postman

Modifications and additional material:

https://github.com/GENERALBYTESCOM/batm_public/tree/master/operators_sample_website/website#readme

Building from source?

This is optional and advanced. The extension should already exist, but there are occasions where you may want to overwrite the default. This is how you do it.

Test to see if the extension already exists:

ls /batm/app/master/extensions/operators_sample_website*.jar

Proceed if you choose to build it from the source code on GitHub.

REPOSITORIES: GitHub, Java, and source code compilation is beyond the scope of this article and General Bytes' support.

This article is intended for advanced Operators. If you are unfamiliar with Java, website development, or addressing ports via IP, then STOP !

Overview:

Clone the GB repository.
Compile the CAS extension (JAR).
Copy that JAR to the right destination in your CAS host.
Test it.

I. Clone the GB repository:

Install Git:

sudo apt update && sudo apt install git

Clone the GB repository.

These instructions assume you’ll use your home directory. If you choose to clone into another, different directory, then adjust this next command to change to it instead:

cd $HOME

Now clone batm_public and enter the OSW subdirectory:

git clone https://github.com/GENERALBYTESCOM/batm_public
cd batm_public
cd operators_sample_website

If you’ve previously cloned the repository (e.g. for the SSH wallet tunnel), the operators_sample_website directory (and contents) may not exist. Fix that to continue.

You’ll have to either:

reset the current repository clone, or
clone the latest version into another directory (and adjust the commands to reflect that).

To reset Git, use: git reset --hard && git clean -f -d and the new contents will be cloned.

II. Compile the CAS extension (JAR).

Build the operators_sample_website.jar extension with:

../gradlew clean build

You have succeeded in building the API jar from source code. Now copy it to CAS.

III. Copy that JAR to the right destination in your CAS host.

You’ve prepared CAS (in step 1) to look for an extension in a specific place. Put it in it’s place.

The default location of the new JAR is:

$HOME/batm_public/operators_sample_website/build/libs/operators_sample_website.jar

We want to copy it to:

/batm/app/master/extensions/operators_sample_website.jar

Use this command to copy it:

sudo cp $HOME/batm_public/operators_sample_website/build/libs/operators_sample_website.jar /batm/app/master/extensions/operators_sample_website.jar

Modify file ownership:

sudo chown batmmaster:batmmaster /batm/app/master/extensions/operators_sample_website.jar

Restart CAS to implement the new extension.

sudo /batm/batm-manage stop all
sudo /batm/batm-manage start all

Success. The JAR is now in the proper place, and CAS will load it when started.

NGINX Server Block

This demonstration NGINX server block contains typical settings for the OSW.

server {
  server_name sample.yourcasdomain.com;
  access_log /var/log/nginx/onfido_access.log;
  error_log /var/log/nginx/onfido_error.log;
  listen 8743 ssl;
  ssl_certificate /etc/letsencrypt/live/yourcasdomain.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/yourcasdomain.com/privkey.pem;
  location /osw {
        proxy_pass https://10.3.2.1:7743/extensions/website/terminals;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Exposes the sensitive internal path /extensions/website/terminals at the public path: /osw
Port 8743 is an arbitrary selection, adapt it to your specific needs.
- When using a cloudflared tunnel, a port number such as 8705 is suggested.
Rewriting the port and path are security measures; adapt them to your specific needs.

Website API Example