Properties reference

Application property setup

The Onegini Security Proxy uses environment variables to manage its application properties. These variables need to be set in the docker-compose.yml file. The required column indicates which properties are mandatory to start the Security Proxy.

Security Proxy general config

The Security Proxy needs a key/value store (Consul). The configuration for connecting with this store can be done with the following environment variables.

Property Required Example Description
CONSUL_HTTP_ADDR yes 192.168.100.78:8500 IP address with port of Consul
APPLICATION_NAME no test Alpha-numeric identifier of this Security Proxy instance

NOTE: The APPLICATION_NAME can be used when multiple Security Proxy instances are using the same Consul cluster. The APPLICATION_NAME will act as a key/value store prefix in Consul.

Token Server

The Security Proxy needs at least one Token Server instance but it can handle as many instances as you have installed. It will automatically load balance the requests between all the configured Token Server instances that are running.

Token Server general config

Property Required Example Description
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​HOSTS yes Comma-separated list of backend token servers.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​CONTEXT_​ROOT no /oauth The context root of the Token Server, used for non encrypted data. It must be /oauth.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​PROXY_​SCHEME no http The protocol scheme used to communicate to the back end.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​PROXY_​API_​ENABLED no true Indicates whether the Token Server API should be exposed through the Security Proxy.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​PROXY_​API_​ALLOW no 0.0.0.0/0 The allowed client ip address or address range in CIDR notation for the api.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​ALLOW no 0.0.0.0/0 The allowed client ip address or address range in CIDR notation.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​PROXY_​SSL_​SNI_​ENABLED no true Turns on/off SNI for the proxied token server backend
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​PROXY_​SSL_​NAME no tokenserver.internal Overrides the server name used to verify the certificate of the proxied backend
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​HEALTHCHECK_​LOG_​ENABLED no true Enable/disable the logging of healthcheck requests. Defaults to false.

Resource gateway

The resource gateway back-ends serve APIs that you want to expose to mobile devices. You can add as many resource gateways as you like as long as you specify a unique context root for each resource gateway. Please note that the /oauth context root is reserved for the Token Server back-end.

Resource gateway(s) general config

Per type of resource gateway you need to add the general config below. The <RGID> is used identify this resource gateway available to the Security Proxy. <RGID> needs to be replaced with a label that corresponds with the resource gateway e.g. for the gateway that serves the customer data you could choose: CUSTOMER_API as the <RGID>.

Property Required Example Description
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CONTEXT_ROOT yes /resources/images The context root of the resource, used for non encrypted data.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_PROXY_SCHEME no http The protocol scheme used to communicate to the back end.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_SERVER_NAME no api.example.com Server name to listen on.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_ALLOW no 0.0.0.0/0 The allowed client ip address or address range in CIDR notation.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_HOSTS yes 192.168.118.151:8080 A comma separated list of resource backends (hostname or ip address).
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_TOKEN_VALIDATION_ENABLED no false Enable or disable token validation for this resource gateway.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CUSTOM_HOST_HEADER no external.api.example.dev Sets a custom host header in the request to external endpoint.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_SSL_CERTIFICATE_NAME no rgid Name of the SSL certificate for this resource gateway (must match SECURITY_PROXY_SSL_CERTIFICATE_<RGID> and SECURITY_PROXY_SSL_KEY_<RGID>).
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_PROXY_SSL_SNI_ENABLED no true Turns on/off SNI for the proxied resource gateway backend.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_PROXY_SSL_NAME no resource.internal Overrides the server name used to verify the certificate of the proxied backend.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CORS_ENABLED no true Enables support for Cross-Origin Resource Sharing (CORS). The default value is false.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CORS_ALLOW_ORIGIN no https://example.com The origins that will be communicated in the Access-Control-Allow-Origin header returned by the Security Proxy, the default value is *.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CORS_ALLOW_METHODS no * Specifies the method or methods allowed when accessing the resource in response to a preflight request, the default value is *.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CORS_ALLOW_HEADERS no * Indicates which HTTP headers can be used during the actual resource call, the default value is *.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CORS_ALLOW_CREDENTIALS no false Response header that tells browsers whether to expose the response to frontend JavaScript code when the request's credentials mode (Request.credentials) is included. The default value is false.
SECURITY_PROXY_BACK_END​_RESOURCE_GATEWAYS_<RGID>​_CORS_MAX_AGE no 7200 Indicates how long the results of a preflight request can be cached (in seconds). The default value is 7200 seconds (2 hours).

TLS/SSL

TLS/SSL generic config

Property Required Description
SECURITY_​PROXY_​SSL_​ENABLED yes Enable/disable TLS/SSL support
SECURITY_​PROXY_​SSL_​PROTOCOLS no TLS/SSL protocol versions
SECURITY_​PROXY_​SSL_​CIPHERS no TLS/SSl cipher suites
SECURITY_​PROXY_​SSL_​CERTIFICATE_​DEFAULT yes if SSL enabled The ssl certificate of the server in PEM format
SECURITY_​PROXY_​SSL_​KEY_​DEFAULT yes if SSL enabled The ssl private key of the server in PEM format

