Subject: [OAUTH-WG] JWT audience claim

From: Brian Campbell <[email-masked]>
Date: Tue, 18 Dec 2012 14:41:05 -0700

WG folks,

I'm wondering if the current definition of the "aud" (audience) claim in
JWT [1], which limits the value of the claim to a case sensitive string
containing a StringOrURI value, might not be flexible enough?

In thinking about or discussing various potential applications of JWT, the
possibility of having a token intended for consumption by more than one
entity has come up frequently. One such example would be an AS that is
using JWTs as structured access tokens intended for use at multiple RSs and
wants to audience restrict those access tokens. Doing that with the current
JWT and "aud" claim could be rather awkward in that a single aud value
would need to somehow represent multiple entities, which seems likely to be
done in very application specific ways that would not result in much
interoperability. Scope is potentially applicable in this case but isn't
standardized at that level and wouldn't be useful outside of OAuth specific
applications.

At a high level, I'm proposing that we consider changing the definition of
"aud" to allow for an array of StringOrURI values. And change the
processing requirement such that the thing consuming the claim must
identify itself with [at least] one of the values of the "aud" claim array.
That would allow a JWT AT that's intended for consumption by RS 1, 2 and 3
to be audience restricted like this, "aud": ["RS1", "RS2", "RS3"] and an
individual RS just needs to find itself in one of the values of the claim.

Such a change would add some complexity but I'm beginning to think that
it's a good trade off for the added flexibility it brings. The validation
would be basically the same but just over a list of values rather than
against a single one. We would have to decide whether the case of a single
audience could still be represented as it is now or if everything would
always have to be an array (i.e. "aud": "RS" vs. "aud": ["RS"] ). The
former introduces slightly more complexity to validation but is a nice
optimization for the common case and would preserve compatibility with
existing implementations.

Thoughts, comments, questions, or angry diatribes?

Thanks,
Brian

[1]
http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-05#section-4.1.5

---

From: John Bradley <[email-masked]>
Date: Tue, 18 Dec 2012 19:14:33 -0300

We probably also need to consider this in light of people like Google already adding new JWT claims to specify a secondary audience, though there 'cid' Client ID claim is more about who requested the token.

I am not keen on claims that are sometimes a literal and sometimes an array, though it works in JSON it can be confusing.

Are you proposing that aud us always an array with one or more values, or that it is a literal if it is one value and array if more than one?

The other way to deal with it is having a abstract audience that all the recipients recognize.  Though that has its own issues.

Having one way to do it would be better, I just don't have a good feeling that it is worth complicating the simple case where there is only one audience.

I might be convinced of the utility for aud to be an array if you need mopre than one value and leave the single case as a literal.

John B.

On 2012-12-18, at 6:41 PM, Brian Campbell <[email-masked]> wrote:

> WG folks,
> 
> I'm wondering if the current definition of the "aud" (audience) claim in JWT [1], which limits the value of the claim to a case sensitive string containing a StringOrURI value, might not be flexible enough?
> 
> In thinking about or discussing various potential applications of JWT, the possibility of having a token intended for consumption by more than one entity has come up frequently. One such example would be an AS that is using JWTs as structured access tokens intended for use at multiple RSs and wants to audience restrict those access tokens. Doing that with the current JWT and "aud" claim could be rather awkward in that a single aud value would need to somehow represent multiple entities, which seems likely to be done in very application specific ways that would not result in much interoperability. Scope is potentially applicable in this case but isn't standardized at that level and wouldn't be useful outside of OAuth specific applications.   
> 
> At a high level, I'm proposing that we consider changing the definition of "aud" to allow for an array of StringOrURI values. And change the processing requirement such that the thing consuming the claim must identify itself with [at least] one of the values of the "aud" claim array. That would allow a JWT AT that's intended for consumption by RS 1, 2 and 3 to be audience restricted like this, "aud": ["RS1", "RS2", "RS3"] and an individual RS just needs to find itself in one of the values of the claim.
> 
> Such a change would add some complexity but I'm beginning to think that it's a good trade off for the added flexibility it brings. The validation would be basically the same but just over a list of values rather than against a single one. We would have to decide whether the case of a single audience could still be represented as it is now or if everything would always have to be an array (i.e. "aud": "RS" vs. "aud": ["RS"] ). The former introduces slightly more complexity to validation but is a nice optimization for the common case and would preserve compatibility with existing implementations. 
> 
> [1]  http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-05#section-4.1.5  
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Brian Campbell <[email-masked]>
Date: Tue, 18 Dec 2012 16:16:26 -0700

Inline...

On Tue, Dec 18, 2012 at 3:14 PM, John Bradley <[email-masked]> wrote:
> We probably also need to consider this in light of people like Google
> already adding new JWT claims to specify a secondary audience, though there
> 'cid' Client ID claim is more about who requested the token.

There is a lot of similarity.  When I first heard about the cid claim,
I wondered if they might have used multiple aud values to accomplish
the same thing, if that been readily available in the spec. There are
some subtle differences between the two and I don't fully understand
the reasons for going with that secondary claim name.

> I am not keen on claims that are sometimes a literal and sometimes an array,
> though it works in JSON it can be confusing.
>
> Are you proposing that aud us always an array with one or more values, or
> that it is a literal if it is one value and array if more than one?

I could go either way. But I'd lean towards the latter given all the
considerations.

> The other way to deal with it is having a abstract audience that all the
> recipients recognize.  Though that has its own issues.

