Subject: [scim] Comments for sections 3.4 to the end

From: Ian Glazer <[email-masked]>
Date: Tue, 15 Jul 2014 08:29:14 -0700

Here's a few more comments:

3.4 Delete - Does an SP who chooses not to permanently delete a resource
have to tell the client of that choice?

3.4 Delete conflicts - "SP MUST not consider deleted resource in conflict
calculation" -  What about situations where the SP requires all userNames
to be unique and holds delete accounts to ensure no repetition of
userNames? This might cause a problem for Salesforce.

3.5 Bulk - Maybe my memory failed me here but I thought we were carving
Bulk out as its own profile to be dealt with later. Given that no one has
implemented it I wonder if it doesn't make sense to completely pull it and
put it into a future profile.

3.5 Bulk - formatting issue - Page 38 of the pdf. The paragraph beginning
"The following example shows how to add..." is formatted like example code
not regular text.

3.5 Bulk - formatting issue - Page 40 of the pdf. The paragraph beginning
"The following response is returned if an error occurred..." is formatted
like example code not regular text.

3.5 Bulk - formatting issue - same problems on pages 41 and 42 as 38 and 40.

3.7 attributes - If "attributes" are specified, it isn't clear if default
attributes are also returned along with the minimum set and those
specified. I think this needs to say explicitly that default attributes are
not returned when "attributes" are specified.

6.4 - Universal Identifiers - ?

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

---

From: Phil Hunt <[email-masked]>
Date: Fri, 18 Jul 2014 19:18:23 -0700

Ian… thanks again.  Comments inline

Phil

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

On Jul 15, 2014, at 8:29 AM, Ian Glazer <[email-masked]> wrote:

> 3.4 Delete - Does an SP who chooses not to permanently delete a resource have to tell the client of that choice?

The wording in 3.4 is intentional and leaves room for the record to be retained. However, as far as the REST API is concerned the record is gone.

I’ve had some thought that we may need to define functions down the road the provide high-level IDM functions like password self service, de-provisioning/de-activation, etc that go beyond simple state changes.  If we do that, the way we’ve worded DELETE for now should be compatible. 
> 
> 3.4 Delete conflicts - "SP MUST not consider deleted resource in conflict calculation" -  What about situations where the SP requires all userNames to be unique and holds delete accounts to ensure no repetition of userNames? This might cause a problem for Salesforce.

Yes. This is an issue. The current text says the SP is to act as if the resource is gone.  That potentially means freeing up old user-ids. 

Yet, I can see it is perfectly reasonable that a SP may never release a username once used. Maybe the wording we have is a bit too tight?
> 
> 3.5 Bulk - Maybe my memory failed me here but I thought we were carving Bulk out as its own profile to be dealt with later. Given that no one has implemented it I wonder if it doesn't make sense to completely pull it and put it into a future profile.

I think I commented earlier — several orgs were starting implementation the last time we discussed. I think the idea will be to discuss in Toronto and confirm we are keeping it.
> 
> 3.5 Bulk - formatting issue - Page 38 of the pdf. The paragraph beginning "The following example shows how to add..." is formatted like example code not regular text.

Will fix.
> 
> 3.5 Bulk - formatting issue - Page 40 of the pdf. The paragraph beginning "The following response is returned if an error occurred..." is formatted like example code not regular text.
Will fix
> 3.5 Bulk - formatting issue - same problems on pages 41 and 42 as 38 and 40.
Ditto.
> 
> 3.7 attributes - If "attributes" are specified, it isn't clear if default attributes are also returned along with the minimum set and those specified. I think this needs to say explicitly that default attributes are not returned when "attributes" are specified.

Will correct.
> 6.4 - Universal Identifiers - ?

I saw that today. I can’t recall what that was about.  I think it was going to be a caution about using things like DN’s as identifiers and the need to ensure universality and stability (does not change). 

Maybe someone else recalls?
> @iglazer
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim

---

From: Kelly Grizzle <[email-masked]>
Date: Mon, 21 Jul 2014 18:14:00 +0000

