Running Skopos Securely

The Skopos engine has support for running it securely over an open/public network:

  • encrypted connections (TLS)
  • login with username/password
  • login with client SSL certificate

This document will guide you through the steps necessary to set up and run the Skopos engine with security enabled.

The following reference pages provide full details about the commands and options related to security:

TLS Connection

Using a TLS connection is recommended in all cases when the client/browser will connect to Skopos over a network that is accessible by third parties that are not authorized to access Skopos or the application(s) that Skopos is set up to view or control. A TLS connection must be used to enable the login feature.

Using the built-in TLS server

  • Option 1: with an automatically-generated self-signed certificate: add the --autocert option to the engine start command line, for example:
docker run -d -p 8100:8100 --restart=unless-stopped --name skopos \
    -v /var/run/docker.sock:/var/run/docker.sock \
    opsani/skopos:edge --autocert '*'
  • Option 2: with a server certificate of your choice: You will need a file containing both the server certificate and the private key in PEM format (the certificate and key PEM blocks can be in any order). Map your certificate file into the container's namespace and add the '--certfile .' option, for example:
docker run -d -p 8100:8100 --restart=unless-stopped --name skopos \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /root/cert-srv-with-key.pem:/skopos/user/config/server.pem \
   opsani/skopos:edge --certfile .

If you are running Skopos as a Docker Swarm service, you can also take advantage of the Docker's --secret option to map the certificate file:

# first, create a secret and store the certificate in it
docker secret create skopos_server_cert my-cert-file.pem

# now, the secret can be given to the skopos service (the '--certfile .' option will
# make Skopos look for the cert file in the /run/secrets/ directory where Docker Swarm
# places it):
docker service create --name skopos --constraint 'node.role == manager' \
    --mount type=bind,source=/var/run/docker.sock,destination=/var/run/docker.sock \
    --publish 8100:8100 \
    --secret skopos_server_cert
    opsani/skopos:edge -- certfile .

Using an external TLS connection termination

It is possible to use a 3-rd party application or hardware appliance that serves as a transparent proxy to terminate the client's TLS connection. In this case, Skopos runs with a regular (non-TLS) server endpoint, but expects that the client is connecting with a secure connection (https://host/...).

  • set up your HTTP forwarder/proxy to have a TLS endpoint on the outside and to connect to Skopos with plain HTTP on the backend;
  • the back-end connection between the forwarder/proxy and Skopos should be on a private network that is not exposed to unauthorized access;
  • start the Skopos engine with --assume-secure option and without specifying either --autocert or --certfile, e.g.:
docker run -d -p 8100:8100 --restart=unless-stopped --name skopos \
    -v /var/run/docker.sock:/var/run/docker.sock \
    opsani/skopos:edge --assume-secure

It is important to note that, if configured with --assume-secure, Skopos will send browser cookies with the 'Secure' flag and therefore a connection with a browser directly over the insecure server port on which Skopos is listening will not work correctly; only the skopos command-line tool can connect directly over the insecure connection.

Set up Basic Login

To make the user connections require login, run the Skopos engine with the --use-login option. This option must be combined with one of the secure connection options (--autocert, --certfile or --assume-secure), otherwise it is invalid. Here is an example startup command line that enables login over a TLS connection with auto-generated self-signed certificate:

docker run -d -p 8100:8100 --restart=unless-stopped --name skopos \
    -v /var/run/docker.sock:/var/run/docker.sock \
    opsani/skopos:edge --autocert '*' --use-login

The authorized users database is the Unix users database in the container namespace (stored in the /etc/passwd and /etc/shadow) files. It can be easily modified and viewed with the system command-line utilities available in the Skopos container:

  • useradd, usermod, userdel - to add, modify or delete users
  • passwd - to set a user's password

A container newly created from the opsani/skopos:edge image does not have any valid users. You can add users after starting the container, with the help of the 'docker exec' command, e.g., to create a new user 'bob' and set the password:

docker exec -ti skopos useradd bob
docker exec -ti skopos passwd bob

PAM Authentication

The Skopos login uses Linux PAM (Pluggable Authentication Modules) to authenticate users. This means that it is possible to customize it to work with any of the login mechanisms supported by existing PAM modules - LDAP, Kerberos and others.

The pre-built Skopos container image does not include any PAM modules other than pam_unix (which does the login against a local /etc/passwd database). To add support for other login mechanisms, they need to be installed and configured appropriately. The best approach is to build a new Docker image using the original Skopos image opsani/skopos:edge as a base.

The following advanced topics provide examples of such image builds: