Config - Destinations

JSON Configuration for Destinations

"destinations" is an array of JSON objects where each object contains the configuration for a single destination.

{
  "destinations": [
    {
      "name": "demoapp",
      "description": "Demonstration application",
      "cookiesnapper": {
        "pattern": "JSESSIONID",
        "classifier": "default"
      },
      "ping": {
        "expect": "200",
        "timeout.seconds": 5,
        "method": "HEAD",
        "uri": "/",
        "meod": "GET",
        "interval.seconds": 30,
        "response.verify.script": "if (input.contains('For further information about PortalProtect')) true; else false;"
      },
      "loadbalance": "roundrobin",
      "target.consul.askviaconfigserver": false,
      "target.consul.interval": 60,
      "targets": [{
        "scheme": "http",
        "port": 8080,
        "unavailable": false,
        "name": "demoapp1",
        "host": "127.0.0.1",
        "disabled": false,
        "limits": {
          "queue.length": 100,
          "max.idle.connections.hard": 20,
          "idle.ttl": 10,
          "max.idle.connections.soft": 5,
          "max.concurrent.requests": 20
        }
      }],
      "limits": {
        "queue.length": 200,
        "max.idle.connections.hard": 20,
        "idle.ttl": -1,
        "max.idle.connections.soft": 5,
        "max.concurrent.requests": 10
      },
      "authentication": {
        "plugins": [
          "io.ceptor.authentication.target.TAuthenticatorBasicAuth",
          "io.ceptor.authentication.target.TAuthenticatorSSL",
          "io.ceptor.authentication.target.TAuthenticatorBearerToken"
        ],
        "basicauth": {
          "password": "password",
          "anonymous.password": "password",
          "anonymous.userid": "%{REQUEST_ID}",
          "userid": "%{REQUEST_ID}"
        },
        "bearer": {
          "authenticationplugin": 48,
          "forward.from.request": true,
          "call.newtoken": false,
          "base64encode": false,
          "newtoken.input": null,
          "use.ticket.from.session": true
        },
        "ssl": {
          "header.cipher": "SSL_CIPHER",
          "header.sessionid": "SSL_SESSION_ID",
          "header.clientcert": "SSL_CLIENT_CERT"
        }
      }
    }
  ]
}

Configuration using Ceptor Console

Here is the list of destinations, where you can add new destinations, or remove existing ones.

When you click Add, you get this prompt:

where you need to enter a name and optionally a description for your own use.

When you have entered this, you are brought to the Destination Configuration

Configuration is stored in the JSON object for the destination directly

The configuration on this screen is split into 2 different sections.

Destination Configuration

Name

Name of destination - used for logging/debugging and stickinesss (hash of name is in sticky cookie)

Default: none, a name is required
JSON key: name

Description

Description of destination - an optional description for your own use.

Default: none
JSON key: description

Enable HTTP2

Enable HTTP/2 protocol support - if not checked, HTTP 1.1 will be used instead when making connections towards the server.
Whenever possible, you should enable this, since HTTP/2 performs significantly better than older versions of the HTTP protocol.

Default: true
JSON key:http2.enable

Enable KeepAlive

If set, enables HTTP keepalive support - if not set, new connections will be created for each request which performs a lot worse than when enabled.

Default: true
JSON key: keepalive.enable

Sticky

If set, stickiness is enabled, meaning a sticky cookie is set, so user hits the same server again next time.

Default: true
JSON key: sticky

TCP Binding

Bind Address

If specified, this is the address to bind to when making the connection to the target server - leave blank to autoassing. This is useful when you want to select a particular network interface.

Default: blank
JSON key: bindaddress 
Minimum Version: 5.61 

Bind Port

TCP port to bind to when connecting to target server. Set to 0 to autoassign port. Only used when also specifying the bind address

Default: 0
JSON key: bindport 
Minimum Version: 5.61  

CookieSnapper

Configuration is stored in the JSON object cookiesnapper.

Cookies to snap

Pattern defining which cookies to remove from the response and place into the session. Any cookies matching this pattern will be moved from the response to the session, and added on future requests.

Default value: blank
JSON key: pattern

Classifier

