Add service to service guide

[sixhobbits]

We had some questions while doing this one, as the introspect endpoint didn't work as we expected.

We posted this forum post and received some clarification on one point from @mooreds - but are still not clear if Fusionauth is implementing the introspect endpoint in a standard way, or we don't understand how to correctly use it.

The original draft of this article had the following paragraph which explains our understanding of what introspect should do and how it doesn't work that way in Fusionauth. We removed it as it's either a bug in Fusionauth or a misunderstanding on our part.

@mooreds maybe you have a quick insight here on the following as you responded on the forum before about the second point?

---

A Better Way To Verify A Token — Introspection

Verifying a token by manually looking at JWT signatures, as the code above does, is not standard in OAuth. Instead, all OAuth servers should allow anyone to verify a token by passing the token to the standard introspect endpoint. Example code to do this is given below.

async function verifyTokenThroughIntrospectionEndpoint(token) {
  const response = await axios({
    method: "post",
    url: "http://localhost:9011/oauth2/introspect",
    headers: {"Content-Type": "application/x-www-form-urlencoded"},
    data: `token=${token}&client_id=40450891-0231-49c4-839b-b2c444f57f9c&client_secret=EmQ3FL-rDqHuESnJCmZacFK3sKQbOKX-gQYnC5pPLio`
  });
  console.log("\nToken verification result:", response.data);
  return response.data;
}

Unfortunately, FusionAuth does not implement this endpoint correctly. In the code above, you have to send the customer's secret key along with the token to be verified. But the server is the one that wants to verify the key, and the server doesn't have access to the customer's secrets. So the server can't verify any access tokens with this endpoint, as it should be able to. If you try passing the server's secret key to FusionAuth it doesn't work either.

[bradmccarty]

Sending this to @mark-robustelli for review.

[mark-robustelli]

@sixhobbits does the documentation that @mooreds point to, help clear things up? If not, what do you need from us here?

[sixhobbits]

@mark-robustelli - no, the docs did not resolve this. we need confirmation on our understanding of how to use the introspect endpoint as we could not get that working as expected.

• the current article draft uses a workaround and manually verifies the JWT token
• the snippet shown in the comment above does not work as we expect

So we need either

A) some help in using introspect correctly to verify the token without passing the client secret
B) confirmation that this is a bug in Fusionauth and that the workaround we used in the article is correct

[mooreds]

Verifying a token by manually looking at JWT signatures, as the code above does, is not standard in OAuth. Instead, all OAuth servers should allow anyone to verify a token by passing the token to the standard introspect endpoint. Example code to do this is given below.

The reason that you can't look at JWT signatures for all OAuth servers is that not all access tokens are JWTs. JWT as a standard was published in 2015 (7519), whereas OAuth 2.0 was published in 2012 (6749). Introspect was published in 2015 as well (7662). The OAuth2 standard explicitly says that

The resource server MUST validate the access token and ensure that it has not expired and that its scope covers the requested resource. The methods used by the resource server to validate the access token (as well as any error responses) are beyond the scope of this specification but generally involve an interaction or coordination between the resource server and the authorization server.

Hopefully that sets the table a bit.

Now let's talk about how FusionAuth implements introspect.

Unfortunately, FusionAuth does not implement this endpoint correctly. In the code above, you have to send the customer's secret key along with the token to be verified. But the server is the one that wants to verify the key, and the server doesn't have access to the customer's secrets. So the server can't verify any access tokens with this endpoint, as it should be able to. If you try passing the server's secret key to FusionAuth it doesn't work either.

I'm not sure I understand this paragraph. I believe that 7662 is implemented correctly, but of course would love to hear about where I am wrong.

When you are using introspect, you (some kind of resource server, typically) have received an access token. You don't know if it is valid. So you are are trying to validate it by communicating with the server that issued it. I'm not sure what you mean about the key, because there is no key in the introspect request. What am I missing?

According to the spec:

If left unprotected and un-throttled, the introspection endpoint
could present a means for an attacker to poll a series of possible
token values, fishing for a valid token. To prevent this, the
authorization server MUST require authentication of protected
resources that need to access the introspection endpoint

This is why we require the client id and the client secret by default. However, there are application level settings (the clientAuthenticationPolicy) to turn this behavior off, as documented here.

Also, I would expect that most services would be running on a server, so would have the ability to properly and securely store a client secret, so I don't see why requiring it by default would be problematic.

[mark-robustelli]

@sixhobbits , can you work of this or do you need anything else to move this forward?

[sixhobbits]

@mooreds - thanks for this and sorry for what seems to have come from a misunderstanding on our part.

@mark-robustelli - this should be all we need, just need some time to figure it all out and do hopefully a small rework on that section. we'll shout if we need more help on this one.