Security¶
Enabling JWT authentication ¶
IDVoice CC Server supports JWT-based authentication. To enable it set the IDVOICE_CC_SERVER_AUTHENTICATION
environment variable to jwt
and specify the configuration endpoint of the authorization server:
docker run \
--env IDVOICE_CC_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_CC_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=idvoicecc \
...
Note that /core/get_build_info
and /core/get_expiration_date
endpoints are never require authentication (see available endpoints).
Enabling SSL¶
IDVoice CC 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-cc-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-cc-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-cc-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
- Create
ssl-config.properties
file with contents provided on the right panel - 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-cc-server:3.0