Subject: [scim] Comments so sections 1 through 3.3

From: Ian Glazer <[email-masked]>
Date: Mon, 14 Jul 2014 11:00:07 -0700

Here are my early comments on the above sections. I'll grind through more
of this a bit later.

1.1 - "identity service providers and client" - This is a little confusing.
Do we mean identity providers and consumers? providers of identity services
and organizations that consume those services?

1.3 - URL versus URI - There might be a bit of a inconsistency here.

2. - The section is titled "Authentication and Authorization" but
authorization isn't directly addressed. The sentence "Appropriate security
considerations of the selected authentication and authorization schemes
SHOULD be taken" isn't actionable - it is a motherhood and apple pie
statement. Do we want to specifically mention scopes as an authorization
mechanism? Do we just want to cut "Authorization" from the section header?

3. API - Did we decided whether SCIM is an API or a protocol? For
consistency-sake, the title of this section and the first sentence may need
to change accordingly.

3. POST - "or bulk modify resources" - Bulk? I thought that bulk was off
the table for this draft?

3. PUT - The draft reads "PUT SHOULD NOT be used to create new resources."
Should that SHOULD actually be a MUST?

3. API Table - minor nit - only some of the sections are properly linked in
the PDF

3. API Table - /Bulk - I thought we weren't dealing with Bulk for v2 and
were going to handle it via profile later

3.1 - "Successful resource creation..." - It is unclear from the second
sentence whether the entire object MUST be returned or can the server
simply return back a pointer to the newly created object?

3.1 - Is the server required to return a Location header when a resource is
successfully created? Text does not make that clear.

3.1.1. - Just a clarification - "SHALL be set by the service provider" - in
this case service provider means SCIM server and not the client, is that
correct?

3.2 Consistency question - Query or Search?

3.2.2 Consistency question - it appears that this draft refers to "service
providers," "Providers," and "servers" - does this need to be cleaned up
and made consistent?

3.2.2.1 - Do we really want to allow a search against the server root that
would result is all objects being returned? Seems like we ought to endorse
a pattern of querying resourceTypes and then a specific resourceType is a
better way to go.

3.2.2.2 - What happens if someone includes a "ge" search against a
non-numeric or non-date type field? The next isn't clear about a failure
condition.

3.2.2.3 - Primary attributed - it isn't clear from the text what a primary
attribute is.

3.2.2.5 - Meta-question - how does a SCIM server indicate whether it
supports attributes and excludedAttributes to be returned (or not) for a
Query?

3.2.3 - Figure 2 - the example doesn't use a meta.resourceType attribute
which I think it should to indicate a best practice.

3.3.1 - HTTP PUT "SHOULD NOT" or "MUST NOT" be used to create new resources?

3.3.1 - "If an attribute is required..." - What if the attribute's value
isn't going to change? Does it still need to be sent along?

3.3.1 - "Attributes whose mutability is 'readWrite.' This paragraph seem
very squishy. The server is afforded a lot of latitude which the client may
not be aware of. Should be more prescriptive? Attributes that are omitted
are not changed?

3.3.2.1 - I'd move the paragraph before the example up before the list of
possible outcomes.

3.3.2.2 - I get what happens here but there could be confusion as to
whether Remove sets a value to "null" or not. Is removing an attribute
equivalent to nulling it?

3.3.2.2 - What about mutability? If I attempt to remove a readOnly, can I?
What about "required" attributes?

3.3.2.3 - What about mutability?

-- 
Ian Glazer
Senior Director, Identity
+1 202 255 3166
@iglazer <https://twitter.com/iglazer>

---

From: Phil Hunt <[email-masked]>
Date: Mon, 14 Jul 2014 15:54:31 -0700

Ian

Thanks for all the comments! I will look at in more detail when I get back from vacation. 

Regarding protocol vs api, the advice I received was we should call this a protocol as api is associate with programming not over the wire semantics. 

Only real issue is the name of the document itself. This will be one of the issues to sort out in Toronto for sure!

Thanks again! 

Phil

