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"
        },
        "request.headers": [
          {
            "name": "X-Forwarded-For",
            "value": "%{REMOTE_ADDR}"
          }
        ],
        "response.headers": []
      }
    },
	{
      "sslcontext": {
        "ssl.protocol": "TLS",
        "keystore.provider": "BC",
        "keystore.type": "PKCS12",
        "verify.server.certificate": true,
        "verify.server.name": true,
        "excludeprotocols": "SSLv3",
        "allowrenegotiate": false,
        "trusted.server.certificates": [],
        "excludeciphersuites": ".*NULL.*,.*RC4.*,.*MD5.*,.*DSS.*",
        "includeprotocols": "TLS.*",
        "includeciphersuites": "TLS_ECDHE.*,SSL_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA",
        "useciphersuites.order": true
      },
      "http2.enable": true,
      "keepalive.enable": true,
      "max.connect.retries": 3,
      "ping": {
        "expect": "200|302",
        "method": "HEAD",
        "uri": "/",
        "interval.seconds": 60
      },
      "name": "google",
      "sticky": false,
      "keep.hostheader": true,
      "description": "Proxying requests to google",
      "targets": [{
        "scheme": "https",
        "port": 443,
        "unavailable": false,
        "name": "google1",
        "host": "www.google.com",
        "disabled": false
      }]
    },
  ]
}

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 stickiness (hash of name is in the 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: false
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

Keep Host header

If set, existing HOST header is kept and forwarded unmodified to the target server - if not, it is discarded and a new HOST header matching the target servers host and port is sent instead.

Default: false
JSON key: keep.hostheader

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

Max connect retry attemps

The number of retries in case connection fails to one of the target servers.

Default: 3
JSON key: max.connect.retries

TCP Binding

Bind Address

If specified, this is the address to bind to when making the connection to the target server - leave blank to auto assign. 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 too.
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 requests has the exact same hostname as this one.
If the classifier is left as "default" then 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 

Keystore type

Type of keystore, e.g. PKCS12, or JKS - must be a type supported by the specified Keystore provider.

Default: PKCS12
JSON key: keystore.type 

Keystore provider

Name of JCE provider (default BC - BouncyCastle Provider)

Default: BC
JSON key: keystore.provider 

Keystore file

Name of and path to file containing keystore - if specified, the keys herein are used as SSL client certificates when communicating with the target server.

Default: none
JSON key: keystore.file 

Keystore password

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

Default: none
JSON key: keystore.password 

Verify Server Certificate

If uncheckecked, server certificate is NOT checked for validity, and Trusted Certificates as well as Truststore settings are not used - in this case, all server certificates are accepted regardless of their validity.

Default: true
JSON key:  verify.server.certificate

Verify Server Name

Uncheck to turn off server hostname validation - if not checked, the hostname in the SSL server certificate is ignored and not compared to the configured hostname/IP.

Default: true
JSON key: verify.server.name

Trusted Certificates

List of trusted server certificates - if specified, then truststore is NOT used.
Specify a list of filenames available on the gateway containing either .cer, .p7b or .der certificates. Can be used as an alternative to specifying a truststore containing a number of certificates.

Can also contain the server certificates themselves, in PEM encoding - in that case, prefix with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE----- any spaces between these two lines are converted to linefeeds before parsing the certificate - this allows you to specify a long line with the certificate bytes, or cut and paste the certificate into the textfield directly from a .cer file.

Default: empty
JSON key: trusted.server.certificates 
Minimum version: 5.62 

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 know 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 obtained 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. 
• io.ceptor.authentication.target.TAuthenticatorLTPAToken
  Allows creation of an LTPA token which is sent in a cookie to the backend application server. Enables easy integration with various IBM products supporting LTPA authentication.

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

-Djava.security.krb5.conf=${ceptor.home}/config/spnego/krb5.conf
-Djava.security.auth.login.config=${ceptor.home}/config/spnego/login.conf

LTPA Token Authentication

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

Authentication Plugin ID

ID of authentication plugin to use when obtaining ltpa token (default is 56 - AuthTypes.AUTHTYPE_LTPA)

Default is: 56
JSON key: authenticationplugin

Forward token from request

If ltpa token is present in the request input, forward it.

Default is: true
JSON key: forward.from.request

Use token from session

If ltpa is present in session (pp_ltpatoken), use that as ltpa token.

Default is: true
JSON key: use.token.from.session

Input to newToken()

When calling authentication plugin's newToken() method to create a token, this is the input to it.

Note that this input is either the token name as a plain text, or it can be a string in JSON format - if JSON, the token name can be present in the tokenname attribute.
Example:

{"tokenname": "liberty1", "additionalattribute": "visible to creation script"}

Default is: empty
JSON key: call.newtoken

Cookie name

Name of cookie to place LTPA Token within

Default is: LTPAToken2
JSON key: cookiename

Request Headers

Configuration for request headers is stored in the JSON array request.headers within the destination- each element in the array is a JSON Object containing a name and value.

If the value is an empty string, or null then the corresponding header will be removed from the request in case it was present already.

When you click Add, you get a dialog where you can enter a name and value:
 

You can edit the header name/value after adding it on this screen:
 

HTTP Header configuration

Name

Name of HTTP Request header to add or replace

Default: none, must be specified
JSON key: name 

Value

Value of the HTTP Request header - set to an empty string or null to remove the header instead of adding it.
You can use Scripts and Macros to generate the value. 

Default: blank
JSON key: value

Response Headers

You can configure HTTP Response Headers that are added to the response before sending it.

Response headers are stored in a JSON Array called response.headerswithin the location.

When you click "Add", you get the dialog below, where you can specify the name and value of the response header to add: 

Once a header is added, you can edit it on this screen:
 

HTTP header configuration

Name

Name of HTTP Header

Default: none, must be specified
JSON key: name 

Value

Value of HTTP Header

%{rewrite:responseheader:location;"http\:\/\/(.*)$";"CASE_INSENSITIVE";"https://$1"}

Default: empty
JSON key: value