Note: The certificate and key have to be converted to a single line where newlines have been replaced with \n

TLS/SSL additional certificates

Resource gateways and transparent proxies that use a SERVER_NAME can have their own certificates. These can be set with the following environment keys:

  • SECURITYPROXY_SSL_CERTIFICATE<NAME>
  • SECURITYPROXY_SSL_KEY<NAME>

The name should match the SECURITY_PROXY_BACK_END_RESOURCE_GATEWAYS_<RGID>_SSL_CERTIFICATE_NAME or SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_<PROXYID>_SSL_CERTIFICATE_NAME

Transparent proxies

Per type of transparent proxy you need to add the general config below. The <PROXYID> is used to identify this transparent proxy. <PROXYID> needs to be replaced with something that corresponds with the transparent proxy e.g. for the gateway that serves the CIM: CIM as the <PROXYID>.

Property Required Example Description
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​CONTEXT_ROOT yes / The context root of the proxied backend.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​PROXY_SCHEME no http The protocol scheme used to communicate to the back end.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​SERVER_NAME no api.example.com Server name to listen on.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​ALLOW no 0.0.0.0/0 The allowed client ip address or address range in CIDR notation.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​HOSTS yes 192.168.118.151:8080 A comma separated list of proxied backends (hostname or ip address).
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​CUSTOM_HOST_HEADER no external.api.example.dev Sets a custom host header in the request to external endpoint.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​SSL_CERTIFICATE_NAME no proxyid Name of the SSL certificate for this transparent proxy (must match SECURITYPROXY_SSL_CERTIFICATE and SECURITYPROXY_SSL_KEY)
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​STICKY_SESSIONS no true When enabled the loadbalancing to the backend hosts will be stickied based on source ip address
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​BACKEND_SET_X_FRAME_OPTIONS no true When disabled the Security Proxy (default) removes any value specified by the backend and sets the X-Frame-Options header with value deny. When enabled the Security Proxy does not set the X-Frame-Options header, but the backend can control it.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​PROXY_SSL_SNI_ENABLED no true Turns on/off SNI for the proxied resource gateway backend
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>_​PROXY_SSL_NAME no transparent.internal Overrides the server name used to verify the certificate of the proxied backend

Transparent proxies - locations

A transparent proxy with a SERVER_NAME configured can also have multiple locations pointing to different backend upstreams. This can be configured by the following properties:

Note: This will only work for a transparent proxy that has a SERVER_NAME configured.

Property Required Example Description
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_CONTEXT_ROOT no /location The context root of the proxied backend location.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_PROXY_SCHEME no http The protocol scheme used to communicate to the back end.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_ALLOW no 127.0.0.1 The allowed client ip address or address range in CIDR notation.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_HOSTS no 192.168.118.151:8080 A comma separated list of proxied backends (hostname or ip address).
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_STICKY_SESSIONS no true When enabled the loadbalancing to the backend hosts will be stickied based on source ip address
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_BACKEND​_SET_X_FRAME_OPTIONS no true When disabled (default) the Security Proxy removes any value specified by the backend and sets the X-Frame-Options header with value deny. When enabled the Security Proxy does not set the X-Frame-Options header, but the backend can control it.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_CUSTOM_HOST_HEADER no external.api.example.dev Sets a custom host header in the request to external endpoint.
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_PROXY_SSL_SNI_ENABLED no true Turns on/off SNI for the proxied resource gateway backend
SECURITY_PROXY_BACK_END_​TRANSPARENT_PROXIES_<PROXYID>​_LOCATIONS_<LOC>_PROXY_SSL_NAME no transparent-loc.internal Overrides the server name used to verify the certificate of the proxied backend

Security proxy trusted certificates

Property Required Example Description
SECURITY_​PROXY_​SSL_​LUA_​TRUSTED_​CERTIFICATE yes /etc/pki/tls/certs/ca-bundle.crt Specifies a file path with trusted CA certificates in the PEM format used to verify the certificate of the SSL/TLS server.
SECURITY_​PROXY_​SSL_​LUA_​VERIFY_​DEPTH yes 3 Sets the verification depth in the server certificates chain.
SECURITY_​PROXY_​NGINX_​DNS no 8.8.8.8 DNS address (resolver) used by nginx to resolve dns names.

Property Encryption

Property Required Description
SECURITY_​PROXY_​COMMON_​PROPERTY_​ENCRYPTION_​PASSWORD yes The password that is used to encrypt and decrypt property values

Generic properties

