Subject: [scim] Ben Campbell's Discuss on draft-ietf-scim-api-18: (with DISCUSS and COMMENT)

From: "Ben Campbell" <[email-masked]>
Date: Tue, 12 May 2015 19:35:01 -0700

Ben Campbell has entered the following ballot position for
draft-ietf-scim-api-18: Discuss

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-scim-api/

----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

-- 3.4.2: "SHOULD ignore any query parameters they do not understand"

I'm curious why this is not a MUST. What are the alternatives--that is,
can you envision situations where it might be reasonable to _not_ ignore
parameters you don't understand?

-- 3.4.2.2, reference to [Order-Operations]

As written, that needs to be a normative reference. That's problematic
for a reference to wikipedia, since articles are extremely changeable.
Furthermore, the referenced article doesn’t indicate one true operator
precedence for programming languages. If the rest of the paragraph fully
defines the precedence, I suggest saying “MUST… according to the
following”, and making the reference truly informational (or even
dropping it entirely.)

-- 3.8:

The first paragraph says servers MUST respond with JSON in UTF-8. But the
following paragraphs talk about how the client may request different
response formats. This seems contradictory.

-- 3.13:

It's optional (MAY) to include the API version. If the version is
missing, the service provider SHOULD perform the operation using the most
recent supported version. This seems to allow the client and service
provider to disagree on the version being used. Does this cause an
interop problem if the later version is not backwards compatible? (Are
all new versions expected to be backwards compatible with old versions?)

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

-- General: There seems to be a pervasive use of 2119 keywords in ways
that seem like statements of fact, rather than normative requirements.
This is especially true with MAY, where it seems like people may have
gotten into the habit of capitalizing every occurrence of the word. I've
called out a number of instances below, but probably didn't catch them
all.

-- 1.3, 3rd paragraph:

The paragraph is indented as if part of the definition of "Base URI". I
suspect that is not the intent.

"It is expected that SCIM servers MAY...": Is the normative MAY
intentional? It's odd to see a 2119 keyword following a phrase like "It
is expected..."

-- 2, Basic Authentication:

"Implementers SHOULD combine the use of basic authentication with other
factors": Do you mean that they SHOULD NOT use basic _without_ combining
it with other factors? If so, that is subtly different than the text as
written.

-- 2.1, last paragraph:

Just SHOULD? Do you invision situations where it might be reasonable
_not_ to take the threats into account?

Also, the reference to oath-assertions needs to be normative

-- 2.2, "... it MAY be acceptable"

This seems more a statement of fact than a normative assertion.

-- 3.1, 2nd paragraph "... a JSON object that MAY be created...", "in
cases where SCIM MAY be used...", "reasonable to expect that some service
providers MAY only support"

s/MAY/may

-- 3.1, 3rd paragraph:

"... implementations MAY vary": Should not be normative.
"... techniques such as document validation...are not recommended.":
Maybe that one _should_ be normative.
"... a SCIM client SHOULD NOT expect...": Probably should not be
normative. (But if it really is intended as normative, when might a
client reasonably choose to violate it?)

-- 3.3, 3rd bullet:

How does a service provider know which attributes a client understands?

-- 3.4.2, totalResults: "... SHALL NOT be equal..."

Never? Is it never possible that all results fit into one "page"? Perhaps
this should have been a non-normative "might not be equal"?

-- 3.4.1.2, paragraph starting with "A query against a server root..."

What is the significance of "ALL" in caps?

-- 3.4.2.2, "... the the resource MUST match if any of the instances of
the given attribute match the specified criterion..."

