OAuth2 Introspection with WSO2 ESB and WSO2 Identity Server

The OAuth2 specification defines several parties: the Client, the Resource Owner, the Authorization Server and the Resource Server. Here is the (textual) diagram from the spec:

     +--------+                               +---------------+
     |        |--(A)- Authorization Request ->|   Resource    |
     |        |                               |     Owner     |
     |        |<-(B)-- Authorization Grant ---|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(C)-- Authorization Grant -->| Authorization |
     | Client |                               |     Server    |
     |        |<-(D)----- Access Token -------|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(E)----- Access Token ------>|    Resource   |
     |        |                               |     Server    |
     |        |<-(F)--- Protected Resource ---|               |
     +--------+                               +---------------+

                     Figure 1: Abstract Protocol Flow

One flow that is not defined by the OAuth specification is any flow from the Resource Server to the Authorization server to validate an existing Bearer Token (or other token). 

The spec says:

The interaction between the authorization server and resource server is beyond the scope of this specification.  The authorization server may be the same server as the resource server or a separate entity. A single authorization server may issue access tokens accepted by multiple resource servers.

In many cases the Authorization server offers an API to access this. For example, Google allows you to call a TokenInfo APIto validate tokens. Similarly Facebook offers an API to "debug" a token. The WSO2 Identity Server also offers an API, but (shock and horror) we don't document it yet. The ESB and API manager both utilize this API to validate OAuth2 bearer tokens. The ESB code is of course available, and with a quick look at the code and also the use of TCPMON it didn't take me long to reverse engineer the API. This Gist has a sample HTTP SOAP request against the WSO2 IS to validate a token:

It turns out that the OAuth Working Group at the IETF is working on this and has a draft specification available, using a RESTful service. They call this OAuth Token Introspection. I figured this would be easier (and more pleasant) to call from my Python code, so I knocked up a quick WSO2 ESB API mediation flow to convert from the RESTful API to the existing WSO2 SOAP-based API.

I know that Prabath and the security and identity team at WSO2 will soon add this useful REST API, but in the meantime, here is a quick hack to help you out. Please note you need to hardcode the URL of the IS and the userid/password into the ESB flow. Also I assume if you don't provide a token_type_hint then this is a bearer token. And here is the Gist showing a sample interaction: