Re: [OAUTH-WG] Confirmation: Call for Adoption of "OAuth Token Introspection" as an OAuth Working Group Item

Justin Richer <> Tue, 29 July 2014 17:37 UTC

Return-Path: <>
Received: from localhost ( []) by (Postfix) with ESMTP id D1BB91B296F for <>; Tue, 29 Jul 2014 10:37:45 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -4.2
X-Spam-Status: No, score=-4.2 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_MED=-2.3, RP_MATCHES_RCVD=-0.001] autolearn=ham
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id dJ2cqlkt0Qnr for <>; Tue, 29 Jul 2014 10:37:35 -0700 (PDT)
Received: from ( []) by (Postfix) with ESMTP id 4B7F61B2963 for <>; Tue, 29 Jul 2014 10:37:31 -0700 (PDT)
Received: from (localhost.localdomain []) by localhost (Postfix) with SMTP id DF37C1F2011; Tue, 29 Jul 2014 13:37:30 -0400 (EDT)
Received: from IMCCAS03.MITRE.ORG ( []) by (Postfix) with ESMTP id C87351F1FFC; Tue, 29 Jul 2014 13:37:30 -0400 (EDT)
Received: from [] ( by IMCCAS03.MITRE.ORG ( with Microsoft SMTP Server (TLS) id; Tue, 29 Jul 2014 13:37:30 -0400
Message-ID: <>
Date: Tue, 29 Jul 2014 13:36:38 -0400
From: Justin Richer <>
User-Agent: Mozilla/5.0 (X11; Linux i686; rv:24.0) Gecko/20100101 Thunderbird/24.6.0
MIME-Version: 1.0
To: Mike Jones <>, Paul Madsen <>, Phil Hunt <>
References: <> <> <> <> <> <> <>
In-Reply-To: <>
Content-Type: multipart/alternative; boundary="------------060202000400070109010609"
X-Originating-IP: []
Cc: "" <>
Subject: Re: [OAUTH-WG] Confirmation: Call for Adoption of "OAuth Token Introspection" as an OAuth Working Group Item
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: OAUTH WG <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Tue, 29 Jul 2014 17:37:46 -0000

I disagree with this position and think it's vital to standardize a 
return structure and a common set of return values -- and that this work 
would be rather pointless without it. Mike, I think you might be 
thinking in terms of introspection simply unpacking what's already 
contained inside the token, and the AS doing the effort of unpacking 
that for the RS. This is, after all, what used to be the case for the 
now-defunct OpenID Connect "CheckID Endpoint". But what's really 
happening here is this general pattern:

  - The client passes the token to the RS. The client doesn't know or 
care what's in the token or what it's used for, it just knows that it 
can use the token at the RS.
  - The RS gets the token and passes it along to the introspection 
endpoint on the AS. The means by which the RS figures out where its AS 
is is out of scope for this bit of work.
  - The AS is looking at the token as passed in, (whether it's 
structured like a JWT, a random UUID, an integer into a DB, whatever 
deployment-specific bit you want) and figures out if the token is any 
good and what it's for. The AS can do this in whatever 
deployment-specific way it wants to: look up the token in a DB, unpack 
the JWT and check the signature, decrypt the token's payload, whatever.
  - The AS returns (in a standardized JSON object) a set of claims about 
the token. While it's possible that these claims can be included in the 
token directly (as a JWT, for instance) and the RS could have read them 
if it knew how to parse said token, it's important that they don't have 
to be communicated that way and the token itself does not have to be 
structured at all. The AS can literally issue a token of "" 
and the RS can do an introspection call to turn "" into 
{valid: true, sub: user-person, aud: resource-server, ... }
  - The RS looks at the returned JSON value and uses that to make its 
authorization decision.

It's imperative to note that the token in OAuth is opaque to the 
*client* -- it is not opaque to other parties, namely the AS. And in 
most deployments, it's not opaque to the RS either, since the RS has to 
be able to turn the OAuth token into something that can help it make 
authorization decisions. Having an introspection endpoint with a 
standardized return value would actually allow the token content itself 
to be opaque to the RS as well as the Client.

All that said, I think there is enough variability and flexibility in 
OAuth deployments that the introspection data response should (and so 
far, has) follow the JWT model: define a core set of claims with clear 
semantics, make them all optional apart from the common "active" field, 
and allow for copious extension. It's a very simple, very useful pattern 
that's been implemented by many different developers.

  -- Justin

On 07/29/2014 01:15 PM, Mike Jones wrote:
> As I see it, there are two different kinds of standardization for 
> introspection that could occur.  One is defining a standard endpoint 
> for doing introspection on an access token and possibly refresh 
> token.  The other is defining standard contents to be returned from 
> the introspection.
> I'm skeptical of the standard contents, given that access tokens and 
> refresh tokens are intentionally opaque. Implementations could range 
> from being an integer index into a database table, to being a UUID to 
> being an encrypted JWT with context-specific claims.  I don't see 
> anything in common in those implementations for introspection to return.
> While I can see marginal utility to having a common endpoint and 
> request syntax, I would be against trying to standardize the contents 
> of what an introspection request might return. It's as 
> deployment-specific as the access token representation itself.
> -- Mike
> *From:*OAuth [] *On Behalf Of *Paul Madsen
> *Sent:* Tuesday, July 29, 2014 2:48 AM
> *To:* Phil Hunt
> *Cc:*
> *Subject:* Re: [OAUTH-WG] Confirmation: Call for Adoption of "OAuth 
> Token Introspection" as an OAuth Working Group Item
> Standardized Introspection will be valuable in NAPPS, where the AS and 
> RS may be in different policy domains.
> Even for single policy domains, there are enterprise scenarios where 
> the RS is from a different vendor than the AS, such as when an API 
> gateway validates tokens issued by an 'IdP' . We've necessarily 
> defined our own introspection endpoint and our gateway partners have 
> implemented it, (at the instruction of the customer in question). But 
> of course it's proprietary to us.
> Paul
> On Jul 28, 2014, at 8:59 PM, Phil Hunt < 
> <>> wrote:
>     That doesn't explain the need for inter-operability. What you've
>     described is what will be common practice.
>     It's a great open source technique, but that's not a standard.
>     JWT is much different. JWT is a foundational specification that
>     describes the construction and parsing of JSON based tokens. There
>     is inter-op with token formats that build on top and there is
>     inter-op between every communicating party.
>     In OAuth, a site may never implement token introspection nor may
>     it do it the way you describe.  Why would that be a problem?  Why
>     should the group spend time on something where there may be no
>     inter-op need.
>     Now that said, if you are in the UMA community.  Inter-op is quite
>     foundational.  It is very very important. But then maybe the spec
>     should be defined within UMA?
>     Phil
>     @independentid
> <>
> <>
>     On Jul 28, 2014, at 5:39 PM, Justin Richer <jricher@MIT.EDU
>     <mailto:jricher@MIT.EDU>> wrote:
>     It's analogous to JWT in many ways: when you've got the AS and the
>     RS separated somehow (different box, different domain, even
>     different software vendor) and you need to communicate a set of
>     information about the approval delegation from the AS (who has the
>     context to know about it) through to the RS (who needs to know
>     about it to make the authorization call). JWT gives us an
>     interoperable way to do this by passing values inside the token
>     itself, introspection gives a way to pass the values by reference
>     via the token as an artifact. The two are complementary, and there
>     are even cases where you'd want to deploy them together.
>      -- Justin
>     On 7/28/2014 8:11 PM, Phil Hunt wrote:
>         Could we have some discussion on the interop cases?
>         Is it driven by scenarios where AS and resource are separate
>         domains? Or may this be only of interest to specific protocols
>         like UMA?
>         From a technique principle, the draft is important and sound.
>         I am just not there yet on the reasons for an interoperable
>         standard.
>         Phil
>         On Jul 28, 2014, at 17:00, Thomas Broyer <
>         <>> wrote:
>             Yes. This spec is of special interest to the platform
>             we're building for
>             On Mon, Jul 28, 2014 at 7:33 PM, Hannes Tschofenig
>             <
>             <>> wrote:
>             Hi all,
>             during the IETF #90 OAuth WG meeting, there was strong
>             consensus in
>             adopting the "OAuth Token Introspection"
>             (draft-richer-oauth-introspection-06.txt) specification as
>             an OAuth WG
>             work item.
>             We would now like to verify the outcome of this call for
>             adoption on the
>             OAuth WG mailing list. Here is the link to the document:
>             If you did not hum at the IETF 90 OAuth WG meeting, and
>             have an opinion
>             as to the suitability of adopting this document as a WG
>             work item,
>             please send mail to the OAuth WG list indicating your
>             opinion (Yes/No).
>             The confirmation call for adoption will last until August
>             10, 2014.  If
>             you have issues/edits/comments on the document, please
>             send these
>             comments along to the list in your response to this Call
>             for Adoption.
>             Ciao
>             Hannes & Derek
>             _______________________________________________
>             OAuth mailing list
>    <>
>             -- 
>             Thomas Broyer
>             /t?.ma.b? <>
>             _______________________________________________
>             OAuth mailing list
>    <>
>         _______________________________________________
>         OAuth mailing list
>  <>
>     _______________________________________________
>     OAuth mailing list
> <>
>     _______________________________________________
>     OAuth mailing list
> <>
> _______________________________________________
> OAuth mailing list