> On Jul 14, 2014, at 11:00, Ian Glazer <[email-masked]> wrote:
> 
> Here are my early comments on the above sections. I'll grind through more of this a bit later.
> 
> 1.1 - "identity service providers and client" - This is a little confusing. Do we mean identity providers and consumers? providers of identity services and organizations that consume those services?
> 
> 2. - The section is titled "Authentication and Authorization" but authorization isn't directly addressed. The sentence "Appropriate security considerations of the selected authentication and authorization schemes SHOULD be taken" isn't actionable - it is a motherhood and apple pie statement. Do we want to specifically mention scopes as an authorization mechanism? Do we just want to cut "Authorization" from the section header?
> 
> 3. API - Did we decided whether SCIM is an API or a protocol? For consistency-sake, the title of this section and the first sentence may need to change accordingly.
> 
> 3. POST - "or bulk modify resources" - Bulk? I thought that bulk was off the table for this draft?
> 
> 3. PUT - The draft reads "PUT SHOULD NOT be used to create new resources." Should that SHOULD actually be a MUST?
> 
> 3. API Table - minor nit - only some of the sections are properly linked in the PDF
> 
> 3. API Table - /Bulk - I thought we weren't dealing with Bulk for v2 and were going to handle it via profile later
> 
> 3.1 - "Successful resource creation..." - It is unclear from the second sentence whether the entire object MUST be returned or can the server simply return back a pointer to the newly created object?
> 
> 3.1 - Is the server required to return a Location header when a resource is successfully created? Text does not make that clear.
> 
> 3.1.1. - Just a clarification - "SHALL be set by the service provider" - in this case service provider means SCIM server and not the client, is that correct?
> 
> 3.2.2 Consistency question - it appears that this draft refers to "service providers," "Providers," and "servers" - does this need to be cleaned up and made consistent?
> 
> 3.2.2.1 - Do we really want to allow a search against the server root that would result is all objects being returned? Seems like we ought to endorse a pattern of querying resourceTypes and then a specific resourceType is a better way to go.
> 
> 3.2.2.2 - What happens if someone includes a "ge" search against a non-numeric or non-date type field? The next isn't clear about a failure condition.
> 
> 3.2.2.3 - Primary attributed - it isn't clear from the text what a primary attribute is.
> 
> 3.2.2.5 - Meta-question - how does a SCIM server indicate whether it supports attributes and excludedAttributes to be returned (or not) for a Query?
> 
> 3.2.3 - Figure 2 - the example doesn't use a meta.resourceType attribute which I think it should to indicate a best practice.
> 
> 3.3.1 - "If an attribute is required..." - What if the attribute's value isn't going to change? Does it still need to be sent along?
> 
> 3.3.1 - "Attributes whose mutability is 'readWrite.' This paragraph seem very squishy. The server is afforded a lot of latitude which the client may not be aware of. Should be more prescriptive? Attributes that are omitted are not changed?
> 
> 3.3.2.1 - I'd move the paragraph before the example up before the list of possible outcomes.
> 
> 3.3.2.2 - I get what happens here but there could be confusion as to whether Remove sets a value to "null" or not. Is removing an attribute equivalent to nulling it?
> 
> 3.3.2.2 - What about mutability? If I attempt to remove a readOnly, can I? What about "required" attributes?
> 
> @iglazer
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim

---

From: Phil Hunt <[email-masked]>
Date: Thu, 17 Jul 2014 16:46:48 -0700

Ian,

Thanks for the thorough walk through.

Comments in line below.

Thanks for the feedback. Many of these are obvious and will plan to put them in the document following Toronto (unless I hear objections). Others I will add to the list of discussion items for Toronto.

Phil

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

> 1.1 - "identity service providers and client" - This is a little confusing. Do we mean identity providers and consumers? providers of identity services and organizations that consume those services?

How about just “web service providers and clients”.  The fact that it is a protocol around identity isn’t near as important as that it is an HTTP protocol.
> 1.3 - URL versus URI - There might be a bit of a inconsistency here.

