Managing HTTP Headers with Oracle API Platform

Imagine you have a service that is secured with Basic Auth or better yet OAuth2 and you would like to leverage the complete capabilities of an API Platform so you choose to create an API and deploy it to a gateway running in front of your service.

When you call your service directly from within your internal network, everything works, providing you include the appropriate Authorization header that your service expects. However, when you call the API endpoint on your gateway, the endpoint you will make available to your consumers, it does not work. You are passing everything as your original call, you've just modified the end-point to point to your gateway load balancer address and API end-point. What happened?

Well, most of the headers you pass to the gateway will simply pass through by default, with the exception of Authorization. Here is an example of a real simple API I created.

This API receives a request to the "echo" end-point and simply passes it to httpbin.org so we can see the result. So, as we can see, I am not really including any security policies in my API. I am choosing to leave that to the back-end service in this case. What happens if I call this API passing with an Authorization header. As you can see below, it is not included in the headers.

This is because the gateway is an authorization and policy enforcement engine and in most cases, when we validate the user at the gateway, we do not want to pass that header to the back-end systems. But what if we do want to pass that header? It turns out this is quite simple. We add the header to our Service Request policy

As you can see in the Service request, we can add, drop and even update headers. In this case, I am explicitly saying "It's ok, share the Authorization header downstream". Now let's call our API again

This is of course not limited to existing headers. I can add new headers. For example, let's say I need to take a header received, and pass it along as a different header. Here is an example

Now, calling the API, I can see the additional header is passed with the value of the passed in header.

This is not limited to headers. I could map from a payload or even a query. For example, if my API receives a query of "my-special-key=123", I can map a header, say my-special-key to ${queries.my-special-key}.

This is also a very simple example of manipulating headers from the Service Request Policy. For much more functionality on headers, I can choose from other policies dedicated to managing headers.

I hope you found this short introduction to managing headers useful and if you are wondering where your Authorization header went and you do want to propagate it downstream, then remember to configure it in the Service Request Policy.