Subject: [OAUTH-WG] draft-ietf-oauth-dyn-reg-17 review

From: Hannes Tschofenig <[email-masked]>
Date: Thu, 05 Jun 2014 09:42:01 +0200

Hi Justin, Hi Mike,

thanks for updating the document so quickly.

I have re-read the new version and I have a few minor comments.

You write: "The following client metadata fields are defined by this
specification. All client metadata fields are OPTIONAL."

I guess you mean "Optional to implement and optional to use.". Maybe it
would be good to state that.

In the terminology section you briefly introduce a number of actors and
concepts. The description for the initial access token and the software
statement is somewhat short.

I am particularly interested to learn who issues the initial access
token and the software statement? What is the purpose? What does it
authorize?

I still don't fully get the idea of having both tokens (the initial
access token and the software assertion). Stating who issues those might
clarify it. If different parties provide different statements or grant
different authorization rights based on these two "tokens" then I am
happy but with the current write-up I feel that there is something missing.

Redirect URIs: The text says:
"It is RECOMMENDED that clients using these flows register this
parameter, and an authorization server SHOULD require registration of
valid redirect URIs for all clients that use these grant types to
protect against token and credential theft attacks."

The security consideration section is equally weak:
"For clients that use redirect-based grant types such as
authorization_code and implicit, authorization servers SHOULD require
clients to register their redirect_uris in full."

Shouldn't the recommendation be a bit stronger particularly in light of
the recently discussed covered redirect attack?

What happens if the client does not provide any redirect uris? I
recommend to avoid the SHOULD because it is nothing a protocol
specification can fulfill. It seems to be rather a policy issue. I think
there should also be a description about "full" means here as well. For
example, would the AS be expected to understand something like
https://*.example.com?

MUST, MAY, SHOULDs: I think that the document still uses RFC 2119
language too excessively at places where it does not provide any
guidance for protocol implementers. I would recommend to carefully
re-read each MUST/MAY/SHOULD and judge whether it imposes any
implementation specific requirements and if it doesn't to replace it
with deployment recommendations instead. Also, if there is a SHOULD then
it should be clear to the reader under what circumstances what action
should be taken.

policy_uri: In my previous review I argued that the right terminology
here is privacy notice and you can even re-use the IAPP terminology.
Unless the policy URI has nothing to do with privacy I would prefer this
terminology change. If you disagree I would prefer to have a
description about what policy means in this context.

jwks: my problem with the fuzzy description is that it is not indicated
how the client (or any other party) would reference the listed keys and
what these would be used for. Maybe this document is not the right place
to define these JWKs if the semantic cannot be defined properly.

Regarding the ‘software_id' definition. You write that the software_id
is asserted by the client software but wouldn't it be more reasonable
that some human (in an organization) asserts something rather than
software. The software just acts on behalf of the human. Would it be
reasonable to say that a client developer makes these assertions.

Regarding Section 4.2 client registration error response: Does a
response message always contain two members, namely error and
error_description? I would argue that the error member must be there but
the error_description is optional.

Regarding the error values I am missing a value that allows the
authorization server that a specific field has to be provided and is
currently absent.

Ciao
Hannes

---

From: Phil Hunt <[email-masked]>
Date: Thu, 5 Jun 2014 09:29:31 -0700

Hannes,

I’ll clarify the software statement and let Mike/Justin respond for the rest.

Phil

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

> token and the software statement? What is the purpose? What does it

These tokens have very different characteristics. The Software Statement is not a security token. It is a statement that locks the registration profile for client software and provides AS endpoints with a way to recognize client software since they do not have a client_id yet. In practical terms, AS endpoints can set policy to automatically approve reject based on specific statement, or content rules (software_id, version etc) or even approve based on the signer of the statements (e.g. allow registration for any client software statement signed by Cisco).  

Typically, the statement would be generated once (for all copies distributed) by the developer, publisher, or a collective organization.  This is particularly useful when the publisher of an API  is not the same organization as the deployers of the actual API endpoints following a common open API specification. For example, OpenID Connect would be one such example.  

In the early OAuth1 and 2 days, most use cases had the API publisher and the deployer as the same organization. A client_id could be issued in advance and could be used as both credential id and software identifier.  In the evolving world, we have lots of cases (e.g. OpenID Connect) where the organization that defines the API specification is not the same as the one operating implementations of the API specification.  Client_id can’t serve both purposes.  Software statement fills the gap allowing client software to use a client statement “claim” that can be “exchange” for a deployment assigned client_id.

Initial access token is a security token that allows the client to register in a closed/restricted registration endpoint where anonymous registration may not be allowed.  Useful in some environments where an IT organization might re-package a client for distribution on an internal or private system. 

Where the software statement is issued by either the developer or the API specification organization, the initial access token is typically issued by the “domain” (or an organization affiliated with it) where the client intends to register.

