Subject: [scim] Clarification to Response formats for ServiceProviderConfig, ResourceTypes, and Schemas

From: Phil Hunt <[email-masked]>
Date: Fri, 12 Dec 2014 08:08:25 -0800

It has come to my attention that the configuration endpoints may be somewhat under-defined and may lead to inconsistent implementation. During Wednesday's working group call, we discussed a clarification that should not impact most implementations with normative changes and focused on a clarifying solution. Accordingly, I’ve written up a new section for the SCIM API specification that defines the Service provider config endpoints.

Of special note, we also discussed query support in these endpoints. We wanted to avoid the complex situation of a client having to discover what configuration discovery features are available (configuration for the configuration? where does it end?). Tto keep things simple, we decided either all servers must support configuration queries or none of them should.  Given that query is optional for SCIM resources, we decided that the configuration endpoints should not support query for all servers.  In the text below, I am proposing that most query parameters (attributes, startIndex, etc) are ignored and use of query filters should return HTTP status 403 (FORBIDDEN) to indicate the feature is not supported.

I will revise the drafts on Tuesday. Please voice any objections or concerns to the list as soon as possible.

PROPOSED TEXT:
4.  Service Provider Configuration Endpoints

   SCIM 2 defines 3 endpoints to facilitate discovery of SCIM service
   provider features and schema that MAY be retrieved using HTTP GET:

   /ServiceProviderConfig
      An HTTP GET to this endpoint will return a JSON structure that
      describes the SCIM specification features available on a service
      provider.  This endpoint SHALL return responses with a JSON object
      using a "schemas" attribute of
      "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig".
      The attributes returned in the JSON object are defined in
      Section 5 [I-D.ietf-scim-core-schema].  An example representation
      of SCIM Service Provider configuration may be found in Section 8.5
      [I-D.ietf-scim-core-schema].

   /Schemas
      An HTTP GET to this endpoint is used to retrieve information about
      resource schemas supported by a SCIM Service Provider.  An HTTP
      GET to the endpoint "/Schemas" SHALL return all supported schemas
      in ListResponse format (see Figure 3).  Individual schema
      definitions can be returned by appending the schema URI to the
      schemas endpoint.  For example:

            /Schemas/urn:ietf:params:scim:schemas:core:2.0:User

      The contents of each schema returned is described in Section 7
      [I-D.ietf-scim-core-schema].  An example representation of SCIM
      schemas may be found in Section 8.7 [I-D.ietf-scim-core-schema].

   /ResourceTypes
      An HTTP GET to this endpoint is used to discover the types of
      resources available on a SCIM Service Provider (e.g.  Users and
      Groups).  Each resource type defines the endpoints, the core
      schema URI that defines the resource, and any supported schema
      extensions.  The attributes defining a resource type can be found
      in Section 6 [I-D.ietf-scim-core-schema], and an example
      representation can be found in Section 8.6
      [I-D.ietf-scim-core-schema].

   In cases where a request is for a specific "ResourceType" or
   "Schema", the single JSON object is returned in the same way a single
   User or Group is retrieved as per Section 3.2.1.  When returning
   multiple ResourceTypes or Schemas, the message form described by
   "urn:ietf:params:scim:api:messages:2.0:ListResponse" (ListResponse)
   form SHALL be used as shown in Figure 3 and Figure 9 below.  Query
   parameters described in section 3.2 such as, sorting, attributes, and
   paging SHALL be ignored.  If a "filter" is provided, the service
   provider SHOULD respond with HTTP Status 403 (FORBIDDEN) to ensure
   clients cannot incorrectly assume any matching conditions specified
   in a filter are true.

   The following is a non-normative example of an HTTP GET to the
   /ResourceTypes endpoint:

  {
    "totalResults":2,
    "itemsPerPage":10,
    "startIndex":1,
    "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "Resources":[{
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id":"User",
      "name":"User",
      "endpoint": "/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [{
        "schema":
          "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "required": true
      }],
      "meta": {
        "location":"https://example.com/v2/ResourceTypes/User <https://example.com/v2/ResourceTypes/User>",
        "resourceType": "ResourceType"
      }
    },
   {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
     "id":"Group",
     "name":"Group",
     "endpoint": "/Groups",
     "description": "Group",
     "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
     "meta": {
       "location":"https://example.com/v2/ResourceTypes/Group <https://example.com/v2/ResourceTypes/Group>",
       "resourceType": "ResourceType"
     }
   }]
  }

            Figure 9: Example Resource Type JSON Representation

