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
- Property Encryption
- Generic properties
- Generic environment variables
- Encrypting property values
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.
- /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. |
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 valuedummyValue
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>'