Subject: [OAUTH-WG] dyn reg - Human Readable Client Metadata

From: Phil Hunt <[email-masked]>
Date: Wed, 19 Jun 2013 10:05:20 -0700

I am looking over the section on Human Readable Client Metadata and am a bit confused as it pertains to the rest of the specification and the implications for service providers.

Is it the intention that even single-valued client metadata may have multiple localized values?  Or, is the assumption that  a client would signal its preferred language and that ALL metadata values have only ONE localization at a time?

I started considering this when I got to the section discussing things like having client_name#ja-Jpan-JP and client_name#en.  

Would be a lot simpler to have preferredLanguage be part of the client schema and assume that all human readable fields have been localized by the client.  It seems to me to be more complex if every client registers its entire set of language translations for each piece of metadata if the user will only ever use one at a time.  Why track all variants?

My thought is that in the case of OAuth client interactions, all language localization is to drive the interface for the personal use of the user at hand.  We don't have the case as we do in directories where an english language person might be looking up information about a Japanese person.

That said, it would become a normal for a client to trigger a registration "update" event for the client to update its metadata when the client detected a change in language by the user.  E.g. from en to ja-JPan-JP.

Phil

@independentid
www.independentid.com
[email-masked]

---

From: "Richer, Justin P." <[email-masked]>
Date: Wed, 19 Jun 2013 17:18:57 +0000

Your question seems to assume a one-to-one mapping between client and user, and that's not guaranteed to be the case. Think of an installed web application that's talking to an auth server, and that web application is going to talk to a number of different users. Those users can have multiple different language preferences. The human-readable fields are sent to the auth server so that the auth server can display them to the end user during the authorization screen and the application management screens. As such, it makes sense (and was requested by the working group at the last IETF) that a client can register its whole set of languages and the auth server picks the appropriate one to display to the user. 

It used to be the case that there was only a single value (unadorned with language tags) for things like client_name, and a client would've had to register itself multiple times to get at different languages. The Working Group decided that this was both too complicated and too error prone, so we adopted (and adapted) the OpenID Connect method for flagging languages. This allows a client to register once for all users and all language types. It wouldn't make sense (and it would cause serious race conditions) for a client to try and switch languages mid-stream for different users. 

On the server side, if your auth server wants to handle localized values appropriately, it will need to parse and manage multiple tagged values for each human readable field. However, we're recommending that clients always send the bare field with an internationalized value (i.e., it's got the best chance of being read by the largest audience for the client/auth server, a good default if you will), so you can fairly safely just look for and use the bare fields in most cases. 

Hope this clears things up. If you have any recommendations for how to make this intended usage clearer, I'd be happy to accept some new suggested text.

Thanks,

 -- Justin

On Jun 19, 2013, at 1:05 PM, Phil Hunt <[email-masked]>
 wrote:

> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Phil Hunt <[email-masked]>
Date: Wed, 19 Jun 2013 10:27:05 -0700

Justin

Thanks for refreshing my mind. I forgot the web client case is acting on behalf of many users. 

Phil

---

From: John Bradley <[email-masked]>
Date: Wed, 19 Jun 2013 16:55:40 -0400

Yes that is an important Connect use case for Web server client registration.  Also thought of as a typical web SP.

John B.

---

From: Phil Hunt <[email-masked]>
Date: Wed, 19 Jun 2013 16:36:00 -0700

Ok.  So then going down this path, is the chosen encoding method, which is LDAPish, the right way to go?  

For example, I read the spec as suggesting:

{ 
   …

       "client_name#en":"My Client",
       "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"
  ...
}

Why not make it more JSON-esque such as:

{ 
   …

       "client_name":[
         {
          "value":"My Client",
          "lang":"en",
          "primary":"TRUE"
         }
         {
           "value":"\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
           "lang":"ja-Jpan-JP"
         }
       ]
  …
}

I mention this format as it seems more JSON-like and it is more SCIM-friendly.  Also wondering if anyone knows how vCards does localization?

I agree the draft format is more compact.  But it requires more complex attribute name parsing, whereas the SCIMish expression requires more JSON parsing.

Phil

@independentid
www.independentid.com
[email-masked]

---

From: Justin Richer <[email-masked]>
Date: Thu, 20 Jun 2013 09:04:48 -0400

One of the things I really like about the current approach is that it 
leaves the bare field name as a simple string attribute, like:

{
   ...
        "client_name": "My Client",
        "client_name#en":"My Client",
        "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"
   ...
}

So I can just grab client.client_name and get what I'm expecting most of 
the time, I don't need to pick a language tag if I don't care about or 
don't support them. This is why we're recommending that *all* clients 
send the "client_name" value alone, and if they want to, send 
"client_name#en" and "client_name#ja-Jpan-JP" as well.

