Versions Compared

Old Version 67

changes.mady.by.user Benn Oshrin

Saved on

compared with

New Version 68

changes.mady.by.user Benn Oshrin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0
CIFER API Framework vis-a-vis SCIM API and SCIM Schema
Section
bordertrue
Column
width50%

CIFER Framework

4. Authentication and Authorization

The framework does not specify authentication or authentication methods. Some acceptable methods include:
    1. Basic auth over https
    2. Client certificate auth over https
    3. Encrypted and signed content over any transport

Info

JF: There are many equally valid auth methods

Info

Issue #6: Capability for Server to Indicate Authentication Methods

The SCIM protocol does not define a scheme for authentication and authorization therefore implementers are free to choose mechanisms appropriate to their use cases. The choice of authentication mechanism will impact interoperability. 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 10.4.2 of Section 10.4.2 \ [RFC2616\].unmigrated-wiki-markup

All examples assume OAuth2 bearer token \ [RFC6750\]; 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.

Column
width50%

SCIM API

2. Authentication and Authorization

Wiki Markup

Section
bordertrue

Column
width50%

CIFER Framework

5.1.1. URI syntax

A major version of a particular CIFER API must be indicated in the URI path (for example, "/v2/"). A major version will differentiate incompatible representations, parameters or headers. A major version change is also indicated by a change in field type. Any minor version will be indicated in the response metadata not in the URI path (see response section below).

Info

JF: SCIM language seems OK

Info

Issue #4: Local Versioning in Request


Column
width50%

SCIM API

3.11.  API Versioning

The Base URL MAY be appended with a version identifier as a separate segment in the URL path.  At this time of this specification, the identifier is 'v2'.  If specified, the version identifier MUST appear in the URL path immediately preceding the resource endpoint and conform to the following scheme: the character 'v' followed by the desired SCIM version number; e.g., a version 'v2' User request is specified as /v2/Users.  When specified service providers MUST perform the operation using the desired version or reject the request.  When omitted service providers SHOULD perform the operation using the most recent SCIM protocol version supported by the service provider.


Section
bordertrue

Column
width50%

CIFER Framework

5.1.2. Request/response grammar

1. Default representation language is Javascript Object Notation (JSON).
2. XML can be requested, but support is not required.

Info

Consider adopting SCIM language


All requests to the service provider are made via Section 9 \ [RFC2616\] on a URL derived from the Base URL.    Responses are returned in the body of the HTTP response, formatted as JSON.    Response and error codes SHOULD be transmitted via the HTTP status code of the response (if possible), and SHOULD also be specified in the body of the response.

3.6.  Data Input/Output Formats

Servers MUST accept requests and respond with JSON structured responses using UTF-8 encoding \ [RFC3629\], UTF-8 SHALL be the default encoding format.unmigrated-wiki-markup

Clients using other encodings MUST specify the format in which the data is submitted via Section 14.17 HTTP header content-type\[RFC2616\] and MAY specify the desired response data format via an HTTP Accept Header; e.g.,"Accept: application/json" or via URI suffix; e.g.,

GET /Users/2819c223-7f76-453a-919d-413861904646.json
Host: example.com

Service providers MUST support the Accept Headers "Accept: application/json" for \ [RFC7159\].    The format defaults to JSON if no format is specified.

Column
width50%

SCIM API

3. API

Wiki Markup
Wiki Markup
Wiki Markup
Section
bordertrue
Column
width50%

CIFER Framework

5.1.3. Data and field formats

1. Character set is Unicode, encoded as UTF-8.

Info

Consider adopting SCIM language


   Servers MUST accept requests and respond with JSON structured    responses using UTF-8 encoding \[RFC3629\], UTF-8 SHALL be the default    encoding    Servers MUST accept requests and respond with JSON structured
   responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default
   encoding format.

Column
width50%

SCIM API

3.6.  Data Input/Output Formats

Wiki Markup

Section
bordertrue

Column
width50%

CIFER Framework

5.1.3. Data and field formats

2. Timestamp representations will comply with ISO 8601. For example: 2012-10-04T03:10:14.123Z

Info

Consider adopting SCIM language



Column
width50%

SCIM Core Schema

3.1.5.  DateTimeunmigrated-wiki-markup

