Subject: [OAUTH-WG] Dynamic Client Registration

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 12 Jan 2015 12:11:52 +0100

Hi Justin, Hi all,

as noted in my status update I am trying to finalize the pending items.

Hence, I re-read the draft-ietf-oauth-dyn-reg-21 document since my
review of draft-ietf-oauth-dyn-reg-management raised some questions
about the terminology.

If you look at the structure of the ToC then you will notice the following:

   3.  Client Registration Endpoint  . . . . . . . . . . . . . . . .  13
     3.1.  Client Registration Request . . . . . . . . . . . . . . .  14
       3.1.1.  Client Registration Request Using a Software
               Statement . . . . . . . . . . . . . . . . . . . . . .  15
     3.2.  Client Registration Response  . . . . . . . . . . . . . .  16
   4.  Responses . . . . . . . . . . . . . . . . . . . . . . . . . .  16
     4.1.  Client Information Response . . . . . . . . . . . . . . .  17
     4.2.  Client Registration Error Response  . . . . . . . . . . .  18

There is no 'Client Registration Response' in the protocol (only the
Client Information Response) and section 3.2 is pretty much empty and
only points to the later sections. So, I would suggest to do the following.

   3.  Client Registration Endpoint
     3.1.  Client Registration Request
       3.1.1.  Client Registration Request Using a Software Statement
     3.2.  Client Registration Response
       3.2.1.  Client Information Response
       3.2.2.  Client Registration Error Response

(A section with only a single sub-section is also a sign of a bad
structure.)

I re-read the terminology and looked at Figure 1 to see whether it makes
sense and it still does not. I know that there may be many different
deployment options but it should at least be clear to the reader where
information comes from and where does it go.

For example, when I try to follow the flow of the software statement
then I read the following:
"
Software Statement: In some cases, a software statement will be issued
directly by the organization or developer that creates the client software.
"

What does the figure tell us? It shows us that the client or developer
gets the software assertion.

        +--------(A)- Initial Access Token (OPTIONAL)
        |
        |   +----(B)- Software Statement (OPTIONAL)
        |   |
        v   v
    +-----------+                                      +---------------+
    |           |--(C)- Client Registration Request -->|    Client     |
    | Client or |                                      | Registration  |
    | Developer |<-(D)- Client Information Response ---|   Endpoint    |
    |           |                                      +---------------+
    +-----------+

Maybe we should illustrate one example that makes sense and then say
that there are others that could be used. It also does not make sense to
show the developer in the box together with the client since the
developer does not execute a protocol exchange with the client
registration endpoint.

Here is a proposal for improving this:

FROM:

        +--------(A)- Initial Access Token (OPTIONAL)
        |
        |   +----(B)- Software Statement (OPTIONAL)
        |   |
        v   v
    +-----------+                                      +---------------+
    |           |--(C)- Client Registration Request -->|    Client     |
    | Client or |                                      | Registration  |
    | Developer |<-(D)- Client Information Response ---|   Endpoint    |
    |           |                                      +---------------+
    +-----------+

    Figure 1: Abstract Dynamic Client Registration Flow

TO:

    +--------  O  -- (A)- Initial Access Token (OPTIONAL)
    |         /|\
    |   +---- / \ -- (B)- Software Statement (OPTIONAL)
    |   |   Client
    |   |   Developer
    |   |
    v   v
+--------------+                                      +---------------+
|              |--(C)- Client Registration Request -->|    Client     |
|   Client     |                                      | Registration  |
|              |<-(D)- Client Information Response ---|   Endpoint    |
+--------------+                                      +---------------+

  Figure 1: Abstract Dynamic Client Registration Flow

Alternatively, one could also separate the distribution of software
statements and the actual protocol exchange. Here is the proposal:

    +--------(A)- Initial Access Token (OPTIONAL)
    |
    |   +----(B)- Software Statement (OPTIONAL)
    |   |
    v   v
+-----------+                                      +---------------+
|           |--(C)- Client Registration Request -->|    Client     |
|   Client  |                                      | Registration  |
|           |<-(D)- Client Information Response ---|   Endpoint    |
+-----------+                                      +---------------+

 Figure 1: Abstract Dynamic Client Registration Flow

           +---------------+
           | Authorization |
           | Server        |
           +---------------+
                 |    Initial
                 |(A) Access
                 |    Token
                 v
                  O  Client
         +------ /|\ Developer
         |+----- / \
         ||
      (A)||(B) Software
         ||    Statement
         vv
  +-----------+
  |           |
  |   Client  |
  |           |
  +-----------+

Figure 2: Software Statement / Initial Access Token Distribution Example.

Then, there is also this statement in the Software Statement definition:

"
      In other cases, a
      software statement will be issued by a third party organization
      for use by the organization or developer that creates the client
      software.
"

In the terminology section we are defining all the parties that are
involved and now this mysterious "third party organization" is
introduced. Is this one of the already defined parties or is this yet
another organization?

Finally, the client developer is defined as a single individual or an
entire organization (i.e., a group of people). However, in the text you
write 'client developer or organization'. For example, look at the
software statement:

"In some cases, a software statement will be issued directly by the
organization or developer that creates the client software.
"

Wouldn't it be more consistent to use the client developer definition as
is and just turn this sentence into

"
In some cases, a software statement will be issued directly by the
client developer.
"

Ciao
Hannes

---

From: "Richer, Justin P." <[email-masked]>
Date: Tue, 13 Jan 2015 23:08:59 +0000

Hi Hannes, thanks for the review. Comments inline.

> (A section with only a single sub-section is also a sign of a bad

I'm actually OK with this re-organization, as long as there's no objection from the WG at this stage. I think what we have might be slightly vestigial of the existing document. There *is* a client registration response, but it's one of two things: the information or error response. Collapsing them as above will likely make that section easier to read. Thoughts?

> that there are others that could be used.

The examples are included in Appendix A. 

> It also does not make sense to

That's not true, a developer (person or organization) could very easily be using the dynamic registration protocol on behalf of the software that they're developing. This is actually used in practice in a number of places, and if you'd like a concrete example just go to the MIT integration test site: https://mitreid.org/manage/dev/dynreg (log in with user/password).

>        |   +----(B)- Software Statement (OPTIONAL)

This is inaccurate, as described above. I believe we should leave this as is.

> introduced. Is this one of the already defined parties or is this yet

This is just exemplary text, saying one way that it could happen. The "mysterious" third party organization is someone who is not the authorization server or software API publisher who issued the statement (those cases are covered by the preceding sentence). They're not a named party, it's just "whoever made the software statement". We are not specifying which software statements the AS decides to trust, since that's a policy decision outside of our control as spec authors. Many authorization servers will only trust software statements that they issue, but others will have a configured set of third parties that they will accept software statements from, probably as part of a trust framework. I think this text should be left as it is unless there's a way to word this so that it doesn't sound like we're adding another explicitly named party to the mix.

> In some cases, a software statement will be issued directly by the

Since "developer" can mean individual or organization, I'm fine with this simplifying change as long as there's no objection from the WG.

Thanks again for the review.
 -- Justin

---

From: Phil Hunt <[email-masked]>
Date: Tue, 13 Jan 2015 15:24:01 -0800

in line
Phil

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

> On Jan 13, 2015, at 3:08 PM, Richer, Justin P. <[email-masked]> wrote:
> 

IMO. This defeats the purpose of dynamic registration. A developer that wants to hand register would go through the SP’s developer support pages as they do now.

It also won’t work in cases where an individual client will negotiate a client key (where the actual key is not shared and thus the developer (or any other MITM) can’t get in between.

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

---

From: "Richer, Justin P." <[email-masked]>
Date: Tue, 13 Jan 2015 23:30:34 +0000

> It also won’t work in cases where an individual client will negotiate a client key (where the actual key is not shared and thus the developer (or any other MITM) can’t get in between.

If it were only authenticated portal pages, then I'd agree with you, but it's not. The page I pointed to above is just a wrapper shell around the dynamic registration endpoint -- it doesn't even *need* the user's credentials to function, but that's how our server is set up to present the page, which might be confusing people. On our server, only server admins can access the "real" client registration page, which isn't as limited as the dynamic registration page. There are other use cases that have things like build frameworks that do the registration on behalf of a client instance or version, where it's the developer (in this case an organization/system) and not the client software doing the registration. 

Basically, there was a strong argument for leaving that particular door open, all of which is documented in the Use Cases appendix and liberally on the list.

 -- Justin

---

From: John Bradley <[email-masked]>
Date: Tue, 13 Jan 2015 21:05:33 -0300

We have used the dynamic client registration API for building portals for developers to register clients.   
I am seeing that across several telco operators at the moment.

Yes everyone could have custom web pages but this is at-least a common way to build that sort of thing.
This is not just about registering instances of native apps.

The GSMA mobile connect profile is going to use dynamic client registration based on a software statement from a trusted party to allow web sites to register as clients to 800+ AS.

Those sites may well be developers of there own client or have a central admin for several clients.

I don't think that we want to say that it is only the client that interacts with the registration or management endpoint.  
That is too limiting on the applications for this API.

John B.

> On Jan 13, 2015, at 8:24 PM, Phil Hunt <[email-masked]> wrote:
> 
> in line
> Phil
> 
> @independentid
> www.independentid.com
> [email-masked]
>