With the JSON structure, I'd have to get client.client_name as an array 
and search through it to find the one tagged "primary: true". That's a 
lot of work to just find a display string.

Webfinger currently uses a different JSON structure like this:

      {
        "en-us" : "The Magical World of Bob",
        "fr" : "Le Monde Magique de Bob"
      }

Though it was proposed a while back that they use the hash structure 
instead as well. This also has the problem that I have to call 
client.client_name.en-us explicitly, or client.client_name.und if it's 
there. I think we should make the use cases for single-language 
deployments (and internationlized deployments) simpler, and the hash 
structure does that at the expense of some extra attribute parsing for 
the more complex use case.

  -- Justin

---

From: Phil Hunt <[email-masked]>
Date: Thu, 20 Jun 2013 10:44:18 -0700

The larger issue is that multi-lingual requirements do not go from 1 to 2 or 3 languages, the requirements tend to go to 8 or 60 or more. This is why I was hoping we could observe that clients simply want to select a single preferred language.  That said, web clients clearly need a multi-language solution.

As we do this, imagine javascript clients doing dyn reg with 60 languages. That's a LOT of data being moved around. Even under normal use, scale becomes a concern.  How fast is it parsed? When is it stored? Where is it stored? How is it retrieved and by what component(s)?

I can think of a couple of possibilities to manage this:
* Differentiate between public (or rather personal) clients that tend to use only one language vs. web clients that are fewer in number but support many users with many languages
* Break registration into 2 parts:  software registration (has all the UI and language stuff), and client instance registration (deals with only per-instance protocol driven data).

While my gut reaction is simply towards the first (least breaking), the latter strikes me as far more scalable (though with more complexity) -- especially if the group really wants to proceed with implicit client support that tends to register on every execution.

Any other ideas?

Phil

@independentid
www.independentid.com
[email-masked]

On 2013-06-20, at 6:04 AM, Justin Richer wrote:

> One of the things I really like about the current approach is that it leaves the bare field name as a simple string attribute, like:
> 
> {
>  ...
> So I can just grab client.client_name and get what I'm expecting most of the time, I don't need to pick a language tag if I don't care about or don't support them. This is why we're recommending that *all* clients send the "client_name" value alone, and if they want to, send "client_name#en" and "client_name#ja-Jpan-JP" as well.
> 
> With the JSON structure, I'd have to get client.client_name as an array and search through it to find the one tagged "primary: true". That's a lot of work to just find a display string.
> 
> Though it was proposed a while back that they use the hash structure instead as well. This also has the problem that I have to call client.client_name.en-us explicitly, or client.client_name.und if it's there. I think we should make the use cases for single-language deployments (and internationlized deployments) simpler, and the hash structure does that at the expense of some extra attribute parsing for the more complex use case.
> 
> -- Justin
> 
>

---

From: Justin Richer <[email-masked]>
Date: Thu, 20 Jun 2013 14:37:59 -0400

For clients that simple want to use a single preferred language, we've 
got the bare field without the language tag (eg, "client_name"). I think 
we need to keep that. So the remaining question is whether and how to 
handle multiple language tags. I think any format changes are going to 
have the same scale issues -- it's inherent to the problem that if you 
want to pass around a lot of data, you're going to have a lot of data. 
With the use cases that have been brought up so far, it seems that the 
clients who would register the most often (the "public" dynamic clients) 
would probably have enough in-session information to pick a single 
client for a single user and be done with it. The clients who need to 
register many language for many users would be registering less often. 
So, the scaling problem seems to be self-limiting in that regard, right? 
The Javascript client you describe below probably wouldn't try to 
register with 60 languages, it would just pick one for the current user. 
I think it'll be fairly self-selecting with the general mechanism that's 
in there now, so I don't think that the mechanism for language in 
human-facing fields actually needs to change for this reason.

However: Splitting things in two, as you suggest, is a prime candidate 
for an extension to dynamic registration. If we do it right we can solve 
it for more than just the language tags *without* breaking the 
underlying registration spec, which is already useful on its own. 
Specifically, if you're doing a two-stage dynamic registration, your 
first stage is the new step defined by the extension and the second 
(instance) stage is the existing Dyn-Reg spec with some extra processing 
on the part of the registration endpoint. If we can define the right 
mechanisms around assertions, discovery, validation, pre-registry and 
all that, you can actually do things pretty much exactly we both want 
to. The new pre-registration process handles any "fixed" parameters 
(languages, redirects, and stuff, perhaps) and generates something that 
can be handed to all instances of the software. This is a thing that can 
be validated by the registration endpoint and used to tie the instance 
presenting it into a larger ecosystem of a particular piece of software. 
Every instance will still get its own client_id and client_secret (a 
good thing), but the AS would know how to tie all these things together.

With that in mind, I think it's important that we have the appropriate 
extension mechanisms in the dynamic registration spec to allow it, and 
so far, everything is there that I can think of. You can use the initial 
access token in the call to the registration endpoint (like we did with 
BB+), you can have an extension parameter to the client metadata (like 
you proposed with software_id, particularly as an assertion), and it's 
up to the registration endpoint to validate any of these. What we need 
are definitions of what actually goes *in* any of these components as 
well as the appropriate rules for validation and parsing in order for 
them to be useful and interoperable.

  -- Justin

---

From: Phil Hunt <[email-masked]>
Date: Thu, 20 Jun 2013 13:14:56 -0700

Let's think on this. I'm not convinced (yet) that creating an extension point is the right thing to do.  For me, extensions are appropriate when there is a need to support multiple ways of doing something -- like tokens for example.   

In this case, we're talking about adding a single, possibly optional, way of doing something. IOW. I think this is a "if you are going to do it, you must do it this way" situation.

Still, in general, we could try to work it in a backwards compatible way if possible.

Phil

@independentid
www.independentid.com
[email-masked]

On 2013-06-20, at 11:37 AM, Justin Richer wrote:

> For clients that simple want to use a single preferred language, we've got the bare field without the language tag (eg, "client_name"). I think we need to keep that. So the remaining question is whether and how to handle multiple language tags. I think any format changes are going to have the same scale issues -- it's inherent to the problem that if you want to pass around a lot of data, you're going to have a lot of data. With the use cases that have been brought up so far, it seems that the clients who would register the most often (the "public" dynamic clients) would probably have enough in-session information to pick a single client for a single user and be done with it. The clients who need to register many language for many users would be registering less often. So, the scaling problem seems to be self-limiting in that regard, right? The Javascript client you describe below probably wouldn't try to register with 60 languages, it would just pick one for the current user. I think it'll be fairly self-selecting with the general mechanism that's in there now, so I don't think that the mechanism for language in human-facing fields actually needs to change for this reason.
> 
> However: Splitting things in two, as you suggest, is a prime candidate for an extension to dynamic registration. If we do it right we can solve it for more than just the language tags *without* breaking the underlying registration spec, which is already useful on its own. Specifically, if you're doing a two-stage dynamic registration, your first stage is the new step defined by the extension and the second (instance) stage is the existing Dyn-Reg spec with some extra processing on the part of the registration endpoint. If we can define the right mechanisms around assertions, discovery, validation, pre-registry and all that, you can actually do things pretty much exactly we both want to. The new pre-registration process handles any "fixed" parameters (languages, redirects, and stuff, perhaps) and generates something that can be handed to all instances of the software. This is a thing that can be validated by the registration endpoint and used to tie the instance presenting it into a larger ecosystem of a particular piece of software. Every instance will still get its own client_id and client_secret (a good thing), but the AS would know how to tie all these things together.
> 
> With that in mind, I think it's important that we have the appropriate extension mechanisms in the dynamic registration spec to allow it, and so far, everything is there that I can think of. You can use the initial access token in the call to the registration endpoint (like we did with BB+), you can have an extension parameter to the client metadata (like you proposed with software_id, particularly as an assertion), and it's up to the registration endpoint to validate any of these. What we need are definitions of what actually goes *in* any of these components as well as the appropriate rules for validation and parsing in order for them to be useful and interoperable.
> 
> -- Justin
>

---

From: Mike Jones <[email-masked]>
Date: Thu, 20 Jun 2013 20:17:25 +0000

I'm skeptical of multi-phase registration.  It seems more complicated than the "problem" that it's trying to solve.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Phil Hunt
Sent: Thursday, June 20, 2013 1:15 PM
To: Justin Richer
Cc: [email-masked] WG
Subject: Re: [OAUTH-WG] dyn reg - Human Readable Client Metadata

Phil

@independentid
www.independentid.com
[email-masked]

---

From: Justin Richer <[email-masked]>
Date: Thu, 20 Jun 2013 16:36:04 -0400

Mike,

The multi-phase registration isn't necessarily all automated (though it 
could be) and this actually fits directly along side use cases B2 and B3 
in draft 12 of Dyn Reg. The difference is that the current use cases 
assume auth-provider-specific behaviors and mechanisms by calling them 
out of scope (which is still useful, just like with token formats being 
opaque in OAuth) but this other work would be creating one concrete, 
interoperable mechanism for doing this (which is also useful, like the 
JWT token format).

  -- Justin