A DateTime value (e.g. 2008-01-23T04:56:22Z).    The attribute value MUST be encoded as a valid xsd:dateTime as specified in Section 3.2.7 \ [XML-Schema\].unmigrated-wiki-markup

Values represented in JSON MUST conform to the XML constraints above and are represented as a JSON String per Section 7 \ [RFC7159\].

Section
bordertrue

Column
width50%

CIFER Framework

5.1.3. Data and field formats

3. Durations also comply with ISO 8601, For example: P1.81S


Column
width50%

SCIM API

No mention of durations or time intervals



...

Section
bordertrue

Column
width50%

CIFER Framework

5.1.3. Data and field formats

6. Field names must start with a letter. They can contain upper/lower letters, numbers and underscores.

Info

Consider adopting SCIM language



Attribute names MUST conform to the following ABNF \ [RFC5234 \ ] rules:     ATTRNAME = ALPHA \
    ATTRNAME = ALPHA *(nameChar)     nameChar =
    nameChar = "-" / "_" / DIGIT / ALPHA

Column
width50%

SCIM Core Schema

3. SCIM Schema Structure

Wiki Markup


Section
bordertrue

Column
width50%

CIFER Framework

5.1.3. Data and field formats

7. Field types must stay consistent within a major version.


Column
width50%

SCIM

No guidance on what kinds of changes should lead to a new major version number



...

Section
bordertrue

Column
width50%

CIFER Framework

5.2.1 Resource references

CIFER APIs accommodate large responses by recognizing full and partial resources.

1. A full resource, where the response is the full resource requested, must be identified by a URI only, not by query string or fragment

2. A partial resource, like a response that is better served across pages, is identified by a URI that contains at least one additional query string parameter (see paging options in query string options section below)

NOTE: CIFER refers to pagination of single large resources, whereas SCIM discusses pagination only in reference to responses containing multiple resources.

Info

Consider referencing OpenSearch protocol re pagination parameters and behavior



Pagination parameters can be used together to "page through" large numbers of resources so as not to overwhelm the client or service provider. Pagination is not session based hence clients SHOULD never assume repeatable results. For example, a request for a list of 10 resources beginning with a startIndex of 1 may return different results when repeated as a resource in the original result could be deleted or new ones could be added in-between requests. Pagination parameters and general behavior are derived from the OpenSearch Protocol \ [OpenSearch\].

Column
width50%

SCIM API

3.2.2.4 Pagination

Wiki Markup


Section
bordertrue

1. The request method of POST \ [may be\] overridden by a header (see header options below). NOTE: see section 5.2 3 below for details

2. A PUT request need not specify all attributes.

  1. Replacing a resource will not affect attributes not specified in the request.
  2. A necessary attribute not specified will return an error 400 (see response codes below)
Column
width50%

CIFER Framework

5.2.2 Request Methods

Wiki Markup
Info

JF: We have to consider missing attributes if we allow new attributes without re-versioning.

PATCH, if logically a set of PUT/DELETE, is OK


Column
width50%

SCIM API

3. API

PUT Modifies a resource with a complete, client specified resource (replace).

PATCH Modifies a resource with a set of client specified changes (partial update).

NOTE: See also the substantial section 3.3 and its subsections on modifying resources



Section
bordertrue

Column
width50%

CIFER Framework

5.2.2.  Request methods

3. Searches return resource URIs and default resource attributes.

  • Each service will document the fields returns on searches.
  • Searches may request "&extraFields=field3,field4,..&" to get those fields in addition to the default set.
  • Searches may request "&omitFields=field3,field4,..&" to omit those fields from the default set.
  • Support for these features is optional.

4. Searches may specify paging options by query string parameters

  • pageLimit: Number of entries per page
  • pageOffset: page number, first page is zero
Info

Consider adopting SCIM language on queries (3.2.2 and 3.2.3)



excludedAttributes  A excludedAttributes  A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.    This parameter SHALL have no effect on attributes whose schema "returned" setting is "always" see Server Schema \ [I-D.ietf-scim-core-schema\].    Attribute names MUST be in standard attribute notation (Section 3.8) form.    See additional retrieval query parameters (Section 3.7).    OPTIONAL.
Column
width50%

SCIM API

3.2.  Retrieving Resources

"User" and "Group" resources are retrieved via opaque, unique URLs or via Query.  Service providers MAY choose to respond with a sub-set of resource attributes, though MUST minimally return the resource id and meta attributes.

