Reverse proxy configuration¶

The Security Proxy is essentially a reverse proxy. It serves content that is provided by other servers. It should however know where it can find these servers.

There are three kinds of back-ends defined in the Security Proxy that can be configured:

Token Server - Back-end to the Onegini Token Server. This is for requests directed to the Onegini Token Server.
Resource gateway - Back-end for resource gateways. Data requests to transport (personalized) data to a mobile device must be handled by a resource gateway.
Transparent proxy - The transparent proxy back-end can be used for everything else, like the Onegini Token Server admin interface for example.

Configure Onegini Token Server backend¶

The Security Proxy requires a Token Server instance to be configured.

For this configuration the following properties are available:

Property	Default	Description
SECURITY_PROXY_BACK_END_TOKEN_SERVER_CONTEXT_ROOT	/oauth	The context root of the Token Server.
SECURITY_PROXY_BACK_END_TOKEN_SERVER_PROXY_SCHEME	http	The protocol scheme used to communicate to the Token Server.
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_HOSTS	127.0.0.1:8080	Host including port of the Token Server.
SECURITY_PROXY_BACK_END_TOKEN_SERVER_ALLOW	127.0.0.1	The allowed client ip address or address range in CIDR notation.

A setup with a single Token Server back-end is the most common setup. Having multiple Token Servers is explained in more detail in the configuration section.

Configure Onegini Token Server admin backend¶

The Onegini Token Server admin can be configured as a transparent proxy endpoint. Meaning all requests to the admin should be proxied transparently. The properties:

Property	Default	Description
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_ADMIN_CONTEXT_ROOT	/admin	The context root of the Token Server admin.
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_ADMIN_PROXY_SCHEME	http	The protocol scheme used to communicate to the Token Server admin.
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_ADMIN_HOSTS	127.0.0.1:8080	Host including port of the Token Server admin.
SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_ADMIN_ALLOW	127.0.0.1	The allowed client ip address or address range in CIDR notation.

Configure Resource gateway backend¶

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 with a few restrictions:

When not using a server name the context root needs to be unique.
When not using a server name the context root cannot be /oauth as this is used by the token server back-end.
When using Payload Encryption you cannot use a server name. Resource requests made with Payload Encryption enabled only work on the domain of the Security Proxy itself.

A resource gateway can be an external resource gateway or the embedded resource gateway functionality of the Onegini Security Proxy. When using the embedded resource gateway functionality the configured host should be the resource server.

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://token-server.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.

token-server.example.com/customer - maps to the customer API served by http://server-a.internal:8080
products.example.com/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
hosts: server-a.internal:8080

2: product-api

context-root: /product
proxy-scheme: https
hosts: server-b.internal:9443
server-name: products.example.com

Note that because we have not defined a server-name for the customer-api, this api will be available on the same domain as the Security Proxy itself. The product-api will be available on the domain products.example.com. In case Payload Encryption was used the server name must NOT be set because requests with Payload Encryption only use the same domain as the Security Proxy itself.

For the resource gateway backend the following properties can be applied:

Property	Required	Example	Description
SECURITY_PROXY_BACK_END_RESOURCE_GATEWAYS_`<RGID>`_CONTEXT_ROOT	yes	/resource	The context root of the resource, used for non encrypted data.
SECURITY_PROXY_BACK_END_RESOURCE_GATEWAYS_`<RGID>`_PROXY_SCHEME	yes	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	yes	127.0.0.1	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_ and SECURITY_PROXY_SSL_KEY_)

By default all reverse proxy endpoints are mapped based on the context root. For a resource gateway there is the option to map based on server name. To enable this functionality for a resource gateway endpoint you need to set SECURITY_PROXY_BACK_END_RESOURCE_GATEWAYS_<RGID>_SERVER_NAME to the hostname you wish to map it to. Please see the requirements for TLS/SSL related to this function in the configuration section.

Configure Transparent proxy backend¶

The transparent proxy backend can be used to proxy anything through the Security Proxy as though it was a regular transparent proxy. This functionality can be used for example to proxy requests to the Onegini CIM or any other server in your back-end.

For the transparent proxy backend the following properties can be applied:

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	yes	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	yes	127.0.0.1	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 SECURITY_PROXY_SSL_CERTIFICATE_ and SECURITY_PROXY_SSL_KEY_)

Below is an example of how the Security Proxy can be configured with a transparent proxy back-end for the Onegini CIM:

  - SECURITY_PROXY_BACK_END_CIM_CONTEXT_ROOT=/
  - SECURITY_PROXY_BACK_END_CIM_CONTEXT_PROXY_SCHEME=http
  - SECURITY_PROXY_BACK_END_CIM_SERVER_NAME=cim.example.com
  - SECURITY_PROXY_BACK_END_CIM_CONTEXT_ALLOW=0.0.0.0/0
  - SECURITY_PROXY_BACK_END_CIM_HOSTS=192.168.9.2:8080
  - SECURITY_PROXY_BACK_END_CIM_SSL_CERTIFICATE_NAME=CIM

In this example we have defined an additional ssl certificate with the name CIM. This additional certificate can be configured by setting the following properties:

  - SECURITY_PROXY_SSL_CERTIFICATE_CIM=
  - SECURITY_PROXY_SSL_KEY_CIM=

Configure locations for a transparent proxy backend¶

The Security Proxy supports configuring multiple locations per (named) transparent proxy backend. This will allow you to have multiple locations in your transparent proxy pointing to different upstream backends.

For instance let's assume you have the following situation:

my.proxied.server.com/ - maps to the upstream served by http://server-a.internal:8080
my.proxied.server.com/alternate - maps to the upstream served by https://server-b.internal:9443

This situation would be accomplished with the following configuration:

  - SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_MYSERVER_CONTEXT_ROOT=/
  - SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_MYSERVER_SERVER_NAME=my.proxied.server.com
  - SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_MYSERVER_HOSTS=server-a.internal:8080
  - SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_MYSERVER_LOCATIONS_ALT_HOSTS=server-b.internal:9443
  - SECURITY_PROXY_BACK_END_TRANSPARENT_PROXIES_MYSERVER_LOCATIONS_ALT_CONTEXT_ROOT=/alternate

For a full list of properties for the transparent proxy configurations see the configuration section

Note: This will only work for a transparent proxy that has a SERVER_NAME configured.