Indeed. And is complicated in applications or specifications that
require audience to be a very specific value (OpenID Connect, for
example, dictates that the aud of the id token "MUST be the OAuth 2.0
client_id of the Client.").

> Having one way to do it would be better, I just don't have a good feeling
> that it is worth complicating the simple case where there is only one
> audience.

Fair enough.

> I might be convinced of the utility for aud to be an array if you need mopre
> than one value and leave the single case as a literal.

I think that's where it'll end up, if there's a (rough) consensus to
make a change.

> I'm wondering if the current definition of the "aud" (audience) claim in JWT
> [1], which limits the value of the claim to a case sensitive string
> entity has come up frequently. One such example would be an AS that is using
> JWTs as structured access tokens intended for use at multiple RSs and wants
> to audience restrict those access tokens. Doing that with the current JWT
> and "aud" claim could be rather awkward in that a single aud value would
> need to somehow represent multiple entities, which seems likely to be done
> in very application specific ways that would not result in much
> "aud" to allow for an array of StringOrURI values. And change the processing
> requirement such that the thing consuming the claim must identify itself
> with [at least] one of the values of the "aud" claim array. That would allow
> a JWT AT that's intended for consumption by RS 1, 2 and 3 to be audience
> restricted like this, "aud": ["RS1", "RS2", "RS3"] and an individual RS just
> needs to find itself in one of the values of the claim.
>
> Such a change would add some complexity but I'm beginning to think that it's
> a good trade off for the added flexibility it brings. The validation would
> be basically the same but just over a list of values rather than against a
> single one. We would have to decide whether the case of a single audience
> could still be represented as it is now or if everything would always have
> to be an array (i.e. "aud": "RS" vs. "aud": ["RS"] ). The former introduces
> slightly more complexity to validation but is a nice optimization for the
> common case and would preserve compatibility with existing implementations.
>

---

From: Dale Olds <[email-masked]>
Date: Tue, 18 Dec 2012 16:00:34 -0800

comments inline:

On 12/18/2012 02:14 PM, John Bradley wrote:
> already adding new JWT claims to specify a secondary audience, though 
> there 'cid' Client ID claim is more about who requested the token.

In our implementation we produce JWTs with an 'aud' claim that is an 
array of audience identifiers.

>
> I am not keen on claims that are sometimes a literal and sometimes an 
> array, though it works in JSON it can be confusing.
>
> Are you proposing that aud us always an array with one or more values, 
> or that it is a literal if it is one value and array if more than one?
In our usage, it's always an array. While I agree with a single, simple 
data type, I think your last suggested syntax is preferable in this 
case: simple single values and the ability to have arrays when needed.

>
> The other way to deal with it is having a abstract audience that all 
> the recipients recognize.  Though that has its own issues.
>
> Having one way to do it would be better, I just don't have a good 
> feeling that it is worth complicating the simple case where there is 
> only one audience.
>
> I might be convinced of the utility for aud to be an array if you need 
> mopre than one value and leave the single case as a literal.

For better or worse, here's a possible use case:

In our system we have a number of resource servers. We use scope as a 
list of values in the form of <RS>.<role>. So for resource servers A, B, 
and C and roles Read, Admin, and Audit, an application could request an 
access token with a scope of "A.Admin B.Audit C.Read". We produce a JWT 
access token which contains"aud":["A","B","C"]. Such a token could be 
presented to each RS which would validate the token and verifies that it 
is in the intended audience list. This approach has been quite useful 
and flexible.

The downside is that we are not forcing complete insulation of the RSs 
from each other. However, in our case some set of the RSs already have a 
relationship with each other such that isolation from each other in the 
token audience is of no benefit. So IMO the value of allowing an array 
of audiences outweighs the downside.

--Dale

>
> John B.
>
> On 2012-12-18, at 6:41 PM, Brian Campbell <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>> WG folks,
>>
>> I'm wondering if the current definition of the "aud" (audience) claim 
>> in JWT [1], which limits the value of the claim to a case sensitive 
>> string containing a StringOrURI value, might not be flexible enough?
>>
>> In thinking about or discussing various potential applications of 
>> JWT, the possibility of having a token intended for consumption by 
>> more than one entity has come up frequently. One such example would 
>> be an AS that is using JWTs as structured access tokens intended for 
>> use at multiple RSs and wants to audience restrict those access 
>> tokens. Doing that with the current JWT and "aud" claim could be 
>> rather awkward in that a single aud value would need to somehow 
>> represent multiple entities, which seems likely to be done in very 
>> application specific ways that would not result in much 
>> interoperability. Scope is potentially applicable in this case but 
>> isn't standardized at that level and wouldn't be useful outside of 
>> OAuth specific applications.
>>
>> At a high level, I'm proposing that we consider changing the 
>> definition of "aud" to allow for an array of StringOrURI values. And 
>> change the processing requirement such that the thing consuming the 
>> claim must identify itself with [at least] one of the values of the 
>> "aud" claim array. That would allow a JWT AT that's intended for 
>> consumption by RS 1, 2 and 3 to be audience restricted like this, 
>> "aud": ["RS1", "RS2", "RS3"] and an individual RS just needs to find 
>> itself in one of the values of the claim.
>>
>> Such a change would add some complexity but I'm beginning to think 
>> that it's a good trade off for the added flexibility it brings. The 
>> validation would be basically the same but just over a list of values 
>> rather than against a single one. We would have to decide whether the 
>> case of a single audience could still be represented as it is now or 
>> if everything would always have to be an array (i.e. "aud": "RS" vs. 
>> "aud": ["RS"] ). The former introduces slightly more complexity to 
>> validation but is a nice optimization for the common case and would 
>> preserve compatibility with existing implementations.
>>
>> [email-masked] <mailto:[email-masked]>

---

From: Nat Sakimura <[email-masked]>
Date: Wed, 19 Dec 2012 11:49:46 +0900

FYI, I have just posted proposed text for 'cid' in a separate thread.

Nat

-- 
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en