Classifier to use - here you can use %{} variables, such as %{HTTP_HOST} or %{script:xxxx} to specify the classifier or scope to restrict these cookies to.
The classifier can ensure that the cookies are not forwarded on all requests, but only where the next request has the same classifier - so if it is e.g. set to %{HTTP_HOST} then the cookie will only be added to future requests, if these request has the exact same hostname as this one.
If the classifier is left as "default" then if if the next request has a different hostname, e.g. app2.mydomain.com then the cookie will be added to the request again, which is usually what you want. 

Default value: "default"
JSON key: classifier

Targets

A destination server has one or more target servers attached to it - target servers can be configured individually, or they can come from an application cluster, or even a consul service repository.

Target Server Configuration

Target server config is stored in the JSON object targets

To add a new target, click "Add", this will give you this screen:

where you must give the target server a name that is unique for the destination, and select a scheme (http/https) and specify its IP address and TCP port number.

See Destination Target Servers for details.

Alternative target settings

As an alternative to defining each target server one at a time, you can configure the gateway to use either an application cluster or do a consul service lookup.

An application cluster is a dynamic cluster created by importing a directory of configuration files into one, so the act of act of adding or removing the server is simply adding or removing a file within this directory. See Ceptor Configuration Server for details.

A consul service repository is also supported - se https://www.consul.io for information.

Applicationcluster name

Name of application cluster to automatically choose targets from - all servers in the applicationcluster will be used"

Default: none
JSON key: target.applicationcluster 

Lookup targets from services in consul

If set, lookup additional targets in consul using the configured consul service URI and consul server URLs

Default: false
JSON key: target.consul.enabled

Consul service URI

Service URL to query - e.g. /v1/catalog/service/customerservice

Default: none (but required when consul lookups are enabled)
JSON key: target.consul.serviceuri 

Call consul via configserver

If set, the "Consul servers URLs" is not used, but instead the config server is asked to call consul on behalf of the gateway.

Default: false
JSON key: target.consul.askviaconfigserver 

Consul servers URLs

List of URLs (separated by semicolon) to consul server(s), Do not include path - e.g. https://server1:4443;https://server2:4443

Default: none (but required when consul lookups are enabled, unless "Call consul via configserver" is set)
JSON key: target.consul.url 

Consul check interval

Interval in seconds between checking consul for updates

Default: 60
JSON key: target.consul.interval 

SSL Settings

SSL settings for all target servers in this destination, unless overridden for a particular target server.

They are saved in the JSON key sslcontext within the specific destination JSON Object.

SSL Settings

JCE Provider

Name of SSL JCE Provider to use, or leave blank for default JDK

Default: blank, meaning JDK default.
JSON key: ssl.provider 

Protocol

Name of SSL Protocol (e.g. TLS), or leave blank for default. Note that some SSL protocols are insecure - but old server implementations might require you to use an older protocol - typical protocols are TLS, TLSv1.1, TLSv1.2

Default: blank, meaning JDK default.
JSON key: ssl.protocol

Allow renegotiate 

Allow unsecure renegotiation, turn off for best security.

Default: false
JSON key: allowrenegotiate 

Exclude protocols

Comma/semicolon separated list of SSL protocols to exclude from the JCE default protocols list - patterns are regex expressions.

Default: SSL,SSLv2,SSLv2Hello,SSLv3
JSON key: excludeprotocols 

Include protocols

Comma/semicolon separated list of protocols to include from the JCE supported protocols list - patterns are regex expressions

Default: none, meaning JDK default
JSON key: includeprotocols 

Use ciphersuites order

If set, use configured cipher suites order and prefer first, if not set order does not matter when selecting which cipher suite to use.

Default: true
JSON key: useciphersuites.order 

Exclude ciphersuites

Comma/semicolon separated list of ciphersuites to exclude from the JCE default ciphersuites list - patterns are regex expressions.

Default: .*NULL.*,.*RC4.*,.*MD5.*,.*DSS.*
JSON key: excludeciphersuites 

Include ciphersuites

Comma/semicolon separated list of ciphersuites to include from the JCE supported ciphersuites list - patterns are regex expressions

Default: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_,SSL_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA
JSON key: includeciphersuites 

Truststore type