Property Required Example Description
SECURITY_​PROXY_​TOKEN_​SERVER_​API_​CLIENT_​ID yes username The username used to authenticate with the Token Server in order to fetch the Payload encryption policy and perform token introspection.
SECURITY_​PROXY_​TOKEN_​SERVER_​API_​CLIENT_​SECRET yes password The password used for authentication with the Token Server for the above mentioned API's.
SECURITY_​PROXY_​CACHE_​ENCRYPTION_​PASSWORD yes The password used to encrypt values in the cache. Make sure to choose a strong password. In case of a high-available Security Proxy setup the passwords must match on all nodes.
SECURITY_​PROXY_​ENGINE_​ENCRYPTION_​POLICY_​CACHE_​TTL no 5m The time the encryption policy may be cached by the Security Proxy. Specified as a 'Duration'
SECURITY_​PROXY_​ENGINE_​ENCRYPTION_​POLICY_​CACHE_​MAX_​SIZE no 1000 The amount of encryption policies that can be cached.
SECURITY_​PROXY_​ENGINE_​SESSION_​KEYS_​CACHE_​TTL no 30m Sets the maximum time an encrypted session can be used. Specified as a 'Duration'
SECURITY_​PROXY_​ENGINE_​NONCE_​VALIDATION_​CACHE_​TTL no 60m Sets the maximum time an entry will stay in the nonce validation cache. Specified as a 'Duration'
SECURITY_​PROXY_​ENGINE_​NONCE_​VALIDATION_​CACHE_​MAX_​SIZE no 10000 Sets the maximum number of entries stored in the nonce validation cache.
SECURITY_​PROXY_​COMMON_​MAX_​BODY_​SIZE_​BYTES no 1m The maximum allowed size of the client request body, specified in the Content-Length request header. Setting size to 0 disables checking of the client request body size. The default value is 1M (1 MegaByte).
SECURITY_​PROXY_​NGINX_​ACCESS_​LOG_​PATH no /var/log/nginx/access.log Sets an alternative location for the nginx access logs.
SECURITY_​PROXY_​NGINX_​ERROR_​LOG_​PATH no /var/log/nginx/error.log Sets an alternative location for the nginx error logs.
SECURITY_​PROXY_​NGINX_​ALLOW_​INVALID_​HEADERS no false (default) Corresponds to the nginx directive ignore_invalid_headers. If set to true, it sets the directive to off so that headers with periods and other characters deemed invalid by nginx are allowed to pass through.

Redis properties

Property Required Example Description
SECURITY_​PROXY_​REDIS_​SENTINEL_​NODES yes redis1.example.com:6379,redis2.example.com:6379 Comma separated list of Redis sentinel nodes in the form of host:port.
SECURITY_​PROXY_​REDIS_​SENTINEL_​MASTER_​ID yes mymaster The name of the Redis master.
SECURITY_​PROXY_​REDIS_​PASSWORD no The password used to authenticate with the Redis server.

Token Validation Result Caching

In order to reduce the load on the Token Server and reduce the load times of the requests the token validation result can be cached for some period of time.

Property Default value Description
SECURITY_​PROXY_​TOKEN_​VALIDATION_​SERVICE_​CACHE_​TOKEN_​VALIDATION_​RESULT_​CACHE_​TTL 0s The maximum time a token validation result can be available in cache. Specified as a 'Duration'

Note: For highest security we would advice to not use cache (so to leave this setting to its default value). But a setting of 30 or 60 seconds is acceptable.

Note: Tokens with limited usage won't be cached.

Tuning JVM

The Onegini Security Proxy starts two Java processes. One of the processes is for payload encryption and the other one is for token validation. For both processes the JVM can be tuned independently. Therefore three environment variables can be set.

Property Description
JAVA_OPTS These Java options will be applied to all Java components and can be used in combination with the component specific settings.
TVS_JAVA_OPTS These Java options will be applied to the token validation component only.
SP_JAVA_OPTS These Java options will be applied to the payload encryption component only.

Proxy properties

Property Description
SECURITY_​PROXY_​X_​FORWARDED_​DISABLED The flag specifies if setting headers X-Forwarded-Host and X-Forwarded-Port should be disabled for proxied requests. Default value false.
SECURITY_​PROXY_​X_​FORWARDED_​PROTO_​DISABLED The flag specifies if setting headers X-Forwarded-Proto should be disabled for proxied requests. Default value false.

Rest services

The Onegini Security Proxy calls endpoints in the Token Server for payload encryption and token validation via Java processes. The following environment variables can be set to make the connection more resilient in case the Token Server takes too long to respond.

Property Default Description
RESTSERVICES_​WAITFORAVAILABLECONNECTIONINPOOLTIMEOUT 5s Timeout for waiting for available connection in pool
RESTSERVICES_​READTIMEOUT 10s Request read timeout
RESTSERVICES_​CONNECTIONTIMEOUT 2500ms Request connection timeout