SSL Termination¶

Emakin supports SSL-based connections through the host configuration panel. It also accommodates SSL termination at a network load balancer (NLB) or reverse proxy level.

In this configuration, the browser establishes an encrypted connection with a reverse proxy, which sits between the browser and the application server. This proxy handles the SSL encryption.

The connection between the reverse proxy and the Emakin application server can be configured for either encrypted ( HTTPS) or unencrypted (HTTP) communication.

The Emakin application server is configured by default to only allow reverse proxies with a local IP address ( 127.0.0.1). To allow external IP addresses, explicit configuration is required.

Forwarded Headers Support¶

Emakin utilizes the following headers to identify SSL connections when using a reverse proxy:

X-Forwarded-Proto¶

This header specifies the original scheme (HTTP or HTTPS) used for the request. If the request has passed through multiple proxies, this value may be a list of schemes.

X-Forwarded-For¶

This header contains information about the client that initiated the request and any subsequent proxies in the chain.

X-Forwarded-Host¶

This header contains the original value of the Host header field from the client request.

Enabling Forwarded Headers¶

Forwarded headers support is enabled by default only for loopback addresses, used for known proxies and networks. If the reverse proxy uses an external IP address, the default configuration must be updated.

To enable SSL termination, follow these steps:

1. Open the <installdir>/Configuration/appsettings.json file using a text editor.

2. Create a new section with the following content:

1
2
3
4
5
6
7
8

{
    "Web": {
        "ForwardedHeaders": {
          "ClearProxies": true,
          "ClearKnownNetworks": true
        }
    }
}

Diagnostics¶

Emakin offers a diagnostics page to inspect headers sent by the reverse proxy. This page is only accessible when the development environment flag is enabled and is disabled by default in production environments.

Running Emakin in Development Environment¶

Before proceeding, stop the Emakin service or daemon.

1. Open a new terminal window in the application's <installdir>.

2. Set the environment variable:

1
2
3
4

// Linux
export DOTNET_ENVIRONMENT=Development
// Windows
set DOTNET_ENVIRONMENT=Development

1. Start the Emakin service in web mode using the following command:

1

<installdir>/AltiKare.Workflow.Agent web

After this command, the Emakin application will start in web mode and allow access to the header diagnostics page.

Access the HTTP header diagnostics page via:

1

http://my.emakin.com/httpheaders

This page will display all headers sent to the application server, which can assist in diagnostics.

1
2
3
4
5
6
7
8

Request Method: GET
Request Scheme: https
Accept: text/html,application/xhtml+xml
Connection: keep-alive
Host: my.emakin.com
User-Agent: Mozilla/5.0

Request RemoteIp: 35.129.81.210

Request Scheme

Indicates the original HTTP scheme protocol. For SSL connections, this value must be "https".

Host

Specifies the requested hostname. Emakin uses this header to identify the tenants and this value must be set correctly.

Request RemoteIp

Specifies the user's IP address if the X-Forwarded-Host header is configured.