That seems like a statement of fact. (e.g. "the resource matches if..."

-- 3.4.2.4, 1st paragraph: "clients SHOULD never
   assume repeatable results"
   
   That seems like a statement of fact, not a normative assertion.
   
-- 3.5.1, 1st paragraph:

"Clients that MAY have..." : s/MAY/may

-- table 8, tooMany: "... MAY not be acceptable..."

As worded, that sounds like a statement of fact.

-- 7.3:

That needs to be a normative reference. Also, why is this a SHOULD? Can
you envision scenarios where it might be reasonable for implementors NOT
to take the countermeasures into account?

-- 7.4:

Reference to oauth-assertions needs to be normative.

-- 7.6, 2nd bullet

s/MAY/may

-- editorial

-- 2, HOBA paragraph:

Is this intended as part of the TLS Client Authentication entry? It
doesn't seem so, but the paragraph lacks its own heading.

3.2, 1st paragraph, sentence starting with "Given there are cases..."

Sentence fragment.

-- 3.3, first two bullet list entries

The "For" at the beginning of both entries does not fit the rest of the
sentence structure.

---

From: Phil Hunt <[email-masked]>
Date: Tue, 12 May 2015 21:45:56 -0700

Ben,

Thanks for the extensive comments.  If I have not commented below, please assume I am agreeing and will make the change.

Phil

[email-masked]

> On May 12, 2015, at 7:35 PM, Ben Campbell <[email-masked]> wrote:
> 

The currently unstated opposite is that a server might choose to reject the request. I believe the preference is for servers to ignore what they do not understand for upward compatibility reasons.  MUST ignore seems to harsh.

> response formats. This seems contradictory.

I will adjust. I think some service providers may wish to support other formats. I don’t think it is our intent to limit here, just that other formats are beyond scope.
> all new versions expected to be backwards compatible with old versions?)

See previous comment on ignoring what is not understood. My understanding this is one of those common practices that goes underspecified. Happy to take suggestions here.

> suspect that is not the intent.

This one could go either way. I will set it outside the list.
> is expected…"
I’m not sure what you are referring to.  paragraph 1 of 2.1 refers to section 6 of the OAuth Assertions Draft.  The last paragraph does not refer to it.
> How does a service provider know which attributes a client understands?

This was a compromise resolution to a problem in REST that the WG ran into. What does it mean when a client does not assert a value? Is it the intention that the client wants the value cleared (by not asserting it), is the client saying nothing, or does the client expect it to be defaulted.

Then there is the issue that access control might be filtering what the client can set or in the response, what can be returned to the client. In other words, the client may not be intending to clear a value because it may not even know about the attribute.

I’ve never been happy with the proposed paragraph and would invite alternate proposals.
> this should have been a non-normative "might not be equal”?

Agreed
> 
> -- 3.4.1.2, paragraph starting with "A query against a server root…"
> 

We really really mean all.  :-)

