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
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. |
Resource gateway instances
Property | Required | Example | Description |
---|---|---|---|
SECURITYPROXY_BACK_END<RGID> _HOSTS_HOSTID |
yes | 192.168.118.151:8080 | The host record for a resource gateway instance for this type of resources |
Resource gateway based on server name
It is also posible 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_ENGINE_ENCRYPTION_POLICY_USERNAME | yes | username | The username used for the authorization |
SECURITY_PROXY_ENGINE_ENCRYPTION_POLICY_PASSWORD | yes | password | The password used for the authorization, should be encrypted |
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_ENCRYPTION_POLICY_HOST | no | 127.0.0.1 | The host used to retrieve the encryption policy. |
SECURITY_PROXY_ENGINE_ENCRYPTION_POLICY_PORT | no | 8080 | Sets the port used to retrieve the encryption policy |
SECURITY_PROXY_ENGINE_ENCRYPTION_POLICY_URI | no | /api/v1/payload-encryption-policy | Set the URI used to retrieve the encryption policy |
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. |
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. |