Using URL Rewrite for API connections

Warning

This method is no longer recommended for use, as (A) it prevents the use of certain MyClient features and (B) the security benefits are negligible compared to password rotation.

The information is preserved below for reference.

Overview

We understand that in the interest of security, you may not wish to reveal your OBS passwords to the MyClient system. With this in mind, we have devised a system that lets you allow API access to your server without the need to reveal your passwords.

A normal API request looks something like:

https://..../api/getUser.do?sysUser=YOUR_AHSAY_USERNAME&sysPwd=YOUR_AHSAY_PASSWORD&LoginName=example...

Using the URL Rewrite system, the same request would be submitted like this:

https://..../api/getUser.do?LoginName=example

When an API request is submitted from MyClient to your OBS server, it includes a unique API key (in the form of a user-agent). The URL Rewriter intercepts all requests to your server before they get to OBS. If an API request is made, it will check for two components. Firstly, it checks if the request came from the IP address of MyClient. It also checks if the MyClient API key (user-agent) is correct. If both criteria match, it will add your Username and Password to the request, and then allow it through to your OBS server.

This has the following benefits:

• You never need to reveal your AhsayOBS Login Name and Password to MyClient - you keep this secret
• Your API requests are more secure because they do not contain your OBS login details

In order to use this system, you must have root access to your OBS server and the ability to add and edit the file-system. Changes recommended in this document are not for the faint-hearted and it is expected that you have a good working knowledge of your server and the OBS system. Do not attempt to make changes unless you are confident of what you are doing. Once changes are made, you will need to restart OBS. We cannot take responsibility for any problems that these changes may cause you.

Configuring URL Rewriting in MyClient

Step 1. Download URL Rewriter

Visit urlrewritefilter.googlecode.com and download the latest version of UrlRewriter. This is an open source application and is free to use, but you should read and abide by their license terms. As a side-note, there are several other uses for urlrewriter that you can configure to improve the security and features of your OBS system. Please consult their documentation and think outside the square. We may publish an article on this at a later date.

Step 2. Install URL Rewriter

Installation is fairly simple and steps are provided below. However, you should also consult the documentation provided with URL Rewriter.

1. Copy the file urlrewrite.jar into the AhsayOBS/webapps/obs/WEB-INF/lib/ folder.

2. Create a text file called urlrewrite.xml and copy the following code into it. Ensure that you replace the highlighted sections with your OBS username, OBS password and MyClient API Key. Note, the code below relates to version 2.6. If you use a different version, please adjust the code accordingly.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 2.6//EN"
    "http://tuckey.org/res/dtds/urlrewrite2.6.dtd">

<urlrewrite>

<!--
EXPLANATION OF FOLLOWING RULE:
This rule allows the API to connect to a server without knowing the server's 
System login details. Better security, but must be protected by a hash - sent 
through as user-agent and also restrict the IP address to the IP of the connecting 
server. Otherwise, it is possible to open the API to the whole world. Use with caution.
-->

<rule>
  <from>/api/([^\?]*)\??(.*)</from>

  <condition type="remote-addr" operator="equal" next="and">^MYCLIENT_IP_ADDRESS$</condition>
  <condition name="user-agent"  operator="equal" next="and">^MYCLIENT_USER_AGENT$</condition>

  <to last="true">/api/$1?$2&amp;SysUser=YOUR_OBS_USERNAME&amp;SysPwd=YOUR_OBS_PASSWORD</to>
</rule>

</urlrewrite>

The MYCLIENT_USER_AGENT field is sent by MyClient with all API requests. This prevents any other services or MyClient installations on the same server from accessing your AhsayOBS servers. You may view and edit the User-Agent from within MyClient from the System Settings page > System Behaviour > Data Binding tab > "User-Agent for API requests" option.

The MYCLIENT_IP_ADDRESS field is the IP address of your MyClient installation. You may determine this by viewing the Manage Servers page from within your MyClient installation.

Note that for URLRewrite, the <condition> tag is matched as a regular expression, so please escape all period characters as \. - and if any of your AhsayOBS customers use special characters in their usernames, we recommend using URLRewrite 3.2 or newer with the <urlrewrite decode-using="utf8"> opening tag.

Step 3. Edit your web.xml file for urlrewrite:

Your web.xml file is the main configuration file for Tomcat, so again, you must be very careful with this.

1. Create a backup of your web.xml file (located in AhsayOBS/webapps/obs/WEB-INF/web.xml)

2. Open your web.xml file for editing (requires su on Linux / Administrator on Windows)

3. The following code should be pasted into the file directly below the OBS customizations. The exact location does not matter, as long as you don't enclose it within any other tags. Keep the file open, as you may need to make additional changes in the next section.

<!-- MyClient URLRewrite Section Begins -->

<filter>
  <filter-name>UrlRewriteFilter</filter-name>
  <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>

  <init-param>
    <param-name>confReloadCheckInterval</param-name>
    <param-value>0</param-value>
  </init-param>
</filter>

<filter-mapping>
  <filter-name>UrlRewriteFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<!-- MyClient URLRewrite Section Ends -->

Step 4. Edit your web.xml for MyClient API Access:

The following is also contained within the Ahsay documentation and is standard configuration. You may have already completed this step by following the Getting Started guide. It allows you to restrict access to your OBS Server's API to certain IP addresses.

1. Create a backup of your web.xml file (located in AhsayOBS/webapps/obs/WEB-INF/web.xml)

2. Open your web.xml file for editing (requires su on Linux / Administrator on Windows)

3. Add an entry to the ApiAccess section of the file. Look for <filter-name>ApiAccess</filter-name>.

<filter>
    <filter-name>ApiAccess</filter-name>

    <filter-class>com.ahsay.obs.www.IPFilter</filter-class>
    <init-param>
      <param-name>Range1</param-name>
      <param-value>localhost</param-value>

    </init-param>
    <init-param>
      <param-name>Range2</param-name>
      <param-value>127.0.0.1-127.0.0.1</param-value>
    </init-param>

    <init-param>
      <param-name>Range3</param-name>
      <param-value>MYCLIENT_IP_ADDRESS-MYCLIENT_IP_ADDRESS</param-value>
    </init-param>

</filter>

Recent versions of AhsayOBS are preconfigured with a Range parameter of 0.0.0.0-255.255.255.255, allowing API access from anywhere and making this step obsolete. However, we recommend restricting API access to only known services with the above steps.

Step 5. Restart OBS

Stop and restart your OBS service. You should already know how to do this, please consult your Ahsay manual if necessary.