Will make it lower case.  
> That seems like a statement of fact. (e.g. "the resource matches if…"

Agreed. It is awkward. I will rephrase.
>   That seems like a statement of fact, not a normative assertion.

Not sure I agree.  It is normative in that clients must be prepared to handle inconsistent results during paging.  Maybe we can rephrase around the issue?

> to take the countermeasures into account?

Well they might not be using OAuth tokens.

My understanding since OAuth is optional, it should not be a normative reference.  Also, the assertions draft is a work in progress.
> Reference to oauth-assertions needs to be normative.

Again, OAuth is optional. 

Regarding all of the authentication methods described, since they are all optional I have made them all informative unless every implementation MUST support it (e.g. because SCIM depends on it).

Correct me if this is editorially incorrect.

> doesn't seem so, but the paragraph lacks its own heading.

My thinking was it is a profile/variation of TLS client authentication. IOW the only thing that is different is how the keys are managed/distributed.

I am open to calling it out as a separate item.
> 3.2, 1st paragraph, sentence starting with "Given there are cases..."

Agreed. Will rephrase.
> The "For" at the beginning of both entries does not fit the rest of the

Will rephrase.

---

From: "Ben Campbell" <[email-masked]>
Date: Wed, 13 May 2015 00:22:17 -0500

Thanks for the quick response. I am okay with your responses to all the 
DISCUSS points save the last, and I am only holding that one for a bit 
more discussion. (That is, I will probably clear regardless of your 
response.)

Details inline. I deleted sections that did not appear to need further 
discussion.

On 12 May 2015, at 23:45, Phil Hunt wrote:

> Ben,
>
> Thanks for the extensive comments.  If I have not commented below, 
> please assume I am agreeing and will make the change.
>
> Phil
>
> [email-masked]
>
>> Please refer to 
>> https://www.ietf.org/iesg/statement/discuss-criteria.html
> The currently unstated opposite is that a server might choose to 
> reject the request. I believe the preference is for servers to ignore 
> what they do not understand for upward compatibility reasons.  MUST 
> ignore seems to harsh.

Okay, that makes sense. Some guidance to that effect would be helpful, 
but I won't hold the discuss on that.

[...]

> I will adjust. I think some service providers may wish to support 
> other formats. I don’t think it is our intent to limit here, just 
> that other formats are beyond scope.

Okay

> See previous comment on ignoring what is not understood. My 
> understanding this is one of those common practices that goes 
> underspecified. Happy to take suggestions here.

I think this is different than in the previous comment. If a certain 
combination of method and attributes means something different in 
version N and version N+1, and the client and server leaves out the 
version, thinks could break. My suggestion would be to always include 
the version--but I understand there might be other reasons not to. An 
alternative would be to give guidance about backwards compatibility. 
(Even non-normative guidance in the form of "if you do this things might 
break" would help.)

[...]

> I’m not sure what you are referring to.  paragraph 1 of 2.1 refers 
> to section 6 of the OAuth Assertions Draft.  The last paragraph does 
> not refer to it.
>>

Are we looking at the same version (18)? I see the last paragraph of 2.1 
as the following:

"Implementers SHOULD take into account the threats and 
countermeasuresdocumented in the security considerations for the use of 
clientauthorizations see Section 8 of [I-D.ietf-oauth-assertions]."

[...]

> This was a compromise resolution to a problem in REST that the WG ran 
> into. What does it mean when a client does not assert a value? Is it 
> the intention that the client wants the value cleared (by not 
> asserting it), is the client saying nothing, or does the client expect 
> it to be defaulted.
>
> Then there is the issue that access control might be filtering what 
> the client can set or in the response, what can be returned to the 
> client. In other words, the client may not be intending to clear a 
> value because it may not even know about the attribute.
>

The "client has access to" part is easier to understand, since the 
service provider presumably knows what attributes it sent, or will send, 
to the client. Would it make sense to just delete the phrase ", or 
understands,"?

[...]
> Not sure I agree.  It is normative in that clients must be prepared to 
> handle inconsistent results during paging.  Maybe we can rephrase 
> around the issue?
>

How about "clients MUST be prepared to handle inconsistent results..." 
:-)

[...]

> My understanding since OAuth is optional, it should not be a normative 
> reference.

Even if a feature is optional, a reference that is needed to understand 
and/or implement the feature should still be normative.

> Also, the assertions draft is a work in progress.

I understand that is an issue, but it's not appropriate (or even 
beneficial) to avoid a normative reference due to a dependency block. 
The whole point of that bit of inconvenience is to make sure an RFC 
doesn't depend on a moving target in order for a feature to be 
understood or implemented.

> Regarding all of the authentication methods described, since they are 
> all optional I have made them all informative unless every 
> implementation MUST support it (e.g. because SCIM depends on it).
>

IMHO, it is editorially incorrect. Please see my previous comments on 
7.3. But in any case, I am not holding a discuss on these points--I will 
leave it to Barry to decide how to proceed.

> My thinking was it is a profile/variation of TLS client 
> authentication. IOW the only thing that is different is how the keys 
> are managed/distributed.
>

That's okay with me if it was the intent.

[...]

---

From: Phil Hunt <[email-masked]>
Date: Thu, 14 May 2015 11:37:10 -0700

Regarding Ben’s items below on versioning, I think we need more discussion:
> I think this is different than in the previous comment. If a certain combination of method and attributes means something different in version N and version N+1, and the client and server leaves out the version, thinks could break. My suggestion would be to always include the version--but I understand there might be other reasons not to. An alternative would be to give guidance about backwards compatibility. (Even non-normative guidance in the form of "if you do this things might break" would help.)

I do agree that this section is covering the issue of versioning somewhat superficially. 

The text for this section is fairly old and my understanding is it represents some of the original SCIM 1 consensus. 

My personal worry is I would not want to discourage updates by encouraging lock-in to specific versions. Better to “break” clients and have them update or re-configure for a specific version.  I think this is mediated by the fact that most cloud providers all have methodologies capable of delivering rapid and frequent client updates.

From a protocol perspective, the WG has used “robust” processing principles that require implementations to more be flexible in what is accepted while strict on fundamentals (e.g. JSON must be valid). For example, in an earlier thread we talked about how servers SHOULD ignore search parameters they do not understand.  Further, errors are not supposed to be thrown due to attributes that are not defined - they are merely ignored. 