Type of truststore, e.g. PKCS12, or JKS (default PKCS12

Default: PKCS12
JSON key: truststore.type 

Truststore provider

Name of JCE provider (default BC)

Default: BC
JSON key: truststore.provider 

Truststore file

Name of and path to file containing truststore

Default: none
JSON key: truststore.file 

Truststore password

Password for the truststore and keys within - can optionally be encrypted/obfuscated

Default: none
JSON key: truststore.password 

Ping

Ping settings are defined for all target servers in a destination, they are stored in the JSON object ping inside the destination.

Ping

HTTP Method

HTTP Method to use when pinging (usually HEAD or GET)

Default: HEAD
JSON key: method 

URI / Path

Path and optionally query parameters to use when pinging

Default: /
JSON key: uri 

Expected response code

Pattern for expected response codes, e.g. 2??|3??

Default: 200
JSON key: expect 

Ping interval (seconds)

Ping interval in seconds - set to -1 or 0 to disable - 30 is default

Default: 30
JSON key: interval.seconds 

Timeout (seconds)

Timeout in seconds, maximum time to wait for reply when pinging - 10 is default

Default: 10
JSON key: timeout.seconds 

Verification script

Script used to verify response content, called with input set to the response content.

A Ping verification script is called when "pinging" target servers to check if they are up or not - this allows the script to look at response body contents and not just rely on http response code to determine if the server is fit for sending requests to or not.
The script is called with input set to contain the response body, and state set to the usual StateHolder instance. via state, the plugin can access the full response headers.

if (input.contains('Looks good to me'))
  true;
else
  false;

Default: none
JSON key: response.verify.script 

Limits

Limits for each server in this destination, unless specifically overridden for a specific target server.

Limits are stored in the limits JSON Object inside the specific destinations JSON Object.

Limits on connections and queues

Max concurrent per IO thread

Maximum number of concurrent requests (PER IO THREAD) for a target server, requests above this limit will be queued (default is 20). See the settings for number of IO threads here: Config - Gateway Settings

Default: 20
JSON key: max.concurrent.requests 

Queue size

Number of connections that can be queued waiting for an available connection

Default: 500
JSON key: queue.length 

Timeout in seconds

Request timeout in seconds - maximum number of seconds to wait for a reply from the server.

Default: 30
JSON key: timeout.seconds 

Max idle connections

Maximum number of idle connections to a target server - connections exceeding this count will be closed instead of being pooled for new requests.

Default: 20
JSON key: max.idle.connections.hard 

Minimum idle connections 

The minimum number of connections that this proxy connection pool will try and keep established. Once the pool is down to this number of connections no more connections will be timed out.

Default: 5
JSON key: max.idle.connections.soft 

Idle timeout (milliseconds)

Number of milliseconds until timing out idle connections above the minimum limit, set to 0 or -1 to disable

Default: -1
JSON key: idle.ttl

Authentication

Authentication is a way of specifying authentication between the Gateway, and the target server - this has nothing to do with authentication of the user, but it can use information about an authenticated user.

Authentication information is stored in the JSON object authentication for each destination.

Destination authentication

Authentication plugins

Java classes which knows how to add authentication information to backend servers.

You can add multiple authentication plugins, all which are given a chance to add authentication information to the request before it is sent to the target server.

Default: none
JSON key: plugins contains an JSON array with a set of strings, each a java classname specifying the authentication plugin name.

See Plugins -TargetAuthenticationPlugin for more information on target authentication plugins, which ones exist by default, and how to write them.

The following standard target authenticator plugins exist:

• io.ceptor.authentication.target.TAuthenticatorBasicAuth
  This plugin can perform basic authentication against the target server - it can supply both a configured value, pick one from the session, or it can forward the session ID of the authenticated user as userid. This can be configured differently for anonymous and authenticated users. Often, this plugin is used to make it easier to integrate with various application servers, e.g. when using WebLogic SSPI plugins, PP Agent within weblogic is triggered by the session ID being transmitted in the basic authorization header as if it were a userid. 
• io.ceptor.authentication.target.TAuthenticatorSSL
  Allows adding SSL certificate information to the request HTTP headers - e.g. if user was authenticated using an SSL client certificate, the used cypher, SSL session ID and client certificate can be added as HTTP headers. Note that SSL certificate authentication is not done by this plugin, since it would require access to the end-users private key - instead, the information is forwarded in HTTP headers.
  If you need to use a specific SSL client certificate in the communication with the target server, you can set that up in the SSL settings in the destination / target server configuration. 
• io.ceptor.authentication.target.TAuthenticatorBearerToken
  Allows forwarding of a bearer token obtainted from the client to the target server, or creation of a new token/ticket which can be sent in a bearer token to the target server. 
• io.ceptor.authentication.target.TAuthenticatorSPNEGO
  Allows using SPNEGO/Kerberos authentication towards the target server - can either user authenticated users userid/password, or a configured one or one taken from other state variables within the session. 
  
  

Scripts and Macros can be used to obtain the information for the configuration for the values below, e.g. to use the userid of the current authenticated user.

Basic authentication (TAuthenticatorBasicAuth)

When the TAuthenticatorBasicAuth plugin is installed, these configuration options are used for it. They are stored in the JSON object basicauth inside the authentication JSON.

Anonymous userid

Basicauth userid to set for anonymous users. 

Default is: %{REQUEST_ID}
JSON key: anonymous.userid

Anonymous password

Basicauth password to set for anonymous users.

Default is: password
JSON key: anonymous.password 

Authenticated userid

Basicauth userid to set for authenticated users

Default is: %{REQUEST_ID}
JSON key: userid

Authenticated password

Basicauth password to set for authenticated users

Default is: password
JSON key: password 

SSL authentication (TAuthenticatorSSL)

When the TAuthenticatorSSL plugin is installed, these configuration options are used for it. They are stored in the JSON object ssl inside the authentication JSON.

SSL Cipher headername

Name of HTTP header to place SSL cipher name in.

Default is: SSL_CIPHER
JSON key: header.cipher

SSL session ID header

Name of HTTP header to place SSL session ID in.

Default is: SSL_SESSION_ID
JSON key: header.sessionid

SSL client cert header

Name of HTTP header to place SSL client certificate in.

Default is: SSL_CLIENT_CERT
JSON key: header.clientcert 

Bearer token authentication (TAuthenticatorBearerToken)

When the TAuthenticatorBearerToken plugin is installed, these configuration options are used for it. They are stored in the JSON object bearer inside the authentication JSON.

Authentication plugin ID

ID of authentication plugin in Ceptor Session Controller to use when obtaining bearer token (default is 48 - AuthTypes.AUTHTYPE_OAUTH2)

Default: 48
JSON key: authenticationplugin 

Forward token from request

If bearer token is present in the request input, forward it to the server instead of obtaining one from the authentication plugin, or from the session.

Default: true
JSON key: forward.from.request

Use ticket from session

If ticket/token is present in session, use that as bearer token (unless "Forward token from request" is set, and there was a token available).

Default: true
JSON key: use.ticket.from.session 

Input to newToken()

When calling authentication plugin's newToken() method to create a token, this is the input to it.
Note that the newToken() is a method in the authentication plugin on the session controller, which will be called to create the ticket - it might require specific input to select the type of token/ticket to generate.

Default: null
JSON key: call.newtoken 

Base64 encode token

If token should be base64 encoded before being sent, after obtained from the authentication plugin.

Default: false
JSON key: base64encode 

SPNEGO authentication (TAuthenticatorSPNEGO)

When the TAuthenticatorSPNEGO plugin is installed, these configuration options are used for it. They are stored in the JSON object spnego inside the authentication JSON.

Anonymous userid

SPNEGO userid to set for anonymous users. 

Default is: %{REQUEST_ID}
JSON key: anonymous.userid

Anonymous password

SPNEGO password to set for anonymous users.

Default is: password
JSON key: anonymous.password 

Authenticated userid

SPNEGO userid to set for authenticated users

Default is: %{REQUEST_ID}
JSON key: userid

Authenticated password

SPNEGO password to set for authenticated users

Default is: password
JSON key: password 

Logincontext name

Name of login-context.

Default is: kerberos-client
JSON key: logincontext 

SPNEGO Hostname

PNEGO hostname that the ticket is created for - must match the hostname expected by the target server.

Default is: none (must be specified)
JSON key: hostname