Configuring the Proxy

This page describes how to configure the proxy of your Bridge. Configuring a proxy in front of a Bridge installation is described on Configuring a Proxy in Front of the Bridge.

With the Bridge, it is possible to edit the proxy configuration file (Apache httpd 2 configuration).
Refer to http://httpd.apache.org/docs/2.4/configuring.html for the Apache HTTP Server Version 2.4 documentation on configuration files.

For more information about authentication, authorization, and access control, see the Apache documentation at http://httpd.apache.org/docs/2.4/howto/auth.html.
If you want to authenticate users who requests a proxy service, you have to edit the proxy configuration files.

Apache Modules

There are two places to add your configuration:

• A local Apache configuration file to load additional Apache modules: httpd.conf.local.
• A proxy service configuration file to add authentication rules for each proxy entry: auth.conf

The picture below shows how these configuration files are organized.

All Apache modules required for authentication have to be loaded in the local Apache configuration file (httpd.conf.local). This file can be edited with the Bridge (see Changing the Local Apache Configuration). This file is included in the main Apache configuration file httpd.conf in context server config (main section of the configuration file).

Never directly edit the configuration file httpd.conf. It is generated every time a service using this proxy is deployed and your changes will be overwritten.

• The Apache configuration files are provided with your Bridge installation in folder <your Bridge data directory>/proxies/system_templates. Do not change these files - they will get overwritten on every update. Copy files you want to modify to folder <your Bridge data directory>/proxies/templates and modify the copy.
  The actually used configuration files are generated from these template files on Bridge shut-down. The Bridge will generate the configuration from the files in folder templates if available. If not, the Bridge will use the system templates.
• After a Bridge Update, you need to merge your changes with the new system template if necessary.

Refer to http://httpd.apache.org/docs/2.4/mod/directive-dict.html#Context to learn more about the different contexts besides server config.

User Authentication in General

Users can be authenticated with the Bridge or the Apache proxy.

• For more information about authentication, authorization, and access control with Apache, see the Apache documentation at http://httpd.apache.org/ docs/2.4/howto/auth.html or further reading at Apache HTTP Bridge Version 2.2: Authentication, Authorization and Access Control, http://httpd.apache.org/docs/.2.4/howto/auth.html.
• For more information about authenticating users with the Bridge, authorization, and role-based access control refer to Security Model.

The following section contains an example of how to authenticate users using basic authentication with the Apache proxy.

The configuration of the proxy is very open. That is, customer can provide their own Apache modules that, for example, meet special security requirements.

Adding Authentication Rules to a Proxy

For each deployed proxy service (in the Bridge this maps to a proxy service entry), you can define the same or different authentication rules in a proxy service configuration file (auth.conf). First, edit a configuration template, which is used for all new deployed proxy services (for more details see Changing the Configuration Template for Proxy Service Entries). Basic authentication has been already predefined in this configuration template.

After you deployed a proxy service you can modify the authentication rule of this proxy entry (for more details see Changing the Configuration of a Proxy Service Entry further below).

If you delete a proxy entry by removing its corresponding xUML service, the proxy service entry configuration file will not be deleted.

The configuration file is included inside a location directive, which is inside a virtual host directive. This restricts the usage of other configuration directives in this file if they do not belong to the related Apache contexts.

Example

Suppose, on a Windows system, the proxy should authenticate all user requests using basic authentication. User credentials are stored and retrieved from a simple file.

Create the user/password file

Users are managed with the command line tool provided by Apache.

c:\BRIDGE_PROG\apache-2.2.22\win32-64\bin\htpasswd.exe 
-c c:\BRIDGE_DATA\proxies\conf\auth.users firstuser

Automatically using MD5 format.
New password: *******
Re-type new password: *******
Adding password for user firstuser

Use the -c flag only when you are creating a new file. After the first time, omit the -c flag, when you are adding new users to an already existing password file. Otherwise, all your previous definitions will get overwritten.

Deploy an xUML Service using a proxy

Deploy a proxy example. You can find one at the following default location:

Example File (Builder project Advanced Modeling/Proxy):