> Yet, I can see it is perfectly reasonable that a SP may never release a username once used. Maybe the wording we have is a bit too tight?

+1 for loosening the requirement here.

> I saw that today. I can't recall what that was about.  I think it was going to be a caution about
> using things like DN's as identifiers and the need to ensure universality and stability (does not change).
>

I think that you added this in draft 5 (it doesn't show up in -04.xml).

https://code.google.com/p/scim/source/detail?spec=svn248&r=241

I just looked through the tickets mentioned in this changeset and didn't see anything really related to universal identifiers (as far as I can tell).  I'd say just drop the section.

--Kelly

From: scim [mailto:[email-masked]] On Behalf Of Phil Hunt
Sent: Friday, July 18, 2014 7:18 PM
To: Ian Glazer
Cc: [email-masked] WG
Subject: Re: [scim] Comments for sections 3.4 to the end

Ian... thanks again.  Comments inline

Phil

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

On Jul 15, 2014, at 8:29 AM, Ian Glazer <[email-masked]<mailto:[email-masked]>> wrote:

I've had some thought that we may need to define functions down the road the provide high-level IDM functions like password self service, de-provisioning/de-activation, etc that go beyond simple state changes.  If we do that, the way we've worded DELETE for now should be compatible.

I think I commented earlier - several orgs were starting implementation the last time we discussed. I think the idea will be to discuss in Toronto and confirm we are keeping it.

Will fix.

Will correct.

I saw that today. I can't recall what that was about.  I think it was going to be a caution about using things like DN's as identifiers and the need to ensure universality and stability (does not change).

--
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: Erik Wahlström <[email-masked]>
Date: Mon, 21 Jul 2014 20:13:01 +0000

My comments on the API doc. Might be some duplicates in there. Mostly minor comments.

General comments:
- I think that the Protocol document requires more examples when it comes to the Schema, ResourceTypes and the ServiceProviderConfigs end points. They are kinda special, how are they handled when it comes to search for example.
- The ResourceType is messy. Merge it with a resource instead?

—————————

1.  Introduction and Overview

Current:
   The protocol
   supports creation, modification, retrieval, and discovery of core
   identity resources; i.e., Users and Groups, as well as custom
   resource extensions.

Comment:
    The last sentence limits the protocol to just extensions to Users and Groups. SCIM can also provision other types of resources (Schema and ServiceProviderConfigs) and it can also be extended with new types of Resources like Machine or Device.

—————————

1.1.  Intended Audience

Current:
   This document is intended as a guide to SCIM API usage for both
   identity service providers and clients.

To:
   This document is intended as a guide to SCIM Protocol usage for both
   identity service providers and clients.

—————————

1.3.  Definitions

Current:
The SCIM HTTP API is always relative to a Base URL.

To:
The SCIM HTTP Protocol is always relative to a Base URL.

--------------

3.  API

Current text: Change title from "3. API"

To: "3. Protocol"

-----------

3.  API (The Resource endpoint table)

It's not totally up to date. Only DELETE have links to the delete section in the document.

On both User and Group, current text says:
"Retrieve/Add/Modify Users"
To:
"Retrieve/Add/Modify/Delete Users"

--------

3.  API

Current:
"Retrieve a resource's schema"
Comment:
It can read more then just one schemas resource, it can also be used to list all supported schemas.

-----------

3.  API

Current:
"To create new resources, clients send POST requests to the resource container endpoint such as: "/Users" or "/Groups"."
To:
"To create new resources, clients send POST requests to the resource endpoint such as: "/Users" or "/Groups"."
Comment:
Why use the word container?

----------

3.1.1.  Resource Types

Current: "When adding a resource to a specific endpoint, the meta attribute
  "resourceType" SHALL be set by the service provider to the
  corresponding resource Type for the endpoint."
Comment:
Why SHALL? Why not MUST?

---------

3.2.  Retrieving Resources

Current:
""User" and "Group" resources are retrieved via opaque, unique URLs or via Query."
To:
Resources are retrieved via opaque, unique URLs or via Query.
Comment:
It applies to more resources then just User and Groups (even Resources defined in the document).

---------

3.2.1.  Retrieving a known Resource

Current:
   "To retrieve a known resource, clients send GET requests to the
   resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}".""

