Re: [OAUTH-WG] Dynamic Client Registration

["Richer, Justin P." <[e-mail]>]

Hi Hannes, thanks for the review. Comments inline.

On Jan 12, 2015, at 6:11 AM, Hannes Tschofenig <[e-mail]> wrote:

> 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'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?

> 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.

The examples are included in Appendix A. 

> 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.

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).

> 
> 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.
> 

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

> 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?

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.

> 
> 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.
> "
> 

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