—> have I got that correctly justin?
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Mike Jones <[email-masked]>
Date: Thu, 5 Jun 2014 19:18:32 +0000

The answer to your question about the Initial Access Token and Software Statement is highly parallel to the answer to your question in the other thread about the Access Token and ID Token. :-)  The Initial Access Token and the Software Statement do quite different things and have different structures and properties.  The Initial Access Token is an opaque value that grants access to the registration resource.  A Software Statement is a non-opaque JWT security token that makes claims about the software being registered.  You can have one without the other or you can have both, depending upon the use case.

The parties that issue the two are also different.  The Initial Access Token is issued by and is about access to the Authorization Server.  The Software Statement is issued by the author of the Client, or a party cooperating with the author, and is about the Client.  Both their authorship and subject matter of the two data structures are different.

				-- Mike

-----Original Message-----
From: OAuth [mailto:[email-masked]] On Behalf Of Hannes Tschofenig
Sent: Thursday, June 05, 2014 12:42 AM
To: [email-masked]
Subject: [OAUTH-WG] draft-ietf-oauth-dyn-reg-17 review

Hi Justin, Hi Mike,

You write: "The following client metadata fields are defined by this specification. All client metadata fields are OPTIONAL."

I guess you mean "Optional to implement and optional to use.". Maybe it would be good to state that.

In the terminology section you briefly introduce a number of actors and concepts. The description for the initial access token and the software statement is somewhat short.

I am particularly interested to learn who issues the initial access token and the software statement? What is the purpose? What does it authorize?

I still don't fully get the idea of having both tokens (the initial access token and the software assertion). Stating who issues those might clarify it. If different parties provide different statements or grant different authorization rights based on these two "tokens" then I am happy but with the current write-up I feel that there is something missing.

Redirect URIs: The text says:
"It is RECOMMENDED that clients using these flows register this parameter, and an authorization server SHOULD require registration of valid redirect URIs for all clients that use these grant types to protect against token and credential theft attacks."

The security consideration section is equally weak:
"For clients that use redirect-based grant types such as authorization_code and implicit, authorization servers SHOULD require clients to register their redirect_uris in full."

Shouldn't the recommendation be a bit stronger particularly in light of the recently discussed covered redirect attack?

What happens if the client does not provide any redirect uris? I recommend to avoid the SHOULD because it is nothing a protocol specification can fulfill. It seems to be rather a policy issue. I think there should also be a description about "full" means here as well. For example, would the AS be expected to understand something like https://*.example.com?

MUST, MAY, SHOULDs: I think that the document still uses RFC 2119 language too excessively at places where it does not provide any guidance for protocol implementers. I would recommend to carefully re-read each MUST/MAY/SHOULD and judge whether it imposes any implementation specific requirements and if it doesn't to replace it with deployment recommendations instead. Also, if there is a SHOULD then it should be clear to the reader under what circumstances what action should be taken.

policy_uri: In my previous review I argued that the right terminology here is privacy notice and you can even re-use the IAPP terminology.
Unless the policy URI has nothing to do with privacy I would prefer this terminology change. If you disagree I would prefer to have a description about what policy means in this context.

jwks: my problem with the fuzzy description is that it is not indicated how the client (or any other party) would reference the listed keys and what these would be used for. Maybe this document is not the right place to define these JWKs if the semantic cannot be defined properly.

Regarding the 'software_id' definition. You write that the software_id is asserted by the client software but wouldn't it be more reasonable that some human (in an organization) asserts something rather than software. The software just acts on behalf of the human. Would it be reasonable to say that a client developer makes these assertions.

Regarding Section 4.2 client registration error response: Does a response message always contain two members, namely error and error_description? I would argue that the error member must be there but the error_description is optional.

Regarding the error values I am missing a value that allows the authorization server that a specific field has to be provided and is currently absent.

Ciao
Hannes

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Thu, 05 Jun 2014 22:28:45 +0300

BTW, I just spotted a problem with the example response at the bottom of
section 4.1, the HTTP status code should be 201 Created:

http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-17#section-4.1

Vladimir

---

From: Hannes Tschofenig <[email-masked]>
Date: Thu, 12 Jun 2014 09:50:27 +0200

Hi Phil,

thanks for your response. A few remarks below.

>> I am particularly interested to learn who issues the initial
>> access token and the software statement? What is the purpose? What
>> does it authorize?
> 
> These tokens have very different characteristics. The Software
> Statement is not a security token. It is a statement that locks the
> registration profile for client software and provides AS endpoints
> with a way to recognize client software since they do not have a
> client_id yet. In practical terms, AS endpoints can set policy to
> automatically approve reject based on specific statement, or content
> rules (software_id, version etc) or even approve based on the signer
> of the statements (e.g. allow registration for any client software
> statement signed by Cisco).

