Skip to content

Security

Enabling JWT authentication

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

docker run \
    --env IDVOICE_SERVER_AUTHENTICATION=jwt \
    --env 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 \
    --env IDVOICE_SERVER_AUTHENTICATION=jwt \
    --env 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 \
    --env SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_AUDIENCES=idvoice \
    ...

Note that /core/get_build_info and /core/get_expiration_date endpoints are never require authentication (see available endpoints).

Enabling SSL

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

P2P TLS

Enable P2P TLS with custom certificate by altering docker image

 FROM voicesdk-cc-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

Enable P2P TLS with custom certificate by passing certificate bundle as a volume

$ 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 \
             ... \
             voicesdk-server:latest

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:

  • Alter voicesdk-server docker image
  • Pass bundle docker container as a volume

Examples provided at the right panel

LetsEncrypt TLS

Contents of ssl-config.properties:

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

Run server with ssl-config.properties mounted:

$ 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 \
             ... \
             voicesdk-server:latest

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 contents provided on the right panel
  2. Mount ssl config and LetsEncrypt folder when running the image. You have to mount whole letsencrypt folder as live paths use symlinks.

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 is not safe and is not recommended using the option 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 -d --name vrss --publish 8080:8080 \
             -e SERVER_ALLOW_CORS=true \
             voicesdk-server:3.0