Properties/Configuration
This section describes how to configure the Security Proxy properties. It's divided into the following subsections:
- Application property setup
- Reverse proxy configuration
- TLS/SSL
- Security proxy trusted certificates
- Property Encryption
- Generic properties
- Token Validation Result Caching
- Tuning JVM
- Proxy properties
- CIM / UMA Proxy
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 | 127.0.0.1 | 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 | 192.168.118.150:8080 | 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. https://security-proxy.example.com/product/123 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.
- /customer - maps to the customer API served by http://server-a.internal:8080
- /product - maps to the product API served by https://server-b.internal:9443
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 | api.example.com | Server name to listen on. |
SECURITY_PROXY_BACK_END_<RGID> _ALLOW |
yes | 127.0.0.1 | The allowed client ip address or address range. |
SECURITY_PROXY_BACK_END_<RGID> _HOSTS |
yes | 192.168.118.151:8080 | 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 | external.api.example.dev | 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. |
TLS/SSL
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 | 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 | 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 | 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 | cim.onegini.com | This is the URL where the proxy is listening on for CIM requests. |
SECURITY_PROXY_PROXY_CIM_ALLOW | no | 0.0.0.0/0 | 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 | 192.168.2.2:8080,192.168.2.3:8080 | 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.