Will Fix. I think the issue here is that it must be a URL (accessible via HTTP) but IETF seems to always want URIs regardless.  
> 2. - The section is titled "Authentication and Authorization" but authorization isn't directly addressed. The sentence "Appropriate security considerations of the selected authentication and author…

I have already attempted to create a better way of describing this:
   Because SCIM uses HTTP protocol, it does not define a scheme for
   authentication and authorization.  It depends on standard HTTP
   authentication schemes.  It is RECOMMENDED that clients be
   implemented in such a way that new authentication schemes can be
   deployed.  Implementers SHOULD support existing authentication/
   authorization schemes.  In particular, OAuth2 [RFC6750] is
   RECOMMENDED.  Appropriate security considerations of the selected
   authentication and authorization schemes SHOULD be taken.  Because
   this protocol uses HTTP response status codes as the primary means of
   reporting the result of a request, servers are advised to respond to
   unauthorized or unauthenticated requests using the 401 response code
   in accordance with Section 3.1 of [RFC7235].

   All examples show an OAuth2 bearer token [RFC6750] (thought it is not
   required) ; e.g.,

   GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
   Host: example.com
   Authorization: Bearer h480djs93hd8

   The context of the request (i.e. the user for whom data is being
   requested) MUST be inferred by service providers.
That said, do we want to get into a standardized authorization model?  Maybe this is something as a future draft specification. Particularly if we want to talk about a future SCIM Directory specification.

> 3. API - Did we decided whether SCIM is an API or a protocol? For consistency-sake, the title of this section and the first sentence may need to change accordingly.

Per my previous email. I’ve had some recommendation that API always refers to a programming library interface rather than over the wire semantics. Thus I have begun changing to the SCIM protocol or SCIM HTTP protocol where appropriate.

Note we need to discuss the issue of renaming the SCIM API draft to SCIM Protocol draft.
> 3. POST - "or bulk modify resources" - Bulk? I thought that bulk was off the table for this draft?

There was some discussion on one of the calls (I can’t remember if we followed up on the list). The feeling was that many are beginning to implement now. We’d like to keep it in place for now but we agreed it may not make the final cut.  This should be a discussion item for Toronto.
> 3. PUT - The draft reads "PUT SHOULD NOT be used to create new resources." Should that SHOULD actually be a MUST?

I’m open to some discussion here. I’m not sure if there are limited scenarios whereby the implementation has to allow this.
> 3. API Table - minor nit - only some of the sections are properly linked in the PDF

Ok. Weird. Will take a look. Seems like an xml2rfc issue (the xml references the same way for each item).
> 3. API Table - /Bulk - I thought we weren't dealing with Bulk for v2 and were going to handle it via profile later
See above
> 3.1 - "Successful resource creation..." - It is unclear from the second sentence whether the entire object MUST be returned or can the server simply return back a pointer to the newly created objec…
Assume you are referring to:
Upon successful creation, the response body MUST
   contain the newly created resource.

Maybe it should say “the newly created service provider representation of the full resource”?
> 3.1 - Is the server required to return a Location header when a resource is successfully created? Text does not make that clear.

Agreed it should say this.
> 3.1.1. - Just a clarification - "SHALL be set by the service provider" - in this case service provider means SCIM server and not the client, is that correct?

In all cases “service provider” means the HTTP service, not the provider of identity data (the client). Maybe we need more terminology text in the intro on this point.
> 3.2 Consistency question - Query or Search?

Agreed. Any preferences?
> 3.2.2 Consistency question - it appears that this draft refers to "service providers," "Providers," and "servers" - does this need to be cleaned up and made consistent?

Agreed see above.
> 3.2.2.1 - Do we really want to allow a search against the server root that would result is all objects being returned? Seems like we ought to endorse a pattern of querying resourceTypes and then a…

