Security

Enabling JWT authentication ¶

IDLive Doc Server supports JWT-based authentication. To enable it set the IDLIVEDOC_SERVER_AUTHENTICATION environment variable to jwt and specify the configuration endpoint of the authorization server:

docker run \
    -e IDLIVEDOC_SERVER_AUTHENTICATION=jwt \
    -e SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=https://example.com/realms/test \
    ...

If your authorization server doesn't support configuration endpoints, the JWK Set endpoint can be specified instead:

docker run \
    -e IDLIVEDOC_SERVER_AUTHENTICATION=jwt \
    -e SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI=https://example.com/realms/test/protocol/openid-connect/certs \
    ...

Additionally you can specify the audiences (the aud claim) that the JWT should contain:

docker run \
    -e SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_AUDIENCES=idlivedoc \
    ...

Note that GET /api_version, GET /license_info, GET /swagger-ui/** and GET /v3/api-docs/** endpoints don't require authentication.

Enabling SSL¶

IDLive Doc Server provides two possible options for connection. You can either use the default HTTP configuration by connecting to the port 8080, or you can use encrypted connection as described below.

P2P TLS¶

The server supports point-to-point TLS in case you have specific requirements for that. To enable it, pass SERVER_SSL_ENABLED=true as an environment variable to the docker container. This will change the port application listens on from 8080 to 8443, so you need to alter your --publish options in Docker or containerPort: in Kubernetes. This feature uses embedded self-signed certificate which is valid up to year 2120. In case if you need to change it to your own certificate, there are two ways to do it:

1. Alter docker image. Resulting Dockerfile will look like this:

   FROM idlivedoc-server:latest # change with version you got
   ADD ssl-privkey.pem ./
   ADD ssl-cert.pem ./
   RUN cat ssl-privkey.pem ssl-cert.pem > ssl-bundle.pem
   
   ENV SERVER_SSL_ENABLED=true
   ENV SERVER_SSL_KEY_STORE=ssl-bundle.pem
   

2. Pass certificate bundle as a volume. Resulting launch command will look like this:

   docker run \
       ... \
       -v /path/to/your/ssl-bundle.pem:/app/ssl-bundle.pem \
       -e SERVER_SSL_ENABLED=true \
       -e SERVER_SSL_KEY_STORE=ssl-bundle.pem \
       ... \
       idlivedoc-server:latest
   

LetsEncrypt TLS¶

This use-case is discouraged, as proper setup for LetsEncrypt TLS is to have a transparent proxy acting as TLS layer in front of the actual service.

However, if you need to use the container with LetsEncrypt certificate with valid CA chain, follow these steps:

1. Create ssl-config.properties file with following content:

   source.key=/letsencrypt/live/your.domain.tld/fullchain.key
   source.cert=/letsencrypt/live/your.domain.tld/privkey.pem
   

2. Mount ssl config and LetsEncrypt folder when running the image.

   docker run \
       ... \
       -v /etc/letsencrypt/:/letsencrypt/ \
       -v /path/to/ssl-config.properties:/app/ssl-config.properties \
       -e SERVER_SSL_ENABLED=true \
       -e SERVER_SSL_KEY_STORE=ssl-config.properties \
       -e SERVER_SSL_KEY_STORE_TYPE=PEMCFG.MOD \
       ... \
       idlivedoc-server:latest
   

Enabling CORS¶

In some cases Cross-Origin Resource Sharing (CORS) is required (e.g. when client-side JavaScript interacts with the server placed on a different host/port). It's unsafe and is not recommended for usage in production, but for debugging purposes you can enable CORS by passing SERVER_ALLOW_CORS environment variable on the container initialization.

CORS is disabled by default.

Launching server with enabled CORS:

docker run \
    -e SERVER_ALLOW_CORS=true \
    ...