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.

[sixhobbits]

@mooreds - sorry, we’re still struggling with the /introspect stuff unfortunately, and I think it might be us misunderstanding something basic but fundamental. I met with Richard who worked on this draft today to help try figure it out and we’re still stuck on showing how this should be used and making sure we're recommending something that makes sense.

We can set up an example with a Customer, a ResourceServer, and an AuthServer (Fusionauth), as we've done in this guide.

Our understanding is that:

• The Customer should provide a token to the ResourceServer
• The ResourceServer should be able to use /introspect to validate that token with the AuthServer

We are able to do that if we use the Customer’s client_secret but we think it’s weird for the ResourceServer to need the Customer’s client_secret and that it should be able to call /introspect using the ResourceServer's client_secret instead. But we can't get that to work. We created an example at FusionAuth/fusionauth-issues#3010 to demonstrate what we think should work, but doesn't.

We have 3 possible workarounds, but they all seem like bad practice so we don’t want to recommend them unless we understand this better:

• Turn off the need to pass the client_secret at all
• Make the ResourceServer Admin so it can access the client_secret directly with the AuthServer
• Have the Customer pass their client_secret along with the token to the ResourceServer

So I think the confusion is more about which client_secret we should be using. In the example above

&client_secret=EmQ3FL-rDqHuESnJCmZacFK3sKQbOKX-gQYnC5pPLio`

this is the customer's client secret, and we think it should be the resource server's client secret (FDt7P53FymamBobVUxU+DwggNpwriyaujcoziX6E in the article), but that gives us a 401.

So if you have more insights on how this is meant to be used, and if we're holding it wrong, which of the three options you think we should recommend in this guide as best-practice that would be great.

[mooreds]

Hmmm. The introspect RFC is kinda vague on this point. It seems you've found a sharp edge, if not a bug.

For this particular content, any reason to just avoid using the introspect endpoint?

[mooreds]

Also, haven't looked deeply at this content, but it seems pretty FusionAuth specific. Have we considered putting it under docs instead of articles?

[sixhobbits]

@mooreds - avoiding introspect was our original workaround, so if that's all that is needed then the PR should be good to review. We just thought that introspect was the correct thing to use in this case and that we were using it wrong, but the draft as-is doesn't mention introspect (only that excerpt in the PR comment that we removed from the draft).

re location, we're never completely sure how to categorize something so if you have guidelines on that that would be helpful. Can definitely move this one over to docs.

[mark-robustelli]

@sixhobbits are we good to review this now?

[sixhobbits]

@mark-robustelli - sorry missed the above comment. Yes we're done with this now unless you want any more changes from us.