Properties/Configuration

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 etcd to manage it's application properties. Before the application is started for the first time, etcd needs to be populated with properties. See the required column for properties that need to be set before starting the Security Proxy.

Etcd can be populated using a http API, or by using a command line client etcdctl. Details can be found in the etcd documentation.

Reverse proxy configuration

Recall that the Security Proxy is essentially a reverse proxy so 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 Required Example Description
/security-proxy/back-end/token-server/context-root yes /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 yes http The protocol scheme used to communicate to the back end.
/security-proxy/back-end/token-server/request-type yes token-server Indicates that this is the Token Server endpoint.
/security-proxy/back-end/token-server/proxy-api/enabled yes false Indicates whether the Token Server API should be exposed through the Security Proxy.

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 API's 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 API's 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's.

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.

Resource gateway instances

Property Required Example Description
/security-proxy/back-end/RGID/hosts/HOSTID yes 192.168.118.151:8080 The host record for a resource gateway instance for this type of resources

TLS/SSL

The Security Proxy supports a secure listener. You can enable it by setting the properties specified below.

Property Required Example
/security-proxy/ssl/enabled yes true Enable/disable TLS/SSL suport
/security-proxy/ssl/protocols no TLSv1 TLSv1.1 TLSv1.2 TLS/SSL protocol versions
/security-proxy/ssl/ciphers no see below TLS/SSl cipher suites
/security-proxy/ssl/certificate no see below The ssl certificate of the server in PEM format
/security-proxy/ssl/certificate-key no see below The ssl private key of the server in PEM format

Cipher suites

The default cipher suites used by Security Proxy are: ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4

It is highly recommended to use the default cipher suites and TLS/SSL protocols.

Certificate

This property specifies the server certificate (and possibly also the chain certificate). Please see the Nginx documentation on how to prepare the certificate and optionally certificate chain.

The certificates must be put in etcd in the PEM format like the example below:

curl -L -X PUT http://127.0.0.1:2379/v2/keys/security-proxy/ssl/certificate --data-urlencode value="$(cat /location/to/certificate)"

Note: Don't forget to change the location of the pem encoded certificate in the command above.

Certificate key

This server private key must be put in etcd in the PEM format like the example below:

curl -L -X PUT http://127.0.0.1:2379/v2/keys/security-proxy/ssl/certificate-key --data-urlencode value="$(cat /location/to/private/key)"

Note: Don't forget to change the location of the pem encoded private key in the command above.

Property Encryption

All (sensitive) values stored in etcd can be encrypted. Please see the section about property encryption for details on how to encrypt property values.

Property Required Description
/security-proxy/common/property-encryption-password true The password that is used to encrypt and decrypt property values in etcd

Note: It might sound insecure to store the property encryption password in etcd. Since the password is only required during startup it only needs to exist for a few minutes. Etcd provides means to automatically remove properties after a specified amount of time has passed by setting a time-to-live (ttl) option with a number of seconds that the key must exist.

A value with ttl can be specified using the following command:

etcdctl set /foo/bar 'dummyValue' --ttl '300'

The command above specifies that the /foo/bar key with value dummyValue will exist in etcd for 300 seconds or 5 minutes.

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.

Generic environment variables

Property Description
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_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.

Encrypting property values

The Onegini Security Proxy supports encrypting property values. The open source library Jasypt is used for this. Onegini uses a strong encryption algorithm, which is not present in the standard JRE security provider implementation. For this reason we use the BouncyCastle security provider implementation.

Install the Jasypt library

You can download Jasypt from their website.

Untar the library into a directory of your choice, e.g. the /opt directory.

Install a custom Java Cryptographic Provider

BouncyCastle is necessary for encrypting properties since the algorithm that is used is not included in the standard Java cryptographic provider.

Download the bouncy castle jar.

Move it to the lib folder inside the extracted Jasypt archive.

Note: Java including the Java Cryptographic Extensions is required in order to encrypt properties. Check this blog for instructions on installing the proper JCE for your java version

Encrypt property values

It is possible to encrypt properties such as passwords. The steps below describe how to do this. All properties are encryptable. Navigate to the directory where the Jasypt library is installed.

cd <JASYPT_PATH>/jasypt-1.9.1/bin/

Generate a master password either using a password generator or the following command:

openssl rand -hex 32

Next, execute the following command:

./encrypt.sh providerClassName="org.bouncycastle.jce.provider.BouncyCastleProvider" algorithm="PBEWITHSHA256AND256BITAES-CBC-BC" verbose="false" password='<MASTER_PASSWORD>' input='<TEXT_TO_ENCRYPT>'

Note: Don't forget the master password is needed when starting / stopping the Security Proxy instance(s))!

If the password or the input contain a single quote you will need to provide each separate single quote with the following sequence: '"'"'

When the above command is executed the encrypted property value is printed to the screen. The last step is to configure the encrypted value as the actual value in the property file. The value has to be surrounded by ENC(<ENCRYPTED_VALUE>). Below is an example of an encrypted password:

etcdctl set /security-proxy/engine/encryption-policy/password  "ENC(6sCtMDYFi5MhTfRk9x6tzVuc/TouSqLnTsajxGdOq/4=)"

You can verify the encryption by running:

./decrypt.sh providerClassName="org.bouncycastle.jce.provider.BouncyCastleProvider" algorithm="PBEWITHSHA256AND256BITAES-CBC-BC" verbose="false" password='<MASTER_PASSWORD>' input='<TEXT_TO_DECRYPT>'