How to correctly use the introspection endpoint with identity server 4?

Question

I'm using Identity Server 4 and I'm trying to use the introspection endpoint, but just by the docs I'm not getting it.

The docs just gives this example

POST /connect/introspect
Authorization: Basic xxxyyy

token=<token>

Now, why there is this basic authentication and what should be xxxyyy? I mean, there's no basic auth set in my app. I've just setup Identity Server 4 using ASP.NET Core as follows in the ConfigureServices:

services.AddIdentityServer()
            .AddTemporarySigningCredential()
            .AddInMemoryApiResources(ApiResourceProvider.GetAllResources())
            .AddAspNetIdentity<Usuario>();

and in Configure

app.UseIdentity();
app.UseIdentityServer();

Now I've tried just a POST to /connect/introspect with the body just token=<token>, but it returned a 404.

I believe I really didn't get it.

How do we use the introspection endpoint with Identity Server 4 in ASP.NET Core?

Solution 1

The implementation of IdSvr4 is fantastic, but the docs leave a lot to be desired - I spent a good hour searching on the internet to be able to come up with a working solution. Being told to 'read the spec' just isn't always helpful if you are new to a concept - which is something that happens alot on their forums.

So - what you have to pass to the POST /connect/introspect is a scope secret.

You can configure the quickstarts by changing the config.cs class. You will need to update whatever datastore you use if you have customised it, or are not using the quickstart - but the concept should (hopefully) be clear.

public static IEnumerable<ApiResource> GetApiResources()
{
    return new List<ApiResource>
    {
        new ApiResource("MyResource", "My_Resource_DisplayName")
        {
            ApiSecrets = new List<Secret>
            {
                new Secret("hello".Sha256())
            },
            Scopes=
            {
                new Scope("MY_CUSTOM_SCOPE")
            }
        }
    };
}

Now...

1. Ensure that your client has the scope MY_CUSTOM_SCOPE
2. Ensure you have requested the scope MY_CUSTOM_SCOPE when getting a bearer token.

Now, make a Base64 encoded string of the api resource name and secret like this:

Convert.ToBase64String(Encoding.UTF8.GetBytes(string.Format("{0}:{1}", userName, password)));

Where username is MyResource and password is plaintext hello (obv. use your own values!) - should end up with a string which looks like this: TXlSZXNvdXJjZTpoZWxsbw==

Now, you can post to IDSvr4...

POST /connect/introspect
Authorization: Basic TXlSZXNvdXJjZTpoZWxsbw==
Accept: application/json
Content-Type: application/x-www-form-urlencoded

token=<YOUR_TOKEN>

So, as long as your bearer token has the scope MY_CUSTOM_SCOPE (or whatever you ended up calling it) - you should now be able to use to introspection endpoint of IdSvr to get info about it.

Solution 2

Introspection is typically used by APIs to validate an incoming token. Also the introspection endpoint requires authentication per spec.

You need to setup an API secret:

https://identityserver4.readthedocs.io/en/latest/reference/api_resource.html

And then use the api name/secret to authenticate against the introspection endpoint. Either using Basic authentication or posting the values in the form.

Solution 3

@Jay's answer above helped me a lot. In my case I had forgotten to change content type to url-encoded as per the RFC 7662 i.e.

r.Header.Add("Content-Type", "application/x-www-form-urlencoded")

Comments

[Shaun Luttin]

What are you trying to achieve with the introspection endpoint?

[user1620696]

I'm trying to verify the validity of a token. I mean, a token could have expired or it could simply not be a valid token. I want to be able to verify this using. Searching a little I found out that the introspection endpoint is the way to do it, but I'm not really getting how it is used.

[Mashton]

OP: To expand slightly on @leastprivilege 's answer: you want to base64 encode the string "[yourApiName]:[yourApiSecret]", and use that as the Authorization header basic value.

[Tobias Punke]

I agree. The community leaves a lot to be desired. I had to figure this out by myself as well.

[jmichas]

Thanks for this, saved me so much time. This should be marked as the answer.

[Matt Whitfield]

As you say, 'read the spec' is much less useful than your explanation here

[McGuireV10]

It's inexcusable that this is undocumented. As far as I can tell, the spec (RFC 6749 section 2.3.1) actually describes a completely different implementation (which is optional). IDS4 itself is great but those guys are chasing consulting dollars just a bit too hard.

[McGuireV10]

Note if you're using the IdentityModel library with an HttpClient you can just call SetBasicAuthenticationOAuth(scopename, secret) after creating the client object instead of doing the encoding yourself.

[William Jockusch]

Trying to figure out how to do number 2 "Ensure that you have requested the scope" in a test environment

[Ludvig W]

@WilliamJockusch Go to this site, jwt.io, there you can check the content of your token, check under "scope: [ ???? ]"

[Ludvig W]

This answer is just great. Nothing worked, nothing, and nowhere does it say you have to combine the name and secret in the Basic. Thanks for your answer, save me lot of headache and time!!!