This section describes how to configure the Security Proxy properties. It's divided into the following subsections:

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.

Reverse proxy configuration

The Security Proxy is a reverse proxy. It serves content that is provided by other servers. It should however know where it can find these servers.

There are two kinds of back-ends defined in the Security Proxy that need to be configured:

  • Token Server: Requests that are meant for the Token Server should be routed to the Token Server
  • Resource gateway: Data requests to transport (personalized) data to a mobile device must be handled by a resource gateway

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 Default Description
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​CONTEXT_​ROOT /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 http The protocol scheme used to communicate to the back end.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​REQUEST_​TYPE token-server Indicates that this is the Token Server endpoint.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​PROXY_​API_​ENABLED true Indicates whether the Token Server API should be exposed through the Security Proxy.
SECURITY_​PROXY_​BACK_​END_​TOKEN_​SERVER_​ALLOW The allowed client ip address or address range.

For multiple Token Servers a <RGID> should be included in the property name. Please note the defaults are not applied to properties with this <RGID> included. An example property name for RGID A: SECURITY_PROXY_BACK_END_A_CONTEXT_ROOT.

Token Server instances

To connect the Security Proxy to all running Token Server instances you need to add an unique host record for each instance.

Property Required Example Description
SECURITY_PROXY_BACK_END_TOKEN_SERVER_HOSTS_<HOSTID> yes The host record for a Token Server instance.

The <HOSTID> must be replaced with the name of the Token Server. E.g. TOKEN_SERVER1 for the first server, TOKEN_SERVER2 for the second server, etc.

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 you can add as many resource gateways as possible. Please note that the /oauth context root is reserved for the Token Server back-end.

Currently the Security Proxy only supports transparent proxying. This means that the full URI (without the host) that is called by the client is also used to retrieve data from the back-end. E.g. is the URL that is retrieved by the client. This will result in the following call to the back-end: https://back-end.internal/product/123.

Below you see an example for multiple resource gateways:

For instance let's assume you have two APIs that are served by two different servers. You have a customer API and a product API. In this case you need to create two resource back-ends. The list below shows the example context roots or URL prefixes for both API.

This will result in the following two back-end configurations

1: customer-api

  • context-root: /customer
  • proxy-scheme: http
  • request-type: resource
  • hosts: server-a.internal:8080

2 product-api

  • context-root: /product
  • proxy-scheme: https
  • request-type: resource
  • hosts: server-b.internal:9443

Below the specific properties specified below are specified in more detail.

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 something 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_<RGID>_CONTEXT_ROOT yes /resource The context root of the resource, used for non encrypted data.
SECURITY_PROXY_BACK_END_<RGID>_PROXY_SCHEME yes http The protocol scheme used to communicate to the back end.
SECURITY_PROXY_BACK_END_<RGID>_REQUEST_TYPE yes resource Indicates that this is a resource endpoint.
SECURITY_PROXY_BACK_END_<RGID>_SERVER_NAME no Server name to listen on.
SECURITY_PROXY_BACK_END_<RGID>_ALLOW yes The allowed client ip address or address range.
SECURITY_PROXY_BACK_END_<RGID>_HOSTS yes A comma separated list of resource backends (hostname or ip address).
SECURITY_PROXY_BACK_END_<RGID>_TOKEN_VALIDATION_ENABLED no false Enable or disable token validation for this resource gateway.
SECURITY_PROXY_BACK_END_<RGID>_CUSTOM_HOST_HEADER no Sets a custom host header in the request to external endpoint.

Resource gateway based on server name

It is also possible to listen on the domain name instead of path. to enable this functionality set the following property:

Property Required Example Description
SECURITY_​PROXY_​SERVER_​NAME_​ROUTING no true Enable server name based routing for resource endpoints.


Property Required Description
SECURITY_​PROXY_​SSL_​ENABLED yes Enable/disable TLS/SSL suport
SECURITY_​PROXY_​SSL_​CERTIFICATE yes if SSL enabled The ssl certificate of the server in PEM format
SECURITY_​PROXY_​SSL_​CERTIFICATE_​KEY yes if SSL enabled The ssl private key of the server in PEM format

Note: If you configure SECURITY_PROXY_SERVER_NAME_ROUTING you can only use self-signed or multi-domain certificates.

Security proxy trusted certificates

Property Required Default 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 DNS address (resolver) used by nginx to resolve dns names.

Property Encryption

Property Required Description
SECURITY_​PROXY_​COMMON_​PROPERTY_​ENCRYPTION_​PASSWORD true 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_​ENGINE_​ENCRYPTION_​POLICY_​CACHE_​DURATION_​IN_​MINUTES no 5 The time the encryption policy may be cached by the Security Proxy.
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_​DURATION_​IN_​MINUTES no 30 Sets the maximum time an encrypted session can be used specified in minutes.
SECURITY_​PROXY_​ENGINE_​NONCE_​VALIDATION_​CACHE_​DURATION_​IN_​MINUTES no 60 Sets the maximum time an entry will stay in the nonce validation cache specified in minutes.
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).

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_​SECONDS 0 The maximum time a token validation result can be available in cache.

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 independent. 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.

CIM / UMA Proxy

Property Required Example/Default Description
SECURITY_​PROXY_​PROXY_​CIM_​ENABLED no false Enable or disable the proxy for CIM.
SECURITY_​PROXY_​PROXY_​CIM_​SERVER_​NAME yes if CIM enabled This is the URL where the proxy is listening on for CIM requests.
SECURITY_​PROXY_​PROXY_​CIM_​ALLOW no This is a CIDR notated IP block which acts as a whitelist for requests to the CIM.
SECURITY_​PROXY_​PROXY_​CIM_​BACKEND_​HOSTS yes if CIM enabled, This is a comma-separated list of backend hostnames or IP's with port of the CIM backends
SECURITY_​PROXY_​PROXY_​CIM_​PROXY_​SCHEME no http This is the scheme of the backend connections (either http or https).
SECURITY_​PROXY_​PROXY_​CIM_​SSL_​ENABLED no false Enable or disable SSL termination on the Security Proxy for the CIM backends.
SECURITY_​PROXY_​PROXY_​CIM_​SSL_​CERTIFICATE yes if SSL enabled The certificate for SSL termination on a single line where newlines are replaced by \n.
SECURITY_​PROXY_​PROXY_​CIM_​SSL_​PRIVATE_​KEY yes if SSL enabled The private key for SSL termination on a single line where newlines are replaced by \n.
SECURITY_​PROXY_​PROXY_​CIM_​SSL_​PROTOCOLS no TLSv1 TLSv1.1 TLSv1.2 Space-separated list of protocols supported for SSL connections.
SECURITY_​PROXY_​PROXY_​CIM_​SSL_​CIPHERS no HIGH:!aNULL:!eNULL Colon-separated list of ciphers supported for SSL connections. Defaults to a secure set of ciphers.
SECURITY_​PROXY_​PROXY_​CIM_​X_​FORWARDED_​PROTO_​DISABLED no false Disable the X-Forwarded-Proto header.
SECURITY_​PROXY_​PROXY_​CIM_​X_​FORWARDED_​HOST_​DISABLED no false Disable the X-Forwarded-Host header.
SECURITY_​PROXY_​PROXY_​CIM_​X_​FORWARDED_​PORT_​DISABLED no false Disable the X-Forwarded-Port header.

Note: The same properties are also available for the UMA proxy by replacing CIM with UMA in the property names.