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_PROTOCOLS | no | TLSv1.3 | The enabled SSL protocols for the proxied token server backend. Defaults to TLSv1.2 TLSv1.3. |
| 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_PROTOCOLS |
no | TLSv1.3 | The enabled SSL protocols for the proxied resource gateway backend. Defaults to TLSv1.2 TLSv1.3. |
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). |
SECURITY_PROXY_BACK_END_RESOURCE_GATEWAYS_<RGID>_HIDE_UPSTREAM_HEADERS |
no | true | If enabled (default), it will hide certain headers from the responses (X-XSS-Protection, X-Content-Type-Options, Strict-Transport-Security) |
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:
- SECURITY_PROXY_SSL_CERTIFICATE_
<NAME> - SECURITY_PROXY_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 SECURITY_PROXY_SSL_CERTIFICATE_ |
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_PROTOCOLS |
no | TLSv1.3 | The enabled SSL protocols for the proxied backend. Defaults to TLSv1.2 TLSv1.3. |
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_<PROXYID>_PROXY_SSL_SNI_ENABLED |
no | true | Turns on/off SNI for the proxied 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 |
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_<PROXYID>_HIDE_UPSTREAM_HEADERS |
no | true | If enabled (default), it will hide certain headers from the responses (X-XSS-Protection, X-Content-Type-Options, Strict-Transport-Security) |
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_NAMEconfigured.
| 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>BACKENDSET_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_PROTOCOLS |
no | TLSv1.3 | The enabled SSL protocols for the proxied backend. Defaults to TLSv1.2 TLSv1.3. |
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_<PROXYID>LOCATIONS<LOC>_PROXY_SSL_SNI_ENABLED |
no | true | Turns on/off SNI for the proxied 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_BACK_END_TRANSPARENT_PROXIES_<PROXYID>LOCATIONS<LOC>_HIDE_UPSTREAM_HEADERS |
no | true | If enabled (default), it will hide certain headers from the responses (X-XSS-Protection, X-Content-Type-Options, Strict-Transport-Security) |
Extra headers¶
Additional headers can be configured to be added for both the upstream request and the upstream response. The <NAME> in this case is not actually used, so can be set to any name as long as it is unique.
| Property | Required | Example value |
|---|---|---|
SECURITY_PROXY_BACK_END_RESOURCE_GATEWAYS_<PROXYID>EXTRA_HEADERS<NAME> |
no | My-Header header-value |
SECURITY_PROXY_BACK_END_RESOURCE_GATEWAYS_<PROXYID>EXTRA_RESPONSE_HEADERS<NAME> |
no | Referrer-Policy no-referrer-when-downgrade |
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_<PROXYID>EXTRA_HEADERS<NAME> |
no | My-Header header-value |
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_<PROXYID>EXTRA_RESPONSE_HEADERS<NAME> |
no | Referrer-Policy no-referrer-when-downgrade |
Example:
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_TESTPROXY_EXTRA_HEADERS_MYHEADER="My-Header header-value"
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_TESTPROXY_EXTRA_RESPONSE_HEADERS_REFPOL="Referrer-Policy no-referrer-when-downgrade"
In the above example the Security Proxy will add the header My-Header to the request sent to the upstream backend. Secondly, it will add the Referrer-Policy to the response received from the upstream 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_TENANT_ID | no | 4c3be75d-e24c-4d9e-b6dd-473649aef104 | The identifier of the tenant to be sent as a Tenant-Id header in all outgoing requests from the Security Proxy. Required for multitenant installations. |
| 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_COMMON_CLIENT_BODY_BUFFER_SIZE | no | 8k | The size of the buffer that is used to buffer POST data. Defaults to 8k. |
| SECURITY_PROXY_NGINX_MESSAGE_EXCHANGE_CLIENT_MAX_BODY_SIZE | no | 1m | The maximum allowed size of the client request body for /secp/v1/message-exchange API, specified in the Content-Length request header. If the request body size will be larger than specified, nginx will respond with HTTP status code 413 and an error response. The default value is 16k (16 kilobytes). |
| 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. |
| SECURITY_PROXY_NGINX_ENABLE_UPSTREAM_LOG | no | false (default) | Enable the upstream log (located in the container at /var/log/nginx/upstream.log). |
Redis properties¶
Redis Cluster (AWS ElastiCache)
| Property | Required | Example | Description |
|---|---|---|---|
| SECURITY_PROXY_REDIS_HOST | yes | The Redis host to connect to. | |
| SECURITY_PROXY_REDIS_USERNAME | yes | username | The username used to authenticate with the Redis server. |
| SECURITY_PROXY_REDIS_PASSWORD | yes | password | The password used to authenticate with the Redis server. |
| SECURITY_PROXY_REDIS_PREFIX | no | tenant1_security_proxy | The Redis key prefix. |
| SECURITY_PROXY_REDIS_SSL | no | true | Determines whether SSL should be used when communicating with Redis. |
Redis Sentinel
| 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. |
| SECURITY_PROXY_FORWARDED_SCHEME | The protocol that is actually forwarded to the Token Server, the value defaults to https |
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 |