Transport Layer Security (TLS)

Table of Contents

Introduction
Secure Service-To-Service Communication
Other TLS Configurations

Introduction

TLS is important to secure communication between parties. Infinite Scale provides TLS for internal communication and also for communication with users or services which are not provided by Infinite Scale. While focusing on describing the environment variables and their relationships, managing certificates is not the scope of this document.

If not explicitly mentioned otherwise, the environment variables for services start with the environment variable name. Names starting with OCIS_ generally have a global scope and are not bound to a particular service.

Secure Service-To-Service Communication

When deploying a distributed setup, it is recommended to secure communication and authentication between services.

Most services currently provide TLS for service-to-service communication and authentication with the exception of the frontend and the ocdav service. TLS will be added to the latter ones in a future release.

TLS is usually defined per instance on a global scope, though you can define the settings per service too.
When setting TLS modes to insecure, the traffic can’t be sniffed anymore, but it would be still possible to intercept it.

TLS for gRPC

OCIS_GRPC_TLS_ENABLED

Activates TLS for the gRPC-based services using the server certificate and key configured via:

OCIS_GRPC_TLS_CERTIFICATE and
OCIS_GRPC_TLS_KEY.

If OCIS_GRPC_TLS_CERTIFICATE is not set, a temporary server certificate is generated - to be used with OCIS_GRPC_CLIENT_TLS_MODE=insecure.

OCIS_GRPC_CLIENT_TLS_MODE

TLS mode for gRPC connection to the go-micro based gRPC services. Possible values are off, insecure and on.

off: disables transport security for the clients.
insecure allows transport security to be used, but disables certificate verification (to be used with the autogenerated self-signed certificates).
on enables transport security, including server ceritificate verification.

OCIS_GRPC_TLS_KEY

Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the gRPC services.

OCIS_GRPC_TLS_CERTIFICATE

Path/File name of the TLS server certificate (in PEM format) for the gRPC services.

OCIS_GRPC_CLIENT_TLS_CACERT

Path/File name for the root CA certificate used to validate TLS server certificates of the go-micro based gRPC services.

TLS for the HTTP Backend

OCIS_HTTP_TLS_ENABLED

Activates TLS for HTTP-based services using the server certificate and key configured via

OCIS_HTTP_TLS_CERTIFICATE and
OCIS_HTTP_TLS_KEY

If OCIS_HTTP_TLS_CERTIFICATE is not set, a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.

PROXY_INSECURE_BACKENDS

Disable TLS certificate validation for all HTTP backend connections.

OCIS_HTTP_TLS_KEY

Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the HTTP services.

OCIS_HTTP_TLS_CERTIFICATE

Path/File name of the TLS server certificate (in PEM format) for the HTTP services.

PROXY_HTTPS_CACERT

Path/File for the root CA certificate used to validate the server’s TLS certificate for https enabled backend services.

TLS for the Event Bus (NATS)

OCIS_EVENTS_ENABLE_TLS: Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between services.
OCIS_INSECURE: Whether the server should skip the client certificate verification during the TLS handshake.
NATS_TLS_CERT: Path/File name of the TLS server certificate (in PEM format) for the NATS listener.
NATS_TLS_KEY: Path/File name for the TLS certificate key (in PEM format) for the NATS listener.

TLS for the Graph API

GRAPH_EVENTS_TLS_ROOT_CA_CERTIFICATE

Path/File for the root CA certificate used to validate the server’s TLS certificate. If provided, GRAPH_EVENTS_TLS_INSECURE will be regarded as false.

OCIS_INSECURE

Whether the server should skip the client certificate verification during the TLS handshake.

OCIS_HTTP_TLS_ENABLED

Activates TLS for the HTTP-based services using the server certificate and key configured via

OCIS_HTTP_TLS_CERTIFICATE and
OCIS_HTTP_TLS_KEY

If OCIS_HTTP_TLS_CERTIFICATE is not set, a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.

OCIS_HTTP_TLS_CERTIFICATE

Path/File name of the TLS server certificate (in PEM format) for the http services.

OCIS_HTTP_TLS_KEY

Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.

OCIS_GRPC_CLIENT_TLS_MODE

TLS mode for grpc connection to the go-micro-based grpc services. Possible values are off, insecure and on.

off: disables transport security for the clients.
insecure allows to use transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates).
on enables transport security, including server certificate verification.

OCIS_GRPC_CLIENT_TLS_CACERT

Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the go-micro based grpc services.

Other TLS Configurations

These TLS configurations are used for securing communication to users or services not provided by Infinite Scale.

TLS for SMTP

NOTIFICATIONS_SMTP_ENCRYPTION: Encryption method for the SMTP communication. Possible values are starttls, ssl, ssltls, tls and none.

TLS for WOPI

APP_PROVIDER_WOPI_INSECURE: Disable TLS certificate validation for requests to the WOPI server and the web office application. Do not set this in production environments.
APP_PROVIDER_WOPI_WOPI_SERVER_IOP_SECRET: Shared secret of the CS3org WOPI server.

TLS for LDAP

You will find the LDAP TLS settings in the IDP and Auth-Basic service.

LDAP_CACERT: Path to the TLS certificate for the LDAP service.
LDAP_INSECURE: Disable TLS certificate validation for the LDAP connections. Do not set this in production environments.

TLS for the HTTP Frontend

PROXY_TLS: Enable/Disable HTTPS for the external HTTP services. Must be set to 'true' if the built-in IDP service and no reverse proxy is used.
PROXY_TRANSPORT_TLS_KEY: Path/File name of the TLS server certificate key for the HTTPS server.
PROXY_TRANSPORT_TLS_CERT: Path/File name of the TLS server certificate for the HTTPS server.
PROXY_HTTPS_CACERT: Path/File for the root CA certificate used to validate the server’s TLS certificate for https enabled backend services.