Implement Request Mapper

A Request Mapper is an extension to the Onegini Security Proxy. The Request Mapper is responsible to give instructions on how to modify request before it gets to a Resource Server when the embedded resource gateway functionality is used. The way how a request to a resource server should look like is very resource server implementation specific. For that reason the Onegini Security Proxy does not contain a default Request Mapper implementation. This topic guide will provide the api and instructions on how to implement a request mapper via an example implementation.

The request mapper API

The Onegini Security Proxy will call the Request Mapper via a predefined REST/JSON api. Request Mapper should expose a single endpoint:

• method: post
• accept: application/json
• content-type: application/json
• body: see below

Note: The endpoint can optionally be protected with basic authentication. The request that is send from Security Proxy to Request Mapper always contains basic authentication header, so it can be either validated or ignored in Request Mapper implementation.

The endpoint takes the following json object as a request body:

Attribute	Description
request_uri	Request uri of the configured Resource Server endpoint
token_validation_result	The Token introspection result returned by Token Server (see the Token Server introspection api description).
headers	Request headers of the Resource call. (**All header names in the request body are sent lower
case**).

{
  "request_uri": "/some-resource-gateway-request-uri",
  "token_validation_result": {
    "scope": "exampleScope",
    "sub": "exampleUserId",
    "amr": [
      "DEFAULT"
    ]
    ...
  },
  "headers": {
    "header_1": "value_1",
    "header_2": "value_2",
    "authorization": "Bearer 060E7B02C875D5D74318FE0BBDA22BEFBA882B9B90F918BE77F9FCFF1A0E24B0"
  }
}

A 200 OK JSON response is expected as response after the Request Mapper is completed. This response should contain the following json object:

Attribute	Description
request_uri	(Modified) request uri
headers	(Modified) request headers

The request mapper only should give instructions on how to modify the actual request to the Resource Server. The Request Mapper API is not designed to handle any decisions taken in the Request Mapper.

Example request mapper

This example code shows how to implement Request Mapper Component in a simple Spring Boot application. The example uses undertow as embedded application server. Undertow is chosen because it is a lightweight solution with little overhead.

The example request mapper at first validates the basic authentication header. Then the component continues with modifying the request as follows:

• removes blacklisted headers: authorization & authorized_scopes, this is done to prevent a trusted header can be set externally
• adds a new authorized_scopes header based on the scope property of token_validation_result
• appends user id to the request_uri based on the sub property of token_validation_result

Accordingly the /map-request endpoint returns a json object with the same structure (without token_validation_result):

{
  "request_uri": "/some-resource-gateway-request-uri/exampleUserId",
  "headers": {
    "header_1": "value_1",
    "header_2": "value_2",
    "authorized_scopes": "exampleScope"
  }
}

Such a request is ready to use in order to call a Resource Server which implements an API that fetches scopes from authorized_scopes header and read user id form the path.

Example request mapper code

On GitHub you can find the full example Request Mapper.