This is regulated by the max results limits. There was a specific example of being able to search without regard to resource type, or a specific set of resource types. The use case was a search-as-user-types scenario where the result was not known to be a user or a group.
> 3.2.2.2 - What happens if someone includes a "ge" search against a non-numeric or non-date type field? The next isn't clear about a failure condition.
Maybe you mis-read. If anything, I see it doesn’t say how numeric comparisons are made. For strings it is the normal lexicographical comparison.
> 3.2.2.3 - Primary attributed - it isn't clear from the text what a primary attribute is.

Will add a reference to the multi-valued attribute definition where primary is defined.
> 3.2.2.5 - Meta-question - how does a SCIM server indicate whether it supports attributes and excludedAttributes to be returned (or not) for a Query?

Not sure what you mean. There’s no optionality here.
> 3.2.3 - Figure 2 - the example doesn't use a meta.resourceType attribute which I think it should to indicate a best practice.

Sure. Why not.  Might be a good way to say how to search both users and groups.
> 3.3.1 - HTTP PUT "SHOULD NOT" or "MUST NOT" be used to create new resources?

See above.
> 3.3.1 - "If an attribute is required..." - What if the attribute's value isn't going to change? Does it still need to be sent along?

Yes. Since it is a replace, but value must always be supplied - even when no change. Otherwise it makes missing value logic even more complex. :-)

> 3.3.1 - "Attributes whose mutability is 'readWrite.' This paragraph seem very squishy. The server is afforded a lot of latitude which the client may not be aware of. Should be more prescriptive? At…

The problem here was the issue I raised earlier about understanding the implied meaning of a missing value:
* omitted because client isn’t aware of it
* omitted because the client does not intend to change it
* omitted because the client wants to default it
* omitted because the client wants to delete it
* omitted because the client doesn’t care

The squishiness was a result of trying to give the server some room to interpret.

This probably still needs more discussion.
> 3.3.2.1 - I'd move the paragraph before the example up before the list of possible outcomes.
ok
> 3.3.2.2 - I get what happens here but there could be confusion as to whether Remove sets a value to "null" or not. Is removing an attribute equivalent to nulling it?

I think we’ve informally discussed that for scim, null == removed. We should discuss this in Toronto and formalize this in the spec.  Having null equal to removed makes the missing/omitted attribute logic on PUT etc easier to define.
> 3.3.2.2 - What about mutability? If I attempt to remove a readOnly, can I? What about "required" attributes?

Good point.
> 3.3.2.3 - What about mutability?

Agreed.

---

From: Ian Glazer <[email-masked]>
Date: Sat, 19 Jul 2014 11:28:44 -0700

Thanks for going through these Phil. Comments below

On Thu, Jul 17, 2014 at 4:46 PM, Phil Hunt <[email-masked]> wrote:

> Thanks for the feedback. Many of these are obvious and will plan to put
> them in the document following Toronto (unless I hear objections). Others I
> will add to the list of discussion items for Toronto.
>
> Phil
>
> @independentid
> www.independentid.com
> [email-masked]
>
>
>
> 1.1 - "identity service providers and client" - This is a little
> confusing. Do we mean identity providers and consumers? providers of
> identity services and organizations that consume those services?
>
>
> How about just “web service providers and clients”.  The fact that it is a
> protocol around identity isn’t near as important as that it is an HTTP
> protocol.
>
> Works for me

> Will Fix. I think the issue here is that it must be a URL (accessible via
> HTTP) but IETF seems to always want URIs regardless.
>
>
> That said, do we want to get into a standardized authorization model?
>  Maybe this is something as a future draft specification. Particularly if
> we want to talk about a future SCIM Directory specification.
>
> Not a huge fan of of standardizing the authZ model right now. I think
there are more worms in that can than we want to deal with right now.

> Per my previous email. I’ve had some recommendation that API always refers
> to a programming library interface rather than over the wire semantics.
> Thus I have begun changing to the SCIM protocol or SCIM HTTP protocol where
> appropriate.
>
> There was some discussion on one of the calls (I can’t remember if we
> followed up on the list). The feeling was that many are beginning to
> implement now. We’d like to keep it in place for now but we agreed it may
> not make the final cut.  This should be a discussion item for Toronto.
>
> I'd push to remove it but it isn't a deal breaker for us.

