Transport Layer Security (TLS)

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.