3.2.1.  Retrieving a known Resource

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

If the resource exists the server responds with a status code of 200 and includes the result in the body of the response.

3.2.2.  List/Query Resources

SCIM defines a standard set of operations that can be used to filter, sort, and paginate response results.  The operations are specified by adding query parameters to the resource's endpoint.  Service providers MAY support additional query parameters not specified here, and Providers SHOULD ignore any query parameters they don't recognize.

_NOTE: See the rest of section 3.2.2 and its subsections for details on query endpoints, filters, sorting and pagination_

3.2.3 Querying Resources Using HTTP POST

Clients MAY execute queries without passing parameters on the URL by using the HTTP POST verb combined with the '/.search' path extension. The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL be used to indicate the HTTP POST verb is intended to be a query operation.

...

The following attributes are defined for search requests:

  • attributes  A multi-valued list of strings indicating the names of resource attributes to return in the response overriding the set of attributes that would be returned by default.  Attribute names MUST be in standard attribute notation (Section 3.8) form.  See additional retrieval query parameters (Section 3.7).  OPTIONAL.
Wiki Markup


Section
bordertrue

Column
width50%

CIFER Framework

5.2.3. Header Options

1. The request method of POST may be overridden by the header:

  • X-HTTP-Method-Override: GET | PUT | DELETE
Info

JF: A method override is sometimes necessary


Column
width50%

SCIM API

Appendix C.  Change log

Draft 05 - PH - Revisions based on the following tickets:

  65 - Removed X-HTTP-Method-Override support

...

Section
bordertrue

Column
width50%

CIFER Framework

5.2.3. Header Options

3. Use of ETag and If-Match:

  • A request to replace a resource must specify an If-Match header
    • The value must match the resource's current ETag value, or
    • The value may be a 'match-any' wildcard, '*'
    • Acceptance of wildcard is service dependent.
    • A request to add a resource must not specify an If-Match header
Info

Review in light of SCIM approach



   The API supports resource versioning via standard HTTP ETags Section 2.3 \[RFC7233\].  Service providers MAY support weak ETags as the preferred mechanism for performing conditional retrievals and ensuring clients do not inadvertently overwrite each others changes, respectively.  When supported SCIM ETags MUST be specified as an HTTP header and SHOULD be specified within the 'version' attribute contained in the resource's 'meta'    The API supports resource versioning via standard HTTP ETags Section 2.3 [RFC7233].  Service providers MAY support weak ETags as the preferred mechanism for performing conditional retrievals and ensuring clients do not inadvertently overwrite each others changes, respectively.  When supported SCIM ETags MUST be specified as an HTTP header and SHOULD be specified within the 'version' attribute contained in the resource's 'meta' attribute.

...

  If the service providers supports versioning of resources the client MAY supply an If-Match Section 3.1 \[RFC7233\] header for PUT and PATCH operations to ensure that the requested operation succeeds only if the supplied ETag matches the latest service provider resource;   If the service providers supports versioning of resources the client MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH operations to ensure that the requested operation succeeds only if the supplied ETag matches the latest service provider resource; e.g., If-Match: W/"e180ee84f0671b1"

Column
width50%

SCIM API

3.12.  Versioning Resources

Wiki Markup
Wiki Markup

Section
bordertrue

Column
width50%

CIFER Framework

5.2.3. Header Options

4. A client may request to "act as" another user via a header:

  • X-CIFER-Act-As: user_uri

Column
width50%

SCIM API
NOTE: SCIM does not have a concept of authorization of proxy actors such as that represented by the X-CIFER-Act-As header

Section
bordertrue
Column
width50%

CIFER Framework

5.2.4. Query String Options

1. Requests may specify field filters on returned resources.

  • Query string may specify a list desired fields: "&fields=field1,field2,...&"
  • A requests (sic) for an unknown field is not an error.
  • Support for this feature is optional.
Info

Review in light of SCIM approach


excludedAttributes  A excludedAttributes  A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.    This parameter SHALL have no effect on attributes whose schema "returned" setting is "always" see Server Schema \ [I-D.ietf-scim-core-schema\].    Attribute names MUST be in standard attribute notation (Section 3.8) form.    See additional retrieval query parameters (Section 3.7).    OPTIONAL.
Column
width50%

