Properties reference
- Application property setup
- Security proxy trusted certificates
- Property Encryption
- Generic properties
- Redis properties
- Token Validation Result Caching
- Tuning JVM
- Proxy properties
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 |
TLS/SSL
TLS/SSL generic config
Property | Required | Description |
---|---|---|
SECURITY_PROXY_SSL_ENABLED | yes | Enable/disable TLS/SSL suport |
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 |
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. |