Docker

Let's connect a nodejs app in one virtual private network with a MongoDB database in another virtual private network. The example uses docker and docker compose to create these virtual networks.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, Curl, Docker, and Docker Compose. Please set up these tools for your operating system, then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/databases/mongodb/docker

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.
• The run function then generates two new enrollment tickets. The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns attributes to its redeemer. The first ticket is meant for the Ockam node that will run in Bank Corp.’s network. The second ticket is meant for the Ockam node that will run in Analysis Corp.’s network.
• In a typical production setup an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It uses environment variables to give tickets to and provision Ockam nodes in Bank Corp.’s and Analysis Corp.’s network.
• The run function takes the enrollment tickets, sets them as the value of an environment variable, and invokes docker-compose to create Bank Corp.’s and Analysis Corp.’s networks.

Bank Corp

# Create a dedicated and isolated virtual network for bank_corp.
networks:
  bank_corp:
    driver: bridge

• Bank Corp.’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Bank Corp.
• In this network, docker compose starts a container with a MongoDB database. This container becomes available at mongodb:27017 in the Bank Corp network.
• Once the mongodb container is ready, docker compose starts an Ockam node in a container as a companion to the mongodb container. The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.
• When the Ockam node container starts in the Bank Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute mongodb-outlet=true. The run function assigned this attribute to the enrollment ticket.
• The entrypoint script then creates a node that uses this identity and membership credential to authenticate and create a relay in the project, back to the node, at relay address: mongodb. The run function gave the enrollment ticket permission to use this relay address.
• Next, the entrypoint sets an access control policy that only allows project members that possesses a credential with attribute mongodb-inlet="true" to connect to tcp portal outlets on this node. It then creates tcp portal outlet to mongodb at mongodb:27017.

Analysis Corp

# Create a dedicated and isolated virtual network for analysis_corp.
networks:
  analysis_corp:
    driver: bridge

• Analysis Corp.’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Analysis Corp. In this network, docker compose starts an Ockam node container and an app container.
• The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.
• When the Ockam node container starts in the Analysis Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute mongodb-inlet=true. The run function assigned this attribute to the enrollment ticket.
• The entrypoint script then creates a node that uses this identity and membership credential. It then sets an access control policy that only allows project members that possesses a credential with attribute mongodb-outlet="true" to connect to tcp portal inlets on this node.
• Next, the entrypoint creates tcp portal inlet that makes the remote mongodb available on all localhost IPs at 0.0.0.0:17017. This makes mongodb available at ockam:17017 within Analysis Corp’s virtual private network.
• Once the Ockam node container is ready, docker compose starts an app container. The app container is created using this dockerfile which runs this app.js file on startup.
• The app.js file is a nodejs app, it connects with mongodb on ockam:17017, then inserts some data, queries it back, and prints it.

Recap

We connected a nodejs app in one virtual private network with a MongoDB database in another virtual private network over an end-to-end encrypted portal.

Sensitive business data in the MongoDB database is only accessible to Bank Corp. and Analysis Corp. All data is encrypted with strong forward secrecy as it moves through the Internet. The communication channel is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access to connect with MongoDB can be easily revoked.

Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the MongoDB server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their networks are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all containers and images:

./run.sh cleanup