How to introspect an OAuth token on Apigee X?

[asaischintala]

I have an OAuth Provider API which generates token for client_credentials grant type.

I want to expose an "Intropsect" function, where the token is passed to the API and it returns whether the token is valid or not.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 continueOnError="false" enabled="true" name="IntrospectOAuth2Token">
    <DisplayName>IntrospectOAuth2Token</DisplayName>
    <Properties/>
    <Attributes/>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.formparam.token</AccessToken>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
    <RFCCompliantRequestResponse>true</RFCCompliantRequestResponse>
</OAuthV2>

I have used the above policy to verify the token and it's good.

But how can I generate a response body for valid and invalid tokens?

@dchiesa1  Please help.

[dchiesa1]

In the common case, people use Apigee to verify an access token and they want Apigee to throw a fault (return an error to the caller) if the token is expired or invalid. To do that, you can use a simple OAuthV2 policy configured like this:

<OAuthV2 name='OAuthV2-VerifyToken'>
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

If the token is good, then this policy sets a bunch of context variables containing information about the token, like the expiry, the API Product name, and maybe any custom attributes. If the token is "not good", then this policy will raise a fault. In that case, Apigee goes through the normal Fault Handling process - invoking the FaultRules in your proxy endpoint, etc. This policy will also set the fault.name context variable to contain an identifier for the fault that expired. Something like "invalid_access_token" or "expired_access_token", etc. So you can examine that variable in the Conditions within your FaultRules, if you want to customize the error messages that get sent back to callers.

That's the normal case. What you want to do is different. You want to just inquire as to the status of an Access Token. And not throw a fault if the token is expired, etc., but rather, just return some information. You can do that by adding an attribute to the OAuthV2 policy, continueOnError. Like this:

<OAuthV2 continueOnError="true" name='OAuthV2-VerifyToken-Continue'>
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

If the token is good, then .... this policy configuration behaves exactly the same as the above policy configuration. If the token is invalid or expired (etc), then this policy behaves differently. It will simply set a "failed" variable to true, and a "fault.name" variable containing the reason for the fault (invalid or expired etc). The actual variable names vary, depending on the name of the policy. In this case they will be oauthV2.OAuthV2-VerifyToken-Continue.failed and oauthV2.OAuthV2-VerifyToken-Continue.fault.name respectively.

So you could do something like this in your flow:

      <Request>
        <!--
             this will try to verify the token, but will not throw a fault
             if the token is invalid or expired.
        -->
        <Step>
          <Name>OAuthV2-VerifyToken-Continue</Name>
        </Step>
      </Request>
      <Response>
        <Step>
          <Name>AM-Response-AfterContinue-Failed</Name>
          <Condition>oauthV2.OAuthV2-VerifyToken-Continue.failed = true</Condition>
        </Step>
        <Step>
          <Name>AM-Response-AfterContinue-Success</Name>
          <Condition>oauthV2.OAuthV2-VerifyToken-Continue.failed != true</Condition>
        </Step>
      </Response>

A couple notes

• Unfortunately you cannot get all the information related to an expired token, that you can get for a non-expired token. You can't get the API product name, the developer, and all the other metadata. Mostly the information you get back this way, is limited to the token status: expired or invalid. So I don't know if that will be helpful for an introspection endpoint. I guess it depends on your requirements. Do you want the introspection endpoint to be able to tell the caller a bunch of information after the token has already expired. In that case, the continueOnError technique won't help you much.
• Also keep in mind that the proxy that exposes the "introspection" endpoint must itself be authorized on an API product for which the token is good.

Attached please find a working API proxy that you can use to demonstrate this for yourself.

Also, here's a screencast where I walk through this stuff interactively.