Delegation Response Processor (DeRP) Filter

Purpose

The Delegation Response Processor (DeRP) filter will reject any request containing the X-Delegated header. The content of the response will match the content of the X-Delegated header.

General filter information

Filter name: DeRP

Filter configuration: not configurable 

Released: version 7.0.0.1

Prerequisites

Required headers: The DeRP filter has no required headers. However, the X-Delegated header must be present for the filter to do any processing.

Required preceding filters: The DeRP filter processes the X-Delegated header which comes from one of the following filters: Client AuthN, Client AuthZ, Rackspace Identity Basic Auth, OpenStack Identity v3, and API Validator. If one of these filters does not proceed the DeRP filter, the DeRP filter will pass all requests to the next filter in the sequence or to the origin service. 

Recommended follow-on (succeeding) filters: In a few cases, it might make sense to place certain filters after the DeRP filter to save on processing time or prevent the succeeding filter from returning a failing response when the the failure is actually due to a failure in a previous filter. 

Delegation

See: Delegation in Repose

As a brief example, assume I have the following system model:

Now say that I'm trying to utilize delegation and the DeRP filter. First, I'll have to add the DeRP filter to my filter chain, as shown below:

 

Notice that I put derp after client-auth and api-validator, but before rate-limiting. The reason is that both client-auth and api-validator support delegation while rate-limiting does not. Therefore, if rate-limiting came before derp, it would reject the request before derp could process it.

Next I'll have to add the <delegating> element to both the client-auth and the api-validator filters. Doing so will enable delegation so that when a failure would occur, the request is forwarded instead of rejected.

Once that's done, I have delegation working in Repose!

To get a little more advanced, let's say I change my filter chain to the following:

 

Now say I want the failure from api-validator to be returned to the user rather than the failure from client-authorization. To achieve that, I'll change the quality of delegation in the api-validator filter to be greater than the quality of delegation of the client-authorization filter. I can do that by simply modifying the <delegating> element in the client-authorization configuration to <delegating q="0.6"/>. Since 0.6 is greater than 0.5, the default delegating quality of the client-authorization filter, I'll get the behavior that I want.

Generally speaking, you will want the first filter in your filter chain to have the highest delegating quality, and each subsequent filter to have a lower delegating quality so that the last filter to has the lowest delegating quality.

Quality

The DeRP filter sends the failure data that corresponds to the value of the X-Delegated header with the highest quality. If multiple X-Delegated header values exist in a request, the DeRP filter will reject the request using the failure data from one of those values. The failure data to be used is indeterminate prior to processing the request - meaning any of the values with the highest quality could be used. If quality is not specified, the quality will default to 1.0.

Quality defaults

Rackspace Identity Basic Auth filter: 0.9

AuthN filter: 0.7

OpenStack Identity v3 filter: 0.7 

AuthZ filter: 0.5

API Validator filter: 0.3 

Response Messaging Service Interaction

Note that the DeRP filter will always populate a response body when it rejects a request. As such, if you are using the response messaging service, and desire the responses from the DeRP filter to be overridden, each <status-code> element will require that the overwrite attribute to be set to ALWAYS.

Return codes and conditions

The DeRP filter rejects any request containing the X-Delegated header. The content of the response will contain failure data corresponding to the value of the X-Delegated header with the highest quality.

Request headers created

The DeRP filter does not create any request headers.