SCIM API

3.2.2.  List/Query Resources

SCIM defines a standard set of operations that can be used to filter, sort, and paginate response results.  The operations are specified by adding query parameters to the resource's endpoint.  Service providers MAY support additional query parameters not specified here, and Providers SHOULD ignore any query parameters they don't recognize.

_NOTE: See the rest of section 3.2.2 and its subsections for details on query endpoints, filters, sorting and pagination_

3.2.3 Querying Resources Using HTTP POST

Clients MAY execute queries without passing parameters on the URL by using the HTTP POST verb combined with the '/.search' path extension. The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL be used to indicate the HTTP POST verb is intended to be a query operation.

...

The following attributes are defined for search requests:

  • attributes  A multi-valued list of strings indicating the names of resource attributes to return in the response overriding the set of attributes that would be returned by default.  Attribute names MUST be in standard attribute notation (Section 3.8) form.  See additional retrieval query parameters (Section 3.7).  OPTIONAL.
Wiki Markup

Section
bordertrue

Column
width50%

CIFER Framework

5.2.4. Query String Options

2. Requests for large resources, e.g. group membership, may specify paging parameters

  • sortField:
  • sortOrder: 'a*', 'd*', case insensitive
  • pageLimit: number of entries per page, zero means no paging
  • Mutually exclusive page start:
    • pageOffset: page number, starting with zero,
      OR
    • pageStartValue: first value returned will be the one AFTER this value
  • The service may provide default paging parameters, and may reduce the requested limits.

Column
width50%

SCIM API

3.2.2.4 Paginationunmigrated-wiki-markup

Pagination parameters can be used together to "page through" large numbers of resources so as not to overwhelm the client or service provider. Pagination is not session based hence clients SHOULD never assume repeatable results. For example, a request for a list of 10 resources beginning with a startIndex of 1 may return different results when repeated as a resource in the original result could be deleted or new ones could be added in-between requests. Pagination parameters and general behavior are derived from the OpenSearch Protocol \ [OpenSearch\].


Section
bordertrue

Column
width50%

CIFER Framework

5.2.4. Query String Options

3. Boolean parameters are generously interpreted

  • true|false, or t|f or yes|no, or y|n or 1|0, case insensitive

Column
width50%

SCIM API

3.2.2.2.  Filtering

   Filtering is OPTIONAL.

   compValue = false / null / true / number / string
                 ; rules from JSON (RFC7159)

NOTE: SCIM filtering options are as rich or richer than LDAP filter options. See section 3.2.2.2 for full details


...

Section
bordertrue

Column
width50%

CIFER Framework

5.4.2. Response Codes

  1. 200: the resource was found
  2. 201: the resource was created
  3. 400: the request was not valid
  4. 401: the client was unauthenticated
  5. 403: an authenticated client was not authorized for the request
  6. 404: a requested resource was not found
  7. 409: (conflict)
    • PUT to an existing resource without an If-Match
  8. 412: (precondition failed)
    • If-Match header did not match resource's ETag, or
    • If-Match header supplied but resource not found (add with an if-match), or
    • wildcard if-match not allowed
  9. 500: server error
Info

JF: We may want to include some content on a successful DELETE, then the response would be 200.


   The SCIM Protocol uses the response status codes defined in HTTP Section 6 \[RFC7231\] to indicate operation success or failure.  In addition to returning a HTTP response code implementers MUST return the errors in the body of the response in the client requested format containing the error response and, per the HTTP specification, human-readable explanations.  Error responses are identified using the following "schema" URI:    The SCIM Protocol uses the response status codes defined in HTTP Section 6 [RFC7231] to indicate operation success or failure.  In addition to returning a HTTP response code implementers MUST return the errors in the body of the response in the client requested format containing the error response and, per the HTTP specification, human-readable explanations.  Error responses are identified using the following "schema" URI: "urn:scim:api:messages:2.0:Error".    The following attributes are defined inclusion in a SCIM error response using a JSON body

NOTE: See this section of the SCIM API specification for details on the meanings of specific error codes.

Column
width50%

SCIM API

3.4 Deleting Resources

   In response to a successful delete, the server SHALL respond with successful HTTP status 204 (No Content).

3.10  HTTP Error Responses

Wiki Markup