> I’m open to some discussion here. I’m not sure if there are limited
> scenarios whereby the implementation has to allow this.
>
>
> That doesn't address my poorly made point... What I am trying to ask is:
does it make sense to always hand back the new complete object? Would it be
more efficient to simply hand back a point to the resource instead?

> 3.1 - Is the server required to return a Location header when a resource
> is successfully created? Text does not make that clear.
>
>
> 3.1.1. - Just a clarification - "SHALL be set by the service provider" -
> in this case service provider means SCIM server and not the client, is that
> correct?
>
>
> In all cases “service provider” means the HTTP service, not the provider
> of identity data (the client). Maybe we need more terminology text in the
> intro on this point.
>
>
> No.

> This is regulated by the max results limits. There was a specific example
> of being able to search without regard to resource type, or a specific set
> of resource types. The use case was a search-as-user-types scenario where
> the result was not known to be a user or a group.
>
>
> Maybe you mis-read. If anything, I see it doesn’t say how numeric
> comparisons are made. For strings it is the normal lexicographical
> comparison.
>
>
> Ok, that wasn't obvious from the text.

> Yes. Since it is a replace, but value must always be supplied - even when
> no change. Otherwise it makes missing value logic even more complex. :-)
>
>
> I think we’ve informally discussed that for scim, null == removed. We
> should discuss this in Toronto and formalize this in the spec.  Having null
> equal to removed makes the missing/omitted attribute logic on PUT etc
> easier to define.
>
>

---

From: Chris Phillips <[email-masked]>
Date: Sun, 20 Jul 2014 03:25:10 +0000

+1 to Ian's comments on the AuthZ challenges and not modifying the current SCIM model right now.

Chris.

From: Ian Glazer <[email-masked]<mailto:[email-masked]>>
Date: Saturday, 19 July, 2014 2:28 PM
To: Phil Hunt <[email-masked]<mailto:[email-masked]>>
Cc: "[email-masked]<mailto:[email-masked]> WG" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [scim] Comments so sections 1 through 3.3

<snip>

   GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
   Host: example.com<http://example.com>
   Authorization: Bearer h480djs93hd8

Not a huge fan of of standardizing the authZ model right now. I think there are more worms in that can than we want to deal with right now.

<snip>

---

From: Kelly Grizzle <[email-masked]>
Date: Mon, 21 Jul 2014 13:04:11 +0000

+1 for not standardizing authz now.

From: scim [mailto:[email-masked]] On Behalf Of Chris Phillips
Sent: Saturday, July 19, 2014 8:25 PM
To: [email-masked] WG
Subject: Re: [scim] Comments so sections 1 through 3.3

Chris.

<snip>

   required) ; e.g.,

<snip>

---

From: "Salvatore D'Agostino" <[email-masked]>
Date: Mon, 21 Jul 2014 10:41:54 -0400

yes, +1 leave AuthZ "open"

From: scim [mailto:[email-masked]] On Behalf Of Kelly Grizzle
Sent: Monday, July 21, 2014 9:04 AM
To: Chris Phillips; [email-masked] WG
Subject: Re: [scim] Comments so sections 1 through 3.3

+1 to Ian's comments on the AuthZ challenges and not modifying the current
SCIM model right now.

Chris.

From: Ian Glazer <[email-masked]>
Date: Saturday, 19 July, 2014 2:28 PM
To: Phil Hunt <[email-masked]>
Cc: "[email-masked] WG" <[email-masked]>
Subject: Re: [scim] Comments so sections 1 through 3.3

<snip>

 

That said, do we want to get into a standardized authorization model?  Maybe
this is something as a future draft specification. Particularly if we want
to talk about a future SCIM Directory specification.

Not a huge fan of of standardizing the authZ model right now. I think there
are more worms in that can than we want to deal with right now. 

<snip>

---

From: Kelly Grizzle <[email-masked]>
Date: Mon, 21 Jul 2014 21:38:33 +0000

