Skip to main content

Configure an OPC UA Client to use Corsha

A Client using the OPC Unified Architecture Standard (OPC UA) over TCP can be configured to use Corsha to enhance security.

note

Once you have set up an OPC UA client to use Corsha, you will need to set up a Corsha Gatekeeper in front of the OPC UA server to deny requests that do not have valid Corsha Creds. Documentation on setting up the Corsha Gatekeeper for an OPC UA server can be found here: Configure the Gatekeeper to Handle OPC UA

Docker Deployment Configuration​

Configuring a Corsha Authenticator to handle OPC UA connections requires setting up a Corsha Authenticator and a Client Proxy to handle OPC UA traffic. Once the following steps are completed, we will have a running Corsha Authenticator that can handle OPC UA traffic.

  1. We will start by following the Corsha Authenticator Setup Guide. This guide will give us a working authenticator, but will not give us the Client Proxy we need for OPC UA.

  2. Next, we will add in the Client Proxy service to the docker-compose.yaml file. We will also add Envoy config to handle OPC UA traffic.

  3. Finally, we will run docker compose up.

Running the Authenticator Setup Guide​

We will start by running through most of the Corsha Authenticator Setup guide. Complete every step, except running docker compose up. We will need to add in the Client Proxy into the docker-compose.yaml before we run that command.

For reference, your Corsha Authenticator config.yaml should look similar to the one referenced here:

authenticator:
  # listen address for the authenticator service
  listen: 0.0.0.0:8082

  authServerTrustedMachine:
    url: auth-server-trusted.corsha.tld:443 # provided in your Corsha deployment guide
  authServerUntrustedMachine:
    url: auth-server-untrusted.corsha.tld:443 # provided in your Corsha deployment guide
  loggingLevel: info
  writeTime: "2h"
  streamsDir: "/opt/corsha/authenticator"

Setting up Docker Compose​

The docker-compose.yaml file needs to also include a Client Proxy. Add a second service for the proxy as seen below.

version: "3.9"
services:
  authenticator:
    image: corsha-docker.jfrog.io/corsha-authenticator:<latest version>
    ports:
      - 127.0.0.1:8082:8082
    restart: always
    volumes:
      - ./config:/config
      - ./authenticator-data:/opt/corsha/authenticator
    command: --config=/config/config.yaml
    environment:
      - AUTHENTICATOR_SECRET=<INSERT>
  client-proxy:
    image: corsha-docker.jfrog.io/proxy:<latest version>
    entrypoint: envoy -c /opt/envoy/client-proxy.yaml
    ports:
      - 127.0.0.1:4880:4880
    volumes:
      - ./envoy:/opt/envoy
    restart: always

Setting up your Client Proxy​

You will also need create an Envoy config that adds the Corsha Cred to OPC UA traffic.

Create a file named client-proxy.yaml at the path defined in the volume parameter of your docker-compose.yaml. For example, the above Docker Compose file expects this file at ./envoy/client-proxy.yaml.

static_resources:
  listeners:
  - name: listener_0
    address:
      socket_address:
        protocol: TCP
        address: 0.0.0.0
        port_value: 4880
    filter_chains:
      - filters:
          - name: envoy.filters.network.wasm
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.network.wasm.v3.Wasm
              config:
                configuration:
                  "@type": "type.googleapis.com/google.protobuf.StringValue"
                  value: |-
                    {"authenticatorCluster":"corsha-authenticator","authenticatorURL":"http://authenticator:8082"}
                vm_config:
                  runtime: "envoy.wasm.runtime.v8"
                  code:
                    local:
                      # this file is already bundled in the docker image
                      filename: "/envoy/wasm/opc-ua-client.wasm"
          - name: envoy.filters.network.tcp_proxy
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
              stat_prefix: tcp_stats
              cluster: server
  clusters:
  - name: corsha-authenticator
    connect_timeout: 0.25s
    type: LOGICAL_DNS
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: corsha-authenticator
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: authenticator
                port_value: 8082
  - name: server
    type: LOGICAL_DNS
    dns_lookup_family: V4_ONLY
    connect_timeout: 5s
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        # Change this url to the url of your Gatekeeper
        sni: corsha-protected.corsha.tld
    load_assignment:
      cluster_name: server
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                # Change this url to the url of the Gatekeeper
                address: corsha-protected.corsha.tld
                port_value: 4841

note

For additional configuration, reference the Official Envoy Proxy Documentation

Start the Corsha Authenticator​

Now that we've created and populated the Client Proxy configuration, we are ready to start the applications. Open a terminal in the Authenticator directory containing the docker-compose.yaml file and run the following command:

docker compose up

Conclusion​

Congratulations, your OPC UA client is now Corsha enabled! If you have not done so already, you will need to set up a Corsha Gatekeeper in front of your OPC UA server to deny requests that do not have valid Corsha Creds. Documentation on setting up the Corsha Gatekeeper for an OPC UA server can be found here: Configure the Gatekeeper to Handle OPC UA