34

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?

user1620696
  • 10,825
  • 13
  • 60
  • 81
  • What are you trying to achieve with the introspection endpoint? – Shaun Luttin Feb 09 '17 at 03:03
  • 2
    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. – user1620696 Feb 09 '17 at 03:50

3 Answers3

62

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.

Pang
  • 9,564
  • 146
  • 81
  • 122
Jay
  • 9,561
  • 7
  • 51
  • 72
  • 3
    I agree. The community leaves a lot to be desired. I had to figure this out by myself as well. – Tobias Punke Aug 01 '18 at 09:56
  • Thanks for this, saved me so much time. This should be marked as the answer. – jmichas Sep 02 '18 at 04:49
  • 3
    As you say, 'read the spec' is much less useful than your explanation here – Matt Whitfield Sep 07 '18 at 12:50
  • 9
    It's inexcusable that this is undocumented. As far as I can tell, the spec (RFC 6749 [section 2.3.1](https://tools.ietf.org/html/rfc6749#page-16)) 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 Dec 18 '19 at 14:11
  • 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. – McGuireV10 Dec 18 '19 at 14:18
  • Trying to figure out how to do number 2 "Ensure that you have requested the scope" in a test environment – William Jockusch Apr 05 '20 at 16:43
  • @WilliamJockusch Go to this site, jwt.io, there you can check the content of your token, check under "scope: [ ???? ]" – Ludvig W Oct 27 '20 at 13:41
  • 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!!! – Ludvig W Oct 27 '20 at 13:45
9

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.

leastprivilege
  • 18,196
  • 1
  • 34
  • 50
  • 7
    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. – Mashton Feb 14 '17 at 14:34
2

@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")
Community
  • 1
  • 1
Godfrey
  • 1,001
  • 14
  • 17