I think SCIM's design principles should aid implementers in avoiding many of the backwards compatibility issues we might otherwise experience.

Never-the-less, maybe we need some cautionary text that deployers need to consider ramification of breaking changes in the default version? They need to have an appropriate method for co-ordinating breaking updates and transition where possible.

Thanks,

Phil

[email-masked]

> On May 12, 2015, at 10:22 PM, Ben Campbell <[email-masked]> wrote:
> 
> Thanks for the quick response. I am okay with your responses to all the DISCUSS points save the last, and I am only holding that one for a bit more discussion. (That is, I will probably clear regardless of your response.)
> 
> Details inline. I deleted sections that did not appear to need further discussion.
> 
> Okay, that makes sense. Some guidance to that effect would be helpful, but I won't hold the discuss on that.
>> 
> 
> [...]
> 
>>> 
>>> -- 3.8:
>>> 
> I think this is different than in the previous comment. If a certain combination of method and attributes means something different in version N and version N+1, and the client and server leaves out the version, thinks could break. My suggestion would be to always include the version--but I understand there might be other reasons not to. An alternative would be to give guidance about backwards compatibility. (Even non-normative guidance in the form of "if you do this things might break" would help.)
> 
>>> 
>>> 
> Are we looking at the same version (18)? I see the last paragraph of 2.1 as the following:
> 
> "Implementers SHOULD take into account the threats and countermeasuresdocumented in the security considerations for the use of clientauthorizations see Section 8 of [I-D.ietf-oauth-assertions]."
> 
> 
> [...]
> 
>>> -- 3.3, 3rd bullet:
>>> 
> The "client has access to" part is easier to understand, since the service provider presumably knows what attributes it sent, or will send, to the client. Would it make sense to just delete the phrase ", or understands,"?
> 
> [...]
>>> 
> How about "clients MUST be prepared to handle inconsistent results..." :-)
> 
> [...]
> 
>>> 
>>> -- 7.3:
>>> 
>> My understanding since OAuth is optional, it should not be a normative reference.
> 
> Even if a feature is optional, a reference that is needed to understand and/or implement the feature should still be normative.
> 
> I understand that is an issue, but it's not appropriate (or even beneficial) to avoid a normative reference due to a dependency block. The whole point of that bit of inconvenience is to make sure an RFC doesn't depend on a moving target in order for a feature to be understood or implemented.
> 
>>> 
>>> -- 7.4:
>>> 
> IMHO, it is editorially incorrect. Please see my previous comments on 7.3. But in any case, I am not holding a discuss on these points--I will leave it to Barry to decide how to proceed.
> 
>> 
>>> 
>>> -- 7.6, 2nd bullet
>>> 
>>> s/MAY/may
>>> 
>>> -- editorial
>>> 
>>> -- 2, HOBA paragraph:
>>>

---

From: Phil Hunt <[email-masked]>
Date: Thu, 14 May 2015 11:53:59 -0700

Barry,

Following up on more of Ben’s comments. Ben has suggested many of the authentication references need to be normative. Many of these references are works-in-progress and I wouldn’t want to hold SCIM up with so many references pending.

My feeling is that these were added to the specification as supplementary information on how clients can be authenticated and these are really just part of best practices around HTTP.  While arguably version useful, very little of the authentication section is SCIM specific (that would not apply to any other HTTP app). 

We might choose to make certain references normative if SCIM has a normative requirement of a specific method. For example, for OAuth Bearer tokens we say:
> Bearer tokens [RFC6750] MAY be used when combined with TLS and a
>       token framework such as OAuth 2.0 [RFC6749].  Tokens that are
>       issued based on weak or no authentication of authorizing users
>       and/or OAuth clients SHOULD NOT be used.

Even so in this text, we are talking about an operational security consideration and not a protocol or implementation requirement.

Phil

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

---

From: "Ben Campbell" <[email-masked]>
Date: Thu, 14 May 2015 15:48:09 -0500

For the record, I'm clearing the DISCUSS on the version question, and 
moving it to a comment. I only held the discuss to make sure it got 
discussed, and that appears to be happening. If the answer comes back as 
"it's right as is", I'm okay with that.

Thanks!

Ben.

On 14 May 2015, at 13:37, Phil Hunt wrote:

>> (Even non-normative guidance in the form of "if you do this things 
>> might break" would help.)
>
> The text for this section is fairly old and my understanding is it 
> represents some of the original SCIM 1 consensus.
>
> My personal worry is I would not want to discourage updates by 
> encouraging lock-in to specific versions. Better to “break” 
> clients and have them update or re-configure for a specific version.  
> I think this is mediated by the fact that most cloud providers all 
> have methodologies capable of delivering rapid and frequent client 
> updates.
>
> From a protocol perspective, the WG has used “robust” processing 
> principles that require implementations to more be flexible in what is 
> accepted while strict on fundamentals (e.g. JSON must be valid). For 
> example, in an earlier thread we talked about how servers SHOULD 
> ignore search parameters they do not understand.  Further, errors are 
> not supposed to be thrown due to attributes that are not defined - 
> they are merely ignored.
>
> I think SCIM's design principles should aid implementers in avoiding 
> many of the backwards compatibility issues we might otherwise 
> experience.
>
> Never-the-less, maybe we need some cautionary text that deployers need 
> to consider ramification of breaking changes in the default version? 
> They need to have an appropriate method for co-ordinating breaking 
> updates and transition where possible.
>
> Thanks,
>
> Phil
>
> [email-masked]
>
>> Thanks for the quick response. I am okay with your responses to all 
>> the DISCUSS points save the last, and I am only holding that one for 
>> a bit more discussion. (That is, I will probably clear regardless of 
>> your response.)
>>
>>> reject the request. I believe the preference is for servers to 
>>> ignore what they do not understand for upward compatibility reasons. 
>>>  MUST ignore seems to harsh.
>>
>> Okay, that makes sense. Some guidance to that effect would be 
>> helpful, but I won't hold the discuss on that.
>>>
>>
>> [...]
>>
>>>>
>>>> -- 3.8:
>>>>
>> (Even non-normative guidance in the form of "if you do this things 
>> might break" would help.)
>>
>>>>
>>>>
>> countermeasuresdocumented in the security considerations for the use 
>> of clientauthorizations see Section 8 of 
>> [I-D.ietf-oauth-assertions]."
>>
>>
>> [...]
>>
>>>> -- 3.3, 3rd bullet:
>>>>
>>> This was a compromise resolution to a problem in REST that the WG 
>>> ran into. What does it mean when a client does not assert a value? 
>>> Is it the intention that the client wants the value cleared (by not 
>>> asserting it), is the client saying nothing, or does the client 
>>> expect it to be defaulted.
>>>
>> service provider presumably knows what attributes it sent, or will 
>> send, to the client. Would it make sense to just delete the phrase ", 
>> or understands,"?
>>
>> [...]
>>>>
>>> Not sure I agree.  It is normative in that clients must be prepared 
>>> to handle inconsistent results during paging.  Maybe we can rephrase 
>>> around the issue?
>>>
>>
>> Even if a feature is optional, a reference that is needed to 
>> understand and/or implement the feature should still be normative.
>>
>>> Regarding all of the authentication methods described, since they 
>>> are all optional I have made them all informative unless every 
>> 7.3. But in any case, I am not holding a discuss on these points--I 
>> will leave it to Barry to decide how to proceed.
>>
>>>
>>>>
>>>> -- 7.6, 2nd bullet
>>>>
>>>> s/MAY/may
>>>>
>>>> -- editorial
>>>>
>>>> -- 2, HOBA paragraph:
>>>>

---

From: Phil Hunt <[email-masked]>
Date: Thu, 14 May 2015 13:53:57 -0700

Thanks Ben.

It was definitely good to bring up. 

I would like to encourage others to comment if they would like to revise the versioning section.

In the absence of further comment, I will assume we are clear on this item.

Phil

[email-masked]

> On May 14, 2015, at 1:48 PM, Ben Campbell <[email-masked]> wrote:
> 
> For the record, I'm clearing the DISCUSS on the version question, and moving it to a comment. I only held the discuss to make sure it got discussed, and that appears to be happening. If the answer comes back as "it's right as is", I'm okay with that.
> 
> Thanks!
> 
> Ben.
> 
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim