Date: Fri, 29 Mar 2024 11:09:33 +0000 (UTC) Message-ID: <1785237975.7879.1711710573793@ip-10-10-7-29.ec2.internal> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_7878_4150431.1711710573790" ------=_Part_7878_4150431.1711710573790 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
As of Q3 2015, the CIFER Project has been transitioned to the TIER-Data Structures and APIs Working Group.
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
JF: There are many equally valid auth methods
SCIM API
2. Authentication and Authorization=
span>
The SCIM protocol does not defi=
ne a scheme for authentication and authorization therefore implementers are=
free to choose mechanisms appropriate to their use cases. The choice of au=
thentication mechanism will impact interoperability. It is RECOMMENDED that=
clients be implemented in such a way that new authentication schemes can b=
e deployed. Implementers SHOULD support existing authentication/authorizati=
on schemes. In particular, OAuth2[RFC6750] is RECOMMENDED. Appropriate secu=
rity considerations of the selected authentication and authorization scheme=
s SHOULD be taken. Because this protocol uses HTTP response status codes as=
the primary means of reporting the result of a request, servers are advise=
d to respond to unauthorized or unauthenticated requests using the 401 resp=
onse code in accordance with section 10.4.2 of Section 10.4.2 [RFC2616].
All examples assume OAuth2 bearer tok= en [RFC6750]; e.g.,
GET /Users/2819c223-7f76-453a-919d-41=
3861904646 HTTP/1.1
Host: exam=
ple.com
Authorization: Bearer =
h480djs93hd8
The context of the request (i.e. the = user for whom data is being requested) MUST be inferred by service provider= s.
CIFER Framework
5.1.1. URI syntax
A major version of a particular CIFER API must be indicated in the URI p= ath (for example, "/v2/"). A major version will differentiate incompatible = representations, parameters or headers. A major version change is also indi= cated 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).
JF: SCIM language seems OK
SCIM API
3.11. API Versioning
The Base URL MAY be appended with a version identifier as a separate seg= ment in the URL path. At this time of this specification, the identif= ier is 'v2'. If specified, the version identifier MUST appear in the = URL path immediately preceding the resource endpoint and conform to the fol= lowing scheme: the character 'v' followed by the desired SCIM version numbe= r; e.g., a version 'v2' User request is specified as /v2/Users. When = specified service providers MUST perform the operation using the desired ve= rsion or reject the request. When omitted service providers SHOULD pe= rform the operation using the most recent SCIM protocol version supported b= y the service provider.
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.
Consider adopting SCIM language
SCIM API
3. API
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 SHO= ULD 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.=
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 sp= ecify the desired response data format via an HTTP Accept Header; e.g.,"Acc= ept: 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/j= son" for [RFC7159]. The format defaults to JSON if no format is speci= fied.
CIFER Framework
5.1.3. Data and field formats
1. Character set is Unicode, encoded as UTF-8.
Consider adopting SCIM language
SCIM API
3.6. Data Input/Output Formats
Servers MUST accept requests and respond with JSON structur=
ed
responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the =
default
encoding format.
CIFER Framework
5.1.3. Data and field formats
2. Timestamp representations will comply with ISO 8601. For example: 201= 2-10-04T03:10:14.123Z
Consider adopting SCIM language
SCIM Core Schema
3.1.5. DateTime
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].
Values represented in JSON MUST conform to the XML constraints above and= are represented as a JSON String per Section 7 [RFC7159].
CIFER Framework
5.1.3. Data and field formats
3. Durations also comply with ISO 8601, For example: P1.81S
SCIM API
No mention of durations or time intervals
CIFER Framework
5.1.3. Data and field formats
4. Field names are camelCase (including acronyms), e.g. "selfUri"
5. Where there is discretion enum and other fixed field values should be c=
amelCase.
JF: We could go with SHOULDs in 4 and 5
SCIM Core Schema
3. SCIM Schema Structure
Attribute names SHOULD be camelCased.
No mention of rules over string-typed attribute values
CIFER Framework
5.1.3. Data and field formats
6. Field names must start with a letter. They can contain upper/lower le= tters, numbers and underscores.
Consider adopting SCIM language
SCIM Core Schema
3. SCIM Schema Structure
Attribute names MUST conform to the following ABNF [RFC5234 ] rules:
ATTRNAME =3D ALPHA *(nameChar)
nameChar =3D "-" / "_" / DIGIT / ALPHA
CIFER Framework
5.1.3. Data and field formats
7. Field types must stay consistent within a major version.
SCIM
No guidance on what kinds of changes should lead to a new major vers= ion number
CIFER Framework
5.1.3. Data and field formats
8. Objects are identified by uri
JF: We could expand our commentary., but
SCIM Core Schema
5.1. Common Schema Attributes
id
Unique identifier for the SCIM resource as defined by the service provid= er. Each representation of the resource MUST include a nonempty "id" value.= This identifier MUST be unique across the service provider=E2=80=99s entir= e set of resources. It MUST be a stable, non-reassignable identifier that d= oes not change when the same resource is returned in subsequent requests. T= he value of the "id" attribute is always issued by the service provider and= MUST never be specified by the client. bulkId: is a reserved keyword and M= UST NOT be used in the unique identifier. REQUIRED and has a mutability of = "readOnly".
CIFER Framework
5.2.1 Resource references
CIFER APIs accommodate large responses by recognizing full and partial r= esources.
1. A full resource, where the response is the full resource requested, m= ust be identified by a URI only, not by query string or fragment
2. A partial resource, like a response that is better served across page= s, is identified by a URI that contains at least one additional query strin= g 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 multipl= e resources.
Consider referencing OpenSearch protocol re pagination parameters and be= havior
SCIM API
3.2.2.4 Pagination
Pagination parameters can be used together to "page through" large numbe= rs of resources so as not to overwhelm the client or service provider. Pagi= nation is not session based hence clients SHOULD never assume repeatable re= sults. For example, a request for a list of 10 resources beginning with a s= tartIndex 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 O= penSearch Protocol [OpenSearch].
CIFER Framework
5.2.2 Request Methods
1. The request method of POST [may be] overridden by a header (see heade= r options below). NOTE: see section 5.2 3 below for details
2. A PUT request need not specify all attributes.
JF: We have to consider missing attributes if we allow new attributes wi= thout re-versioning.
PATCH, if logically a set of PUT/DELETE, is OK
SCIM API
3. API
PUT Modifies a resource with a complete, client specified resource (repl= ace).
PATCH Modifies a resource with a set of client specified changes (partia= l update).
NOTE: See also the substantial section 3.3 and its subsections on mo= difying resources
CIFER Framework
5.2.2. Request methods
3. Searches return resource URIs and default resource attributes.
4. Searches may specify paging options by query string parameters
Consider adopting SCIM language on queries (3.2.2 and 3.2.3)
SCIM API
3.2. Retrieving Resources
"User" and "Group" resources are retrieved via opaque, unique URLs or vi= a Query. Service providers MAY choose to respond with a sub-set of re= source attributes, though MUST minimally return the resource id and meta at= tributes.
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, so= rt, and paginate response results. The operations are specified by ad= ding query parameters to the resource's endpoint. Service providers M= AY support additional query parameters not specified here, and Providers SH= OULD 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 usi= ng the HTTP POST verb combined with the '/.search' path extension. The incl= usion of '/.search' on the end of a valid SCIM endpoint SHALL be used to in= dicate the HTTP POST verb is intended to be a query operation.
...
The following attributes are defined for search requests:
CIFER Framework
5.2.3. Header Options
1. The request method of POST may be overridden by the header:
JF: A method override is sometimes necessary
SCIM API
Appendix C. Change log
Draft 05 - PH - Revisions based on the following tickets:
65 - Removed X-HTTP-Method-Override support
CIFER Framework
5.2.3. Header Options
2. XML representation may requested by header:
SCIM API
3. API
Responses are returned in the body of the HTTP response, formatte= d as JSON.
NOTE: SCIM has no provision for returning XML responses
CIFER Framework
5.2.3. Header Options
3. Use of ETag and If-Match:
Review in light of SCIM approach
SCIM API
3.12. Versioning Resources
The API supports resource versioning via standard HTTP ETag= s 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.&n= bsp; When supported SCIM ETags MUST be specified as an HTTP header and SHOU= LD be specified within the 'version' attribute contained in the resource's = 'meta' attribute.
...
If the service providers supports versioning of resources the cli= ent MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH o= perations to ensure that the requested operation succeeds only if the suppl= ied ETag matches the latest service provider resource; e.g., If-Match: W/"e= 180ee84f0671b1"
CIFER Framework
5.2.3. Header Options
4. A client may request to "act as" another user via a header:
SCIM API
NOTE: SCIM does not have a concept of a=
uthorization of proxy actors such as that represented by the X-CIFER-Act-As=
header
CIFER Framework
5.2.4. Query String Options
1. Requests may specify field filters on returned resources.
Review in light of SCIM approach
SCIM API
3.2.2. List/Query Resources
SCIM defines a standard set of operations that can be used to filter, so= rt, and paginate response results. The operations are specified by ad= ding query parameters to the resource's endpoint. Service providers M= AY support additional query parameters not specified here, and Providers SH= OULD 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 usi= ng the HTTP POST verb combined with the '/.search' path extension. The incl= usion of '/.search' on the end of a valid SCIM endpoint SHALL be used to in= dicate the HTTP POST verb is intended to be a query operation.
...
The following attributes are defined for search requests:
CIFER Framework
5.2.4. Query String Options
2. Requests for large resources, e.g. group membership, may specify pagi= ng parameters
SCIM API
3.2.2.4 Pagination
Pagination parameters can be used together to "page through" large numbe= rs of resources so as not to overwhelm the client or service provider. Pagi= nation is not session based hence clients SHOULD never assume repeatable re= sults. For example, a request for a list of 10 resources beginning with a s= tartIndex 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 O= penSearch Protocol [OpenSearch].
CIFER Framework
5.2.4. Query String Options
3. Boolean parameters are generously interpreted
SCIM API
3.2.2.2. Filtering
Filtering is OPTIONAL.
compValue =3D false / null / true / number / string
&n=
bsp; ; 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
CIFER Framework
5.2.4. Query String Options
4. A client may request a pretty-printed response with the query string,= "indent=3Dtrue"
SCIM API
NOTE: SCIM does not support client requ=
ests for pretty-printed responses.
CIFER Framework
5.2.4. Query String Options
5. Unexpected Query String parameters will be ignored.
SCIM API
NOTE: Primarily because SCIM works only with defined schema and exte= nsions, unexpected query string parameters are not supported.
CIFER Framework
5.3. Request Methods
...
The framework does not specify these root and directory representations, e=
xcept that they follow the general request and response guidelines.
SCIM API
3.2.2.1. Query Endpoints
A server MAY support searches against the server root (e.g.= "/"). A search against a server root indicates that ALL resour= ces within the server SHALL be included subject to filtering. A filte= r expression using "meta.resourceType" MAY be used to restrict results to o= ne or more specific resource types (e.g. "User" ).
CIFER Framework
5.4.1 Response structure
Resources are returned along with metadata about the resource and metada= ta about the
response (see JSON examples that follow)
1. Resources are wrapped in an object which contains:
1. resource: The actual resource for the request.
2. resourceMetadata: metadata about the resource.
fields as appropriate to the resource
lastModified: timestamp when the resource was modifie=
d
selfUri: URI to the current resource.
ETag, or equivalent, for resources that can be replaced=
, ...
3. responseMetadata: metadata about this particular r= esponse
responseTimestamp:
responseTime: time that the server took in processing t=
his request
requestCommentary: freeform text about the request that=
the server processed (for debug)
httpStatusCode: response status as an HTTP status code.=
serverVersion: major.minor server version number
paging parameters
pageLimit
pageOffset
sortField
pageOffsetValue
sortOrder
Review metadata approach
SCIM Core Schema
5.1 Common Schema Attributes
meta A complex attribute containing resource metadata. All s= ub-attributes are OPTIONAL
CIFER Framework
5.4.2. Response Codes
JF: We may want to include some content on a successful DELETE, then the= response would be 200.
SCIM API
3.4 Deleting Resources
In response to a successful delete, the server SHALL respon= d with successful HTTP status 204 (No Content).
3.10 HTTP Error Responses
The SCIM Protocol uses the response status codes defined in= HTTP Section 6 [RFC7231] to indicate operation success or failure. I= n addition to returning a HTTP response code implementers MUST return the e= rrors in the body of the response in the client requested format containing= the error response and, per the HTTP specification, human-readable explana= tions. Error responses are identified using the following "schema" UR= I: "urn:scim:api:messages:2.0:Error". The following attributes are de= fined 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.