To:
"To retrieve a known resource, clients send GET requests to the
resource endpoint; e.g., "/Users/{id}", "/Groups/{id}" or "/Schema/{id}".

Comment:
How about adding some of the other resources types for clarity?

---------

3.2.2.1.  Query Endpoints
Current:
"/Users/{userid}"
Comment:
Sometimes we use /Users/{id} and sometimes /Users/{userid}. I propose that we always use {id}.

--------

3.2.2.2.  Filtering

Current:
"The attribute name and attribute operator are case insensitive."
Comment:
Something feels wrong with this? English is not native language, like C :), but itn's it "is" instead of "are"?

---------

3.2.2.3.  Sorting

Current:
"for caee insensitive attributes"
To:
"for case insensitive attributes"
----------

3.3.  Modifying Resources

Current:
"PATCH [RFC5789] to "
Comment:
Links to the RFC, should be linked to Normative References secion instead.

--------

3.3.1.  Replacing with PUT

Current:
"Clients that would like to override a
   server defaults, MAY specify "null" for a single-valued attribute or
   an empty array "[]" for a multi-valued attribute to clear all values."
Comment:
Why do we have something like this? It adds a complexity to the service provider and for not so much reasons. Should be up to the SP what to store and how to interpritate the clients requests. We even state in the next section "Since the server is free to
   alter and/or ignore POSTed content". I propose to remove that capability for the client.

---------

3.3.1.  Replacing with PUT

Current:
"to correlate the client's and Provider's views of the updated resource"
To:
"to correlate the Client's and Service Provider's views of the updated resource"

---------

3.3.2.  Modifying with PATCH

Current:
"If a request fails. the server SHALL"
To:
"If a request fails, the server SHALL"
Comment:
Comma instead of period.

----------

3.4.  Deleting Resources

Current: "operations associated with the previously deleted Id"
To: "operations associated with the previously deleted id"
Comment: Capital I in Id.

-------------

3.5.  Bulk

Current:
"version  The current resource version.  Version is REQUIRED if the
         service provider supports ETags and the method is PUT, DELETE,
         or PATCH."

To:
"version  The current resource version."

Comment:
In "3.12.  Versioning Resources" we now state that client MAY send it in PUT and PATCH (not DELETE, we just delete the resource)

We should also remove the version attribute in the DELETE requests in the bulk jobs. Example:

Current:
       {
         "method":"DELETE",
         "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
         "version":"W\/\"0ee8add0a938e1a\""
       }
     ]
   }

To:
       {
         "method":"DELETE",
         "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b"
       }
     ]
   }

----------

3.7.  Additional Operation Response Parameters

Comment: It feels like we usually talk about MUST attributes in the core schema, this is more generic, but a bit fuzzier. Can we say both?

--------------------

3.7.  Additional Operation Response Parameters

Current:
"The defaut attribute set are those attributes whose schema have "returned" set to "default"."
To:
"The default attribute set are those attributes whose schema have "returned" set to "default"."

------------

3.9.  "/Me" Authenticated Subject Alias

Current:
"A client MAY use a URL of the form "<server-root>/Me" as an URL alias"
Comment:
Shoudn't it be "<base-url>/Me"? We have a /Me interface, but it's not hosted on the server-root.

-------------

Authors' Addresses

From:

   Erik Wahlstroem
   Technology Nexus

   Email: [email-masked]<mailto:[email-masked]>

To:

   Erik Wahlstroem
   Nexus Technology

   Email: [email-masked]<mailto:[email-masked]>

Comment:
New legal name, and new email address.

—————————

/ Erik

On 15 Jul 2014, at 17:29, Ian Glazer <[email-masked]<mailto:[email-masked]>> wrote:

---