> I'm open to some discussion here. I'm not sure if there are limited scenarios whereby the implementation has to allow this.

I don't know of any.  I'd be in favor of changing this to a MUST.

From: scim [mailto:[email-masked]] On Behalf Of Phil Hunt
Sent: Thursday, July 17, 2014 4:47 PM
To: Ian Glazer
Cc: [email-masked] WG
Subject: Re: [scim] Comments so sections 1 through 3.3

Ian,

Comments in line below.

Phil

@independentid
www.independentid.com<http://www.independentid.com>
[email-masked]<mailto:[email-masked]>

On Jul 14, 2014, at 11:00 AM, Ian Glazer <[email-masked]<mailto:[email-masked]>> wrote:

How about just "web service providers and clients".  The fact that it is a protocol around identity isn't near as important as that it is an HTTP protocol.

   required) ; e.g.,

Per my previous email. I've had some recommendation that API always refers to a programming library interface rather than over the wire semantics. Thus I have begun changing to the SCIM protocol or SCIM HTTP protocol where appropriate.

There was some discussion on one of the calls (I can't remember if we followed up on the list). The feeling was that many are beginning to implement now. We'd like to keep it in place for now but we agreed it may not make the final cut.  This should be a discussion item for Toronto.

I'm open to some discussion here. I'm not sure if there are limited scenarios whereby the implementation has to allow this.

Maybe it should say "the newly created service provider representation of the full resource"?

In all cases "service provider" means the HTTP service, not the provider of identity data (the client). Maybe we need more terminology text in the intro on this point.

Agreed. Any preferences?

Agreed see above.

3.2.2.2 - What happens if someone includes a "ge" search against a non-numeric or non-date type field? The next isn't clear about a failure condition.
Maybe you mis-read. If anything, I see it doesn't say how numeric comparisons are made. For strings it is the normal lexicographical comparison.

Not sure what you mean. There's no optionality here.

See above.

The problem here was the issue I raised earlier about understanding the implied meaning of a missing value:
* omitted because client isn't aware of it
* omitted because the client does not intend to change it
* omitted because the client wants to default it
* omitted because the client wants to delete it
* omitted because the client doesn't care

I think we've informally discussed that for scim, null == removed. We should discuss this in Toronto and formalize this in the spec.  Having null equal to removed makes the missing/omitted attribute logic on PUT etc easier to define.

Good point.

Agreed.

--
Ian Glazer
Senior Director, Identity
+1 202 255 3166
@iglazer<https://twitter.com/iglazer>
_______________________________________________
scim mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/scim

---

From: Kelly Grizzle <[email-masked]>
Date: Mon, 21 Jul 2014 21:38:47 +0000

> 3.1 - "Successful resource creation..." - It is unclear from the second sentence whether the entire object MUST
> be returned or can the server simply return back a pointer to the newly created object?

> That doesn't address my poorly made point... What I am trying to ask is: does it make sense to always hand back
> the new complete object? Would it be more efficient to simply hand back a point to the resource instead?

I see your point, but don’t think this will be a big concern from an efficiency perspective (maybe on mobile where bandwidth really counts?).  IMO the full representation is pretty useful.  I would be inclined to keep the MUST for now unless we get complaints.

From: scim [mailto:[email-masked]] On Behalf Of Ian Glazer
Sent: Saturday, July 19, 2014 11:29 AM
To: Phil Hunt
Cc: [email-masked] WG
Subject: Re: [scim] Comments so sections 1 through 3.3

On Thu, Jul 17, 2014 at 4:46 PM, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:
Ian,

Comments in line below.

Phil

@independentid

Works for me

   required) ; e.g.,

That doesn't address my poorly made point... What I am trying to ask is: does it make sense to always hand back the new complete object? Would it be more efficient to simply hand back a point to the resource instead?
3.1 - Is the server required to return a Location header when a resource is successfully created? Text does not make that clear.

Agreed. Any preferences?

No.

Agreed see above.

See above.

Good point.

Agreed.

+1 202 255 3166<tel:%2B1%20202%20255%203166>