The software statement is hopefully signed and you are going to make
some security relevant decisions based on it. Whether you call it a
security token or not does not really matter that much.

> 
> Typically, the statement would be generated once (for all copies
> distributed) by the developer, publisher, or a collective
> organization.

I think it would be useful to add information about who creates it,
particularly since the document introduces these parties (at least the
client developer, and the software API publisher).

You might also expand a bit on what you mean by "generated once" to give
guidance on when a new software assertion needs to be generated vs. when
a previous one can be re-used.

>  This is particularly useful when the publisher of an
> API  is not the same organization as the deployers of the actual API
> endpoints following a common open API specification. For example,
> OpenID Connect would be one such example.

OpenID Connect would not have come to my mind here since OpenID connect
is neither a client developer nor a software API publisher (at least in
my understanding of the terminology defined in the dynamic client
registration document).

> 
> In the early OAuth1 and 2 days, most use cases had the API publisher
> and the deployer as the same organization. A client_id could be
> issued in advance and could be used as both credential id and
> software identifier.  In the evolving world, we have lots of cases
> (e.g. OpenID Connect) where the organization that defines the API
> specification is not the same as the one operating implementations of
> the API specification.  Client_id can’t serve both purposes.
> Software statement fills the gap allowing client software to use a
> client statement “claim” that can be “exchange” for a deployment
> assigned client_id.

I think that this would be useful background motivation for the draft; I
disagree with the mentioning of OpenID Connect based on my previous
comment.

> 
> Initial access token is a security token that allows the client to
> register in a closed/restricted registration endpoint where anonymous
> registration may not be allowed.  Useful in some environments where
> an IT organization might re-package a client for distribution on an
> internal or private system.
> 
> Where the software statement is issued by either the developer or the
> API specification organization, the initial access token is typically
> issued by the “domain” (or an organization affiliated with it) where
> the client intends to register.

Using the terminology from the dynamic client registration draft the
initial access token is issued by the "Deployment Organization". This
would be important information to add to the document!

Ciao
Hannes

---

From: Hannes Tschofenig <[email-masked]>
Date: Thu, 12 Jun 2014 09:52:48 +0200

One other small remark: I assume that a single software statement is
distributed to many OAuth clients whereas the initial access token is
only distributed to a single OAuth client. Is that correct? Is that the
envisioned relationship?

---

From: Hannes Tschofenig <[email-masked]>
Date: Thu, 12 Jun 2014 10:01:18 +0200

Hi Mike,

thanks for responding also to the question about dynamic client
registration.

I also believe it would be useful to add information in the draft about
the opaqueness nature of the different tokens, i.e., who is supposed to
read them.

From the current wording of the document my understanding was that the
OAuth client does not need to parse the initial access token nor the
software statement. It just relays it.

If the client indeed has to parse the software statement then it would
be good to know why this is done and what the client uses the
information for.

As mentioned in my review comments I think it would be helpful for the
reader to state who creates and distributes these tokens (as you and
Phil) have explained in the email. Put those thoughts into the document.

Ciao
Hannes

On 06/05/2014 09:18 PM, Mike Jones wrote:
> The answer to your question about the Initial Access Token and
> Software Statement is highly parallel to the answer to your question
> in the other thread about the Access Token and ID Token. :-)  The
> Initial Access Token and the Software Statement do quite different
> things and have different structures and properties.  The Initial
> Access Token is an opaque value that grants access to the
> registration resource.  A Software Statement is a non-opaque JWT
> security token that makes claims about the software being registered.
> You can have one without the other or you can have both, depending
> upon the use case.
> 
> The parties that issue the two are also different.  The Initial
> Access Token is issued by and is about access to the Authorization
> Server.  The Software Statement is issued by the author of the
> Client, or a party cooperating with the author, and is about the
> Client.  Both their authorship and subject matter of the two data
> structures are different.
> 
> -- Mike
> 
> -----Original Message----- From: OAuth
> [mailto:[email-masked]] On Behalf Of Hannes Tschofenig Sent:
> Thursday, June 05, 2014 12:42 AM To: [email-masked] Subject:
> [OAUTH-WG] draft-ietf-oauth-dyn-reg-17 review
> 
> Hi Justin, Hi Mike,
> 
> In the terminology section you briefly introduce a number of actors
> and concepts. The description for the initial access token and the
> software statement is somewhat short.
> 
> access token and the software assertion). Stating who issues those
> might clarify it. If different parties provide different statements
> or grant different authorization rights based on these two "tokens"
> then I am happy but with the current write-up I feel that there is
> something missing.
> 
> Redirect URIs: The text says: "It is RECOMMENDED that clients using
> these flows register this parameter, and an authorization server
> SHOULD require registration of valid redirect URIs for all clients
> that use these grant types to protect against token and credential
> theft attacks."
> 
> The security consideration section is equally weak: "For clients that
> use redirect-based grant types such as authorization_code and
> implicit, authorization servers SHOULD require clients to register
> their redirect_uris in full."
> 
> Shouldn't the recommendation be a bit stronger particularly in light
> of the recently discussed covered redirect attack?
> 
> specification can fulfill. It seems to be rather a policy issue. I
> think there should also be a description about "full" means here as
> well. For example, would the AS be expected to understand something
> like https://*.example.com?
> 
> with deployment recommendations instead. Also, if there is a SHOULD
> then it should be clear to the reader under what circumstances what
> action should be taken.
> 
> Unless the policy URI has nothing to do with privacy I would prefer
> this terminology change. If you disagree I would prefer to have a
> jwks: my problem with the fuzzy description is that it is not
> indicated how the client (or any other party) would reference the
> listed keys and what these would be used for. Maybe this document is
> not the right place to define these JWKs if the semantic cannot be
> defined properly.
> 
> Regarding the 'software_id' definition. You write that the
> software_id is asserted by the client software but wouldn't it be
> more reasonable that some human (in an organization) asserts
> something rather than software. The software just acts on behalf of
> the human. Would it be reasonable to say that a client developer
> makes these assertions.
> 
> error_description? I would argue that the error member must be there
> but the error_description is optional.
> 
> Ciao Hannes

