Securing the Web Services (REST SOAP WEBHANDLER)¶

Securing the Web Services (REST SOAP WEBHANDLER)

Introduction¶

All web services supported by FWD (REST, SOAP, WEBHANDLER) can be secured, to authenticate and execute the request using a certain FWD user account. This allows authenticating the API request to a certain FWD user, and after that authorizing the API request, so:

it will be allowed if the specified FWD user is permitted to access this API, and denied otherwise.
it will execute the target API implementation using that FWD user's context. Any other security plugins checking for access to a resource (like the FWD directory) will be done using that FWD user's ACLs. The limitation at this time is that the target API must not use any client-side features like memptr, file access, or any other I/O.

This authentication and authorization is not mandatory; to enable it, the following configuration changes must be done to the FWD directory:

1. Add the resource plugin¶

In the FWD directory, find the /security/config/resource-plugins node and check that it contains this plugin:

        <node class="strings" name="resource-plugins">
          <node-attribute name="values" value="com.goldencode.p2j.security.WebServiceResource"/>
        </node>

2. Enable authentication at each web service.¶

The authentication and authorization must be enabled for each web service (REST, SOAP, WEBHANDLER), individually. Find the web service node in the directory, add this section:

          <node class="container" name="authentication">
            <node class="boolean" name="enabled">
              <node-attribute name="value" value="TRUE"/>
            </node>
            <node class="string" name="login_path">
              <node-attribute name="value" value="/fwdlogin"/>
            </node>
            <node class="string" name="logout_path">
              <node-attribute name="value" value="/fwdlogout"/>
            </node>
            <node class="string" name="type">
              <node-attribute name="value" value="basic"/>
            </node>
            <node class="integer" name="timeout">
              <node-attribute name="value" value="0"/>
            </node>
          </node>

and configure the following:

enabled, to enable or disable the authentication for this web service. If the authentication node is not present at the web service node, then the authentication is disabled for that web service.
login_path and logout_path. The authentication can happen:
- for each request. In this case, login_path and logout_path must not be specified, and it means each HTTP request will contain the authentication details (these depend on the authentication type being used). In this case, the timeout must be set to zero, as the FWD user's context will be destroyed after each call.
- if the login_path is specified, then authentication will be done once, as the login response will return a token, in the FwdSessionId response header. This token (returned by login) will need to be specified to all further requests, using the FwdSessionId header (case sensitive) at the request. The logout_path (if not set) defaults to /fwdlogout, and requires the FwdSessionId header with the token, at the HTTP request, to perform the logout.
type, the authentication type. Currently, FWD supports only basic authentication mode.
timeout (in seconds), which represents the maximum lifetime of the token created by a login API call. After this timeout expires, the FWD context is destroyed automatically and the token can no longer be used for performing requests. If set to 0, the FWD context will live indefinitely, or until the explicit logout is performed.

If authentication fails, then the web service will return a 401/UNAUTHORIZED status code; if the authentication is OK but authorization fails, then FWD will return a 403/FORBIDDEN status code.

Both the login_path and logout_path are relative, to a basepath computed depending on the web service type:

for REST, this is the basepath and any address configured at the rest service annotation. So, if you have a /rest basepath and a /foo address for a REST service, and the login_path configured as /login, then the API request will need to use the /rest/foo/login to perform the login, and /rest/foo/logout for the logout call.
for WEBHANDLER, this is just the basepath, like /web - so you will have /web/login and /web/logout paths.

for SOAP, this is the basepath (like /ws) and the address for each port, configured in the wsdl:

  <wsdl:service name="fwdService">
    <wsdl:port binding="tns:fwdObj" name="fwdObj">
      <wsdl:documentation/>
      <soap:address location="/fwd"/>
    </wsdl:port>
  </wsdl>

This results in /ws/fwd/login and /ws/fwd/logout paths.

3. Authentication types¶

FWD currently only supports the Basic Authentication mode. In this mode, the request will need to have a HTTP header named Authorization, and with its value following the Basic HHH format, where HHH is the base64-encoded version of the user:token string.

In basic mode, for authentication, you will need to provide the username of a FWD user account, and a password (token), which will be checked against the webServiceToken configured at that FWD user account. If this matches, then the user will be authenticated.

Each FWD user which can be authenticated via a web service request must have webServiceToken specified at its FWD user definition in the directory, like this:

            <node-attribute name="webServiceToken" value="some-random-string"/>

This will be compared exactly with the token set at Authorization header.

WARNING: any user account with webServiceToken configured is dedicated for web service requests - it will be prohibited to login into the application, even if a password is set for it.

4. Configuring permissions¶

When authentication is enabled, permissions must be added for that web service type. This is done using ACLs, in a similar way as for other FWD resources which require security configuration.

In the directory, there will be a acl/webservice node, where ACL instances can be defined, in this format:

resource-instance - the name of the resource.
rights - true to enable access, false to deny access.
subjects - the list of subjects (groups, accounts, etc) to which this ACL instance applies

The resource-instance is the most important. This can be either a regular expression (when reftype is false) or an exact match, and is case-sensitive. The structure for this instance name must follow this format:

for REST, the REST:HTTP-METHOD:/path/to/api format
for WEBHANDLER, the WEBHANDLER:HTTP-METHOD:/path/to/api format
for SOAP, the SOAP:HTTP-METHOD:/path/to/endpoint:namespace/binding/operation format

and:

REST, WEBHANDLER, SOAP represent the web service type, in uppercase
HTTP-METHOD represents the HTTP method (POST, GET, DELETE, PUT, etc), in uppercase
path/to/api is the API target, relative to the web service basepath and any other custom address (for REST), as described at the login_path and logout_path above.
path/to/endpoint for SOAP follows the same rules as above.
namespace/binding/operation represents the SOAP operation details.

An example of ACLs which deny access to any /simple/test POST target but allow to /simple/test2 and /simple/test3 is this:

        <node class="container" name="webservice">
          <node class="container" name="000100">
            <node class="resource" name="resource-instance">
              <node-attribute name="reference" value="REST:POST:/simple/test.*"/>
              <node-attribute name="reftype" value="FALSE"/>
            </node>
            <node class="webServiceRights" name="rights">
              <node-attribute name="allow" value="false"/>
            </node>
            <node class="strings" name="subjects">
              <node-attribute name="values" value="all_others"/>
            </node>
          </node>
          <node class="container" name="000200">
            <node class="resource" name="resource-instance">
              <node-attribute name="reference" value="REST:POST:/simple/test2"/>
              <node-attribute name="reftype" value="TRUE"/>
            </node>
            <node class="webServiceRights" name="rights">
              <node-attribute name="allow" value="true"/>
            </node>
            <node class="strings" name="subjects">
              <node-attribute name="values" value="test1"/>
            </node>
          </node>
          <node class="container" name="000300">
            <node class="resource" name="resource-instance">
              <node-attribute name="reference" value="REST:POST:/simple/test3"/>
              <node-attribute name="reftype" value="TRUE"/>
            </node>
            <node class="webServiceRights" name="rights">
              <node-attribute name="allow" value="true"/>
            </node>
            <node class="strings" name="subjects">
              <node-attribute name="values" value="test1"/>
            </node>
          </node>
        </node>

Project

General

Profile

FWD

Wiki