[Txauth] Use Case: Directed Tokens

[Justin Richer <[e-mail]>]

One of the most important aspects to GNAP is going to be an ability to address things that OAuth 2 can’t, or at least can’t do without significant gymnastics. So with that, I wanted to bring back a use case discussion that originally came up while we were talking about the possibility of multiple access tokens, a few months back. I don’t know if this concept has a regular term, so I’m going to call it “directed access tokens” until we come up with something better — assuming we decide this is worthwhile. 

In OAuth, the client’s supposed to always know where to send its access token, and that knowledge is completely outside the protocol. This makes a lot of sense for many (if not most) deployments, as OAuth is really there to enable the API access that the client already knows about.

But we’re now in a world where a client could be talking to a generic API that could be deployed at a number of different places, or a cloud deployment that the AS wants to be able to dispatch the client to. In order to do this, the AS needs to be able to communicate to the client not only the token information (and any related key and presentation information), but also a set of directions about what that specific token is good for. This needs to be information outside the token itself, since I believe we want to keep OAuth 2’s feature of having the token be opaque to the client. Note: while we could map all of these to different resource requests (in XYZ parlance) or scopes (in OAuth 2 legacy parlance) on the request side, this isn’t enough to tell the client what to do with the token if it doesn’t know already. 

I know of two use cases already in the wild, where people are addressing things using a mix of existing standards and some proprietary extensions to address things within their silos. I’ll try to summarize here, but I know the folks I’ve been talking to about this are also on the list so hopefully they can chime in with more detail or any corrections for something I’ve missed. 

(1) The client knows what resource it’s calling, but it doesn’t know where it’s hosted. Everything is in a single security domain controlled by the AS, but the AS needs to decide at runtime which specific instance of the API to direct the client to. Since things are closely tied together, the client just needs to effectively known an identifier for the RS, and this is currently implemented as a URI. Once the client has that identifier, it knows how to dispatch that token to that instance of the RS.

(2) The client knows what kind of thing it’s looking for, but doesn’t know who to ask it from. There’s a cross-domain trust that’s bridged by the AS, and the AS needs to dispatch to different resources depending on which user logged in (and possibly what the user consented to). To make things more concrete, the client needs to get driver’s license information, but doesn’t know ahead of time which of the many state/provincial bureaus to call to get that information because it doesn’t know yet who the user is. The AS will know who the user is once they log in and approve things, and so it can direct the client to call the correct RS. Since this is a relatively simple API with a pre-negotiated cross-domain trust, the AS returns a URL that the client presents the token at. 

As far as I know, in both of these cases, the token is only good for that API and not others — but more on that later.

A simple thing to do is just give back a URL with the access token, which tells the client where to go. 

	{
		“access_token”: {
			“value”: “87yui843yfer”,
			“resource_uri”: “https://example/foo"
		}
	}

This is good for some kinds of APIs, but it’s limiting because not all APIs dispatch based on the URL. An AS might want to divvy up access tokens to an API that’s keyed on headers, or verbs, or any number of things. And it doesn’t tell us immediately what to do about non-exact URL matches. Can the client add query parameters and still use the token? What about path segments? I like that this simple approach addresses some common deployments that we already see today (see above), it’s not universal. Do we want or need a universal description language for directing where tokens go?

This also opens up a whole new set of security questions. If the AS can now direct the client where to use the token, could a rogue AS convince a legit client to use a stolen token at the wrong RS? And what if the client ignores the directions from the AS entirely? Could this open up new avenues of attack?

This is just the start, too. Things get even more complex if the client can ask for multiple different kinds of resources at once. What if the AS decides that the client needs a hyper-focused directed token for one part of the API, but can use a general token for other stuff? Can it signal that to the client? And if it can, does that mean that all clients need to be prepared for that kind of thing?

I firmly believe that whatever we build in GNAP, we need to optimize for the overwhelmingly common use case of a client getting a single access token to call APIs that it already knows about. Anything we add on top of that really can’t get in the way of this, because if it does, there’s very small chance that people will try to use this for everyday things. Keep the simple things simple, and the complex things possible, after all.

I’m really looking forward to hearing what the community thinks about these use cases, and hopefully the people I’ve chatted with offline about this can join the conversation and provide more light than I was able to.

 — Justin