---

From: Phil Hunt <[email-masked]>
Date: Thu, 12 Jun 2014 09:46:43 -0700

Hannes,

What I was attempting to describe regarding OpenID is an independent organization that controls an API. I think the problem with “publisher” may be that there is confusion between publishing the software vs. publishing the API specification.  Either is appropriate.

OpenID seemed like a good use case as an SDO working with OAuth. However, I don’t want to imply that OIDF needs to start issuing assertions. I did want to underline how this is beneficial to AS deployments of the Connect specs.  The main idea being that administrators can configure policy that says we can now accept any registration signed by OIDF that claims to be a client for Connect.  This means that AS end-points now have prior state to recognize any OIDF Connect client that knocks at the door.  In this sense, it replaces the client_id manual registration model of the past…..

See if this line of thought makes better sense of an explanation. I can work up some text for the draft if people agree.

One important aspect is that the use of software statements reverse the issuing pattern of client_id but initially serve a similar function in recognizing clients.  In 6749, Section 2.2 describes the client identifier: 
   The authorization server issues the registered client a client
   identifier - a unique string representing the registration
   information provided by the client.  The client identifier is not a
   secret; it is exposed to the resource owner, and MUST NOT be used
   alone for client authentication.  The client identifier is unique to
   the authorization server.

The software_statement replaces the client_id during the initial interaction (the registration flow) so that it may be exchanged for an individualized client_id assigned by the AS. By being signed, it enables a federated model where policy decisions can be made about the third-party statement. E.g. Is the software, the organization, the signer approved for use at this AS? Remember also, during the registration flow, we are not authenticating clients we are “registering” them.  There’s no infinite proof of existence claimed here.  8-)

Developers can also self-sign, but the functional characteristic is much more like what people do with (and the term escapes me), self-generated ssl tokens where public keys are exchanged on a pair-wise basis to do mutual-TLS.

On a security considerations front, statements hold the same characteristics/risks of the original “public" client_id, except they are issued externally to the AS. Because they are more than a simple identifier, they have some advantage from a policy management perspective because they do not always require a prior registration record within the AS.  It is the act of “registering” the software and generating a client_id that creates the confidential client in this case.

Is something along these lines a better way to explain this? I can take a shot and try to address the concerns. 

I’m worried, I’m going in circles on this. Maybe there is a better approach?

Phil

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

---

From: Phil Hunt <[email-masked]>
Date: Thu, 12 Jun 2014 09:51:58 -0700

I don’t think so. All copies of a client may carry the same statement.

Special distributions of a client intended for use in a specific domain may be packaged with an initial access token.  So a subset of every client may have the token.

All clients registering within a secure domain would have both statement and initial access token.

Other clients registering in other domains may or may not have initial access tokens.

A good example of this, many IT orgs take software from people like Cisco and embed special keys etc in a private distribution.  When the software installs it is pre-configured with keys and config to work only within the IT orgs domain.  I think this is the model Justin was looking for.

If a single client instance could have a unique initial access token already issued, we probably wouldn’t need dynamic registration.  8-)

Phil

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

---

From: Phil Hunt <[email-masked]>
Date: Thu, 12 Jun 2014 10:06:50 -0700

Hannes,

I should also add one security consideration.

If a server believes it is receiving a registration request from a client sharing the same software_id and software_version as another client that uses an assertion, the server should find the registration suspect. It is likely the client is attempting to change things like redirect_uri’s.  

The point of a software statement is to lock all copies of a client to behave the same way under the same registration profile.

Phil

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