Deploy iText DITO Secure Proxy (Optional)

The secure proxy allows you to secure endpoints for DITO SDK.

This is a separate sidecar container for Docker SDK which is expected to be used with docker-compose.

It serves as a proxy for Docker SDK and handles authentication for requests.

How to use secure proxy for Docker image

First, you'll need to pull the image. Note: you need to specify the version explicitly when using the pull command, e.g.:

docker pull itext/dito-sdk-secure-proxy:{version}

For the full list of available versions go to Tags tab on the DockerHub repository page.

Start the Docker SDK security proxy sidecar container

To start the Docker SDK security container you need to use docker-compose in which both Docker SDK and secure proxy configured

Example of docker-compose.yml

version: "3"

services:
  dito-sdk:
    image: itext/dito-sdk:{version}
    container_name: sdk-host-name
    volumes:
    - {path to config directory}:/etc/opt/dito/shared
    - {path to work directory}:/var/opt/dito
    - {path to log directory}:/var/log/dito

  dito-sdk-secure-proxy:
    image: itext/dito-sdk-secure-proxy:{version}
    container_name: dito-sdk-secure-proxy
    depends_on:
      - dito-sdk
    volumes:
      - {path to config directory}:/etc/opt/dito-sdk-secure-proxy/shared/
    ports:
      - {port on host}:8080
    links:
      - dito-sdk
    environment:
      - DITO_SDK_HOST=sdk-host-name #(since 2.0.4)
      - DITO_SDK_PORT=8080 #(since 2.0.4)

See README.md of Docker SDK for more details about config directory, work directory and log directory

Since 2.0.4, it is possible to configure custom SDK URL. By default, we proxy pass strictly to http://dito-sdk:8080$url To customize dito-sdk:8080 part use DITO_SDK_HOST and DITO_SDK_PORT environment variables

Security configuration file

User configuration file for Docker SDK security. Must be present in config directory. Expected default name is auth.config.yml, but it can be overridden by setting the DITO_AUTH_CONFIG environment variable. YML file with application configuration, in form of:

auth:
  type: token
  properties:
    header: X-Header
    authorizeRequests:
      - tokenValue: testToken
        urls:
          - /api/test
      - tokenValue: anotherTestToken
        urls:
          - /api/second-test
          - /api/example

auth - section to configure access to Docker SDK

• type - configuration part which describes type of authentication, supported values: token
• properties - configuration section where properties for authentication mode are configured
  • header - header name in which authentication token should be passed
  • authorizeRequests - section to secure URL's, accepts list configuration subsections
    • tokenValue - value of the token which should be passed to access URL's
      • urls - section describes list of URL's which will be secured by token

NOTES:

• header - header name can't contain following symbols:

  • (
  • )
  • <
  • >
  • @
  • ,
  • ;
  • :
  • \
  • "
  • /
  • [
  • ]
  • ?
  • =
  • {
  • }
  • (space)

• urls - to secure urls Nginx is used under the hood, this means following:

  • in this section patterns for urls are being configured;
  • as we secure not exactly specified url, but url which matches specified pattern, all urls which matches it will be secured as well (for example: if specified url is /api/test, then /api/test/abc will match);
  • configred pattern is used both in location and proxy_path of nginx config, so it's not allowed to use any regex characters as it will break proxy_path url

Stop the proxy container

To stop proxy service gracefully, run the following command:

docker kill --signal=SIGQUIT {containerId}

Extending from DITO SDK Docker secure proxy image

In some cases you may want to extend from DITO SDK Docker security image. Here are some inner detail on base image that may help you do it. To extend from DITO SDK Docker security image start you Dockerfile with FROM itext/dito-sdk-secure-proxy:{version} e.g.

FROM itext/dito-sdk-secure-proxy:1.5.9

User security config file

Security config file is expected to be stored at /etc/opt/dito-sdk-secure-proxy/shared/$DITO_AUTH_CONFIG where DITO_AUTH_CONFIG is a predefined environment variable equal by default to auth.config.yml.

So if you want to avoid providing volume mapping for folder with config file, it is possible to do so by extending base image and adding

COPY path/on/local/machine/to/config/auth.config.yml /etc/opt/dito-sdk-secure-proxy/shared/$DITO_AUTH_CONFIG

Nginx config file

Nginx config file is being generated automatically in following folder /etc/nginx

Python scrypt which generates it is located in /opt/dito-sdk-secure-proxy/scripts/generator/main.py