Phil

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

---

From: Ian Glazer <[email-masked]>
Date: Mon, 15 Dec 2014 09:56:46 -0500

Phil -

Just to be perfectly clear this clarification on the /ResourceTypes
endpoint means GETs will either get all of the Resource Types or just one
and that's it. Correct?

On Fri, Dec 12, 2014 at 11:08 AM, Phil Hunt <[email-masked]> wrote:
>
>
> It has come to my attention that the configuration endpoints may be
> somewhat under-defined and may lead to inconsistent implementation. During
> Wednesday's working group call, we discussed a clarification that should
> not impact most implementations with normative changes and focused on a
> clarifying solution. Accordingly, I’ve written up a new section for the
> SCIM API specification that defines the Service provider config endpoints.
>
> Of special note, we also discussed query support in these endpoints. We
> wanted to avoid the complex situation of a client having to discover what
> configuration discovery features are available (configuration for the
> configuration? where does it end?). Tto keep things simple, we decided
> either all servers must support configuration queries or none of them
> should.  Given that query is optional for SCIM resources, we decided that
> the configuration endpoints should not support query for all servers.  In
> the text below, I am proposing that most query parameters (attributes,
> startIndex, etc) are ignored and use of query filters should return HTTP
> status 403 (FORBIDDEN) to indicate the feature is not supported.
>
> I will revise the drafts on Tuesday. Please voice any objections or
> concerns to the list as soon as possible.
>
> PROPOSED TEXT:
>
>         "location":"https://example.com/v2/ResourceTypes/User",
>        "location":"https://example.com/v2/ResourceTypes/Group",
> www.independentid.com
> [email-masked]
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim
>
>

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

---

From: Phil Hunt <[email-masked]>
Date: Mon, 15 Dec 2014 09:46:11 -0800

Yes. 

/ResourceTypes/{name}

Returns a single

/ResourceTypes

Returns all. 

Phil

> On Dec 15, 2014, at 06:56, Ian Glazer <[email-masked]> wrote:
> 
> Phil - 
> 
> Just to be perfectly clear this clarification on the /ResourceTypes endpoint means GETs will either get all of the Resource Types or just one and that's it. Correct?
> 
> @iglazer

---

From: Ian Glazer <[email-masked]>
Date: Mon, 15 Dec 2014 12:59:58 -0500

Okay. that makes sense.

---

From: Kelly Grizzle <[email-masked]>
Date: Mon, 15 Dec 2014 21:11:51 +0000

+1 … I think this proposal makes lots of sense.

From: scim [mailto:[email-masked]] On Behalf Of Phil Hunt
Sent: Friday, December 12, 2014 10:08 AM
To: SCIM WG
Subject: [scim] Clarification to Response formats for ServiceProviderConfig, ResourceTypes, and Schemas
Importance: High

PROPOSED TEXT:

   /ServiceProviderConfig

   /Schemas

   /ResourceTypes

   in a filter are true.

   /ResourceTypes endpoint:

  {

    "totalResults":2,

    "itemsPerPage":10,

    "startIndex":1,

    "Resources":[{

      "id":"User",

      "name":"User",

      "endpoint": "/Users",

      "schemaExtensions": [{

        "schema":

        "required": true

      }],

      "meta": {

      }

    },

   {

     "id":"Group",

     "name":"Group",

     "endpoint": "/Groups",

     "description": "Group",

     "meta": {

     }

   }]

  }

Phil

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