From: Phil Hunt <[email-masked]>
Date: Mon, 21 Jul 2014 17:03:06 -0400

Erik,

I think in general, we will align around HTTP protocol….no need for everyone to enumerate them.

See other comments below…

Phil

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

> - The ResourceType is messy. Merge it with a resource instead? 
Can you make some suggestions?
>     The last sentence limits the protocol to just extensions to Users and Groups. SCIM can also provision other types of resources (Schema and ServiceProviderConfigs) and it can also be extended wi…
Agreed
> The SCIM HTTP Protocol is always relative to a Base URL.  
We should discuss at meeting.
> "Retrieve/Add/Modify/Delete Users”

There seems to be a bug in the xml2rfc processor. Only random links are being generated. I’ve checked and the underlying xml is correct.

I think we have to leave this to the final RFC editors who will fix this stuff.

I notice this is a common term being using in REST.  “/Users” is a container (a folder). “Endpoint” is not distinguished from a user’s specific endpoint.

Not sure this is a big deal.  But we should be editorially consistent.

It sounded better. SHALL is equivalent of MUST in RFC terms.  SHALL also implies the service provider is doing it in response to the client.
> It applies to more resources then just User and Groups (even Resources defined in the document).
Agreed - -we should make sure the entire spec is generic.
> How about adding some of the other resources types for clarity? 
Agreed. More examples or at least genericize
> Sometimes we use /Users/{id} and sometimes /Users/{userid}. I propose that we always use {id}.

Agreed.
> Something feels wrong with this? English is not native language, like C :), but itn's it "is" instead of "are”?

Not quite right.

Attribute names and operators are case insensitive.

> "for case insensitive attributes"
agreed

> Links to the RFC, should be linked to Normative References secion instead.

The xml2rfc generator takes care of this. Current style seems to be direct links.
>    alter and/or ignore POSTed content". I propose to remove that capability for the client.

The change is intended to be minor. Rather than trying to infer meaning of a missing value we instead go back to what the client is trying to express.

From what I could figure out from the comments was that there are times when a server will “default” unasserted values (e.g. provide a default set of roles).  In the case where the client wants to have no roles, the client can simply include “roles”:[] to indicate no roles should be assigned.  If the client includes no value, the logic is the same as before.

> "to correlate the Client's and Service Provider's views of the updated resource”

agreed
> "If a request fails, the server SHALL"
agreed
check
Is this meant to be an ETag?  Why not use etag?
>          "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b"
not sure what the differnence is

If SCIM defines this it has to be within the SCIM server’s endpoint.  I wanted to say the root because I want to avoid tying it to “Users”. “/Me” might map back to /Clients/{id}  (e.g. an oauth client)..

> 
> -------------   
>    
> 
> Authors' Addresses
> 
> From:
> 
>    Erik Wahlstroem
>    Technology Nexus
> 
>    Email: [email-masked]
> 
> To:
> 
>    Erik Wahlstroem
>    Nexus Technology
> 
>    Email: [email-masked]
> 
> Comment:

ok
> 
> —————————
> 
> 
> / Erik
> 
> 
> On 15 Jul 2014, at 17:29, Ian Glazer <[email-masked]> wrote:
>

---

From: Erik Wahlström <[email-masked]>
Date: Mon, 21 Jul 2014 21:33:23 +0000

Hi Phil,

> Can you make some suggestions?

Ok. I’ll have a look at it. Just something to make the differentiation in between Schema/Resource/Resouce type and endpoint extra super clear.

> From what I could figure out from the comments was that there are times when a server will “default” unasserted values (e.g. provide a default set of roles).  In the case where the client wants to…

Ok. I understand the requirement now. Works for me.

> Is this meant to be an ETag?  Why not use stag?

Yes, it’s an ETag. The reason it was named version instead of ETag is that ETag is so bound i HTTP. And it could be sent through any potential transport protocol  in the future (SAML, XMPP…). version is a bit more generic and future proof.

> not sure what the difference is

“defaut” is missing an L :)

Cheers
Erik