<your example path>\Advanced Modeling\Proxy\uml\proxyHttpsDedicated.xml

Test the deployed xUML service without providing user and password

In the Analyzer, test the deployed xUML service without providing any user credentials. The Bridge will return an error message saying that authorization is required.

Test the deployed xUML service with valid user and password

The Model Debugger provides the E2E HTTP Header Editor , which enables you to add any HTTP headers and assists with basic authentication.

	On the test case properties dialog, select tab HTTP Header to open the HTTP Header Editor. Click Edit Basic Authentication and enter the user credentials.
	If user and password are correct, the test case will turn green.

Changing the Local Apache Configuration

Edit the local Apache configuration file to load additional Apache modules (see also the previous section Apache Modules that provides an overview about the organization of all Apache proxy configuration files).
In the Node Instances section of the navigation, click the name of the node instance that runs the deployed proxy service. Then, click the sub-navigation item Proxy Services and switch to the tab Configuration.

Only users with administration rights are allowed to edit the configuration file.

You need to stop the proxy service first, before you can edit the configuration file.

	The editable configuration file is displayed. After editing the configuration file, click Save and Check Syntax. The changed configuration file will be saved, and a syntax check will be performed afterwards.
	The result of the syntax check is displayed in a message box.
	If an error occurred during the syntax check, an error message is displayed. You need to rectify your changes as your proxy will not start with an erroneous configuration.

Changing the Configuration of a Proxy Service Entry

Edit the proxy service configuration file for each deployed proxy service (in the Bridge this maps to a proxy service entry) to add authentication rules (see also the previous section Apache Modules that provides an overview about the organization of all Apache proxy configuration files).
In the Node Instances section of the navigation on the left, click the name of the node instance, where the deployed proxy service runs. Then, click the sub-navigation item with the proxy node name below the navigation item Proxy Services. In order to edit the proxy service entry configuration file, switch to the Configurations tab.

Only users with administration rights are allowed to edit the configuration file.

The first time a proxy service is deployed, the proxy service entry configuration template will be copied and used as initial configuration file. This template can be edited as described in the following chapter. However, the template is copied only once. Even if you delete the xUML service including the proxy service, and re-deploy it, the template will not be copied again.

	The editable configuration file of the first proxy entry is displayed.
	In order to edit other proxy service entry configuration files, select the corresponding URI from the dropdown list.
	After editing the configuration file, click Save and Check Syntax. The changed configuration file will be saved, and a syntax check will be performed afterwards. The result of the syntax check is displayed in a message box.
	If an error occurred during the syntax check, an error message is displayed. You need to rectify your changes as your proxy will not start with an erroneous configuration.

On enabling authorization in the proxy configuration, the following error may occur:

AH00526: Syntax error on line 15 of <a service path>/auth.conf: Invalid command 'AuthType', perhaps misspelled or defined by a module not included in the server configuration


This happens because HTTPD 2.4 requires the additional module authn_core_module modules/mod_authn_core.so when using authorization. You have to load the modules in your local Apache configuration (httpd.local.conf, see also Changing the Local Apache Configuration for more information on how to do this):

LoadModule authn_core_module modules/mod_authn_core.so

Changing the Configuration Template for Proxy Service Entries

Edit the proxy service configuration template to be used for each deployed proxy service (in the Bridge this maps to a proxy service entry). See also the previous section Apache Modules that provides an overview about the organization of all Apache proxy configuration files.
In the Node Instances section of the navigation on the left, click the name of the node instance, where the deployed proxy service runs. Then, click the sub-navigation item with the proxy node name below the navigation item Proxy Services. In order to edit the template file, switch to the Configuration Template tab.

Only users with administration rights are allowed to edit the configuration file.

The first time a proxy service is deployed, the proxy service entry configuration template will be copied and used as initial configuration file for this proxy entry. However, the template is copied only once. Even if you delete the xUML service including the proxy service, and re-deploy it, the template will not be copied again.

The editable configuration file of the first proxy entry is displayed. Edit the template and click Save to store your changes.