Subject: [Id-event] SCIM Use Cases for SECEVENTS

From: Phil Hunt <[email-masked]>
Date: Tue, 18 Apr 2017 11:27:35 -0700

All,

Dick asked me if I would enumerate the SCIM use cases.  Here is the SCIM case. Happy to put these somewhere in a working group document.

I mentioned some of this at the recent IETF98 Chicago meeting. See: https://www.ietf.org/proceedings/98/slides/slides-98-secevent-use-cases-00.pdf <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_proceedings_98_slides_slides-2D98-2Dsecevent-2Duse-2Dcases-2D00.pdf&d=DwMFaQ&c=RoP1YumCXCgaWHvlZYR8PQcxBKCX5YTpkKY057SbK10&r=JBm5biRrKugCH0FkITSeGJxPEivzjWwlNKe4C_lLIGk&m=kg_cVvmAeJRx1Y7Kp0Shgl3O1MPg4EOwXIyEG0PqiyY&s=KKDUOQp8lUPGBHZ3rfGM38eYeZp7Qy0zEpxIGY8NgcE&e=>

The slides below (from the presentation) show provisioning from enterprise to cloud and to applications. 

Background Info on SCIM:

SCIM is an extensible provisioning protocol meant for provisioning of identities across security domains (such as an enterprise to a cloud provider). This can be to a cloud directory or direct to cloud host applications.  RFC7643 defines attribute types, mutability, format, composition etc and defines Users and Groups as core objects typically supported in most SCIM providers.  SCIM has an extension model that allows:
* New resource types that can be defined both informally and formally.
* Extensions to existing objects -  e.g. allowing service providers to have domain specific attributes without fear of collision or inter-op issues with other service providers.

Typically a SCIM client makes RESTful calls to a service provider’s endpoint to:
* Query for users and groups using HTTP GET or HTTP POST
* Retrieve specific resources (such as users) using HTTP GET
* Create new resources (eg. Users) using HTTP POST
* Replace a resource using HTTP PUT
* Patch a resource using HTTP PATCH
* Delete a resource using HTTP DELETE

In the real world, each security domain operates independently and a need arises to send signals back to a client domain known as triggers. See “triggers” definition in the SCIM Use Case specification (https://tools.ietf.org/html/rfc7642 <https://tools.ietf.org/html/rfc7642>).  So for example if a change occurs within a cloud provider that may be of interest to an on-premise enterprise identity management system, an event trigger can be sent to the enterprise to allow it to reconcile the cloud based change with the on-premise information. This acts as a complement to REST by enabling to independent entities to both transfer and co-ordinate state across independently managed domains that have slightly differing information about shared subjects.
  
Some other docs…
* Craig McMurtry did some work on polling. There are some interesting recovery features in there:
https://tools.ietf.org/html/draft-mcmurtry-scim-polling-01 <https://tools.ietf.org/html/draft-mcmurtry-scim-polling-01>
* A somewhat out of date description of SCIM events is defined here: https://tools.ietf.org/html/draft-hunt-idevent-scim-00 <https://tools.ietf.org/html/draft-hunt-idevent-scim-00>. This draft needs to be substantially re-written given the new secevent-token draft.

When the SCIM WG was set to discuss re-chartering in Tokyo, there was significant interest shown to broaden the specification scope to include work from OpenID (e.g. Logout, RISC, and HEART).  This work was re-directed at the id-events mailing list was formed to explore a unified proposal. The current set-token and distribution drafts evolved from these discussions the scope was broadened to encompass RISC and other related initiatives to avoid defining even more pub-sub style protocols. 

High-Level Network and Protocol Relationships Requirements:

In the SCIM WG we had discussed that transmission (now called data-plane or stream) can have much simpler semantics and error conditions and thus did not need specification of attribute types, defaulting, filters, etc.  This was important because we had the following use cases for transmission:
* PUSH delivery via HTTP POST (the generally preferred ideal solution)
* POLLING (to enable delivery across firewalls) using HTTP GET
* PUSH delivery via messaging systems like APNS, GMS, SMS, etc - many of these had to do with provisioning and entitlement signals for mobile applications (e.g. WebEx). I’m not sure the nature of these, but they seem focused on auto provisioning of clients so they know how to connect to their service providers and gain correct entitlements (Morteza has more info on this).

Provisioning and monitoring of status for Streams was intended as an extension to the SCIM specifications by defining the Stream resource type and any necessary resources needed to define contents of a feed (event types and subjects).

Directory and Application Provisioning Relationships

As I mentioned in the Chicago meeting, the organizational relationships for these types of connections can be seen as shown in the diagrams above:
*  Enterprise Directory to Cloud “Directory"
*  Cloud “Dir” to Cloud “Dir"
*  Enterprise or Cloud to Cloud Application
*  Enterprise or Cloud to Mobile Application

In the diagrams above, an enterprise directory is typically (but not always) legacy-LDAP.  In the cloud, a directory is non-specific and can mean any centralized profile store (e.g. Google Dir, Azure Directory/OpenGraph, SCIM Directory, etc). Important:  While LDAP remains the center of administrative control, it is important to note that cloud directories and applications hold significantly more PII than enterprise directories. There is a lot of intersectin, but informationally it is mainly the need for governance and control that links these systems.

As with an enterprise directory, a cloud directory is often shared by multiple applications. Cloud directories not only contain entitlement information but now also contain CRM data, contact, credentials, personalization and localization data, social network data, etc (the list goes on). While some cloud providers centralize others are tenancy structured with different directory endpoints per tenancy (e.g. Oracle).

SCIM Security Model

SCIM follows normal authentication and authorization practices for HTTP (See Sections 2 and 7 of RFC7644). In typical deployed cases, access to SCIM endpoints is managed by OAuth authorization in both cross-domain provisioning, delegated administration, and self-service applications. Many integrators also support basic auth, and TLS mutual auth or even kerberos.  SCIM is often access in a couple of ways:
* Self-service (e.g. as facilitated via a /Me endpoint)
* Administrative - where an administrative credential has access to groups of objects they are entitled to administer.  

In SCIM use cases we expect to expose the Stream ResourceType configuration endpoints to be available administrators as well as to the delegated server clients that need to register and configure their data Streams.  The Streams themselves may be limited to the authorized entities assigned to exchange information. A single administrator managing multiple tenancies and multiple event family relationships (e.g. Logout, Token Revocation, Provisioning, and RISC) should be able to update and review the operational status of multiple Streams using GET calls to the Stream configuration endpoint via the control plane (SCIM).

Note that while in many cases SCIM will exchange events with applications, it will more often tend to be directory to directory based. This means that SCIM events will likely have a different, though overlapping pattern of exchange as compared to logout or token revocations such as between an Identity Provider and its Relying Parties.

Control Plane Assumptions

The SCIM WG in re-using SCIM as the control plane had assumed the following is already defined:
*  Handling of omitted attributes (defaulted vs. null etc)
*  Handling of differences in attributes/schemas between implementations
*  Ability of service provider to override or modify client asserted values
*  Identifier stability and referential integrity
*  Querying of subjects using various identifiers both simple and composite (e.g. issuer and subject)
*  Ability to add and remove users from large groups
*  General error handling and processing rules

Security Considerations

PII confidentiality - Querying using PII information comes with some privacy concerns when using HTTP GET. The problem is that the HTTP specifications do not allow for payloads on an HTTP GET - thus GET based queries as to be passed as part of the URL. If queries contain PII (most will in the case of RISC, then there are security issues (e.g. leakage via audit logs and browser histories) relating to passing filter terms that contain PII in URLs. See RFC7642 Security Considerations, section 7.5.2. 

Scale - One of the concerns the SCIM WG had when developing SCIM was the notion that Groups (e.g. a group of users) will tend to get very big at Internet scale. The bigger a Group gets, the more expensive it is to enumerate. With a high change rate it quickly become impractical to do a simple PUT to replace an entire Group object due to the number of updaters. SCIM implementers often do a number of things:
* Severely restricts what clients are actually authorized to return large objects (million member groups)
* Set access policy to allow search filters that confirm membership but avoid returning the members attribute (to avoid enumeration of all values).
*Use HTTP PATCH (a derivative of JSON Patch) to remove or add specific subjects without having to know the entire contents (e.g. the group).

Use Case Scenarios

The following use cases are expressed in terms of the direction of flow of events.  In typical SCIM cases, there is only 1-way event exchange (see diagrams above). Typical usage of events is to act as a “trigger” (see RFC7642) to let a receiver know that an event has occurred in the transmitter's domain that may require action on the part of the receiver.  Events can be simple resource changed events, to higher level account status and change events similar to RISC.

Scenario 1[P0]: Cloud to Enterprise PUSH and Cloud to Cloud PUSH

Pre-conditions:
* The receiver already has SCIM access to the event transmitter. This includes HTTP credentials and an enpoint.
* The receivers and transmitter will agree OOB on JWT security requirements including using of signing and encryption keys to be documented in Stream configuration

Stream Creation Flow:
1.  Receiver using their SCIM credential accesses the transmitters SCIM endpoint and creates a Stream resource configuration e.g.:
POST /Streams
Host: scim.bighost.com
Authorization: Bearer h480djs93hd8 
{ "receiverId":"<client-id>","method":"webCallBack", "receiverUri":"https://set.example.com/events/", "aud":"<client-id>", "type":"SCIM", "receiverJwkUri":"<receiver's public key url>", "authorization":"<btoken|BasicAuth>"}
If the Transmitter does not have an HTTP credential to send events, the receiver should include one in its registration POST request or negotiate one out-of-band.

Note, in the stream configuration there is likely a definition as to what types of events (event families) and which subjects constitute the feed.  In SCIM this will likely be a group of objects, or filter condition such as “roles” eq ”CRM_Users”.  This is likely based on the relationship between parties that determines which entities are provisioned between domains.

Upon successful creation of the stream, the transmitter responds to the receiver with:
HTTP/1.1 201 Created
Location: https://events.bighost.com/Streams/2819c223-7f76-453a
{ "receiverId":"<client-id>","method":"webCallBack", "receiverUri":"https://set.example.com/events/", "aud":"<client-id>", "type":"SCIM", "receiverJwkUri":"<receiver's public key url>", "authorization":"<btoken|BasicAuth>”,”status”:”on"}

Stream Verification:
During the initial stream creation request and at any point the transmitter deems appropriate (e.g. as a ping), the transmitter verifies configuration by sending a verification event to the receiver that requires the receiver to prove that the receiver:
* is willing accept the event
* is able to parse the event - especially if encrypted

If the receiver does not respond, returns an error or is unable to parse the message, the Stream configuration “status” is set to “failed” with an appropriate error condition to assist in diagnosis.

If the verify succeeds, the stream state is set to “on” and the transmitter may then transmit events based on the feed/stream definition. 

Delivery:
Delivery is accomplished by doing a simple HTTP POST to the registered endpoint of the receiver. The payload of the POST is application/jwt and contains a single JWT (which is actually a SET).

Before responding with a 2xx success message, the receiver should ensure it was able to read and validate the SET. If the transmitter receives a 2xx response, the transmitter may assume the event was successfully delivered.  

A set of Status 400 error conditions are defined which the receiver can use to indicate various JWT validation conditions.

Scenario 2[P0]: Cloud to Enterprise via POLLING and Cloud to Cloud POLLING

Pre-conditions:
* The receiver already has SCIM access to the event transmitter. This includes HTTP credentials and an enpoint.
* The receivers and transmitter will agree OOB on JWT security requirements including using of signing and encryption keys to be documented in Stream configuration

Stream Creation Flow:
1.  Receiver using their SCIM credential accesses the transmitters SCIM endpoint and creates a Stream resource configuration e.g.:
POST /Streams
Host: scim.bighost.com
Authorization: Bearer h480djs93hd8 
{ "receiverId":"<client-id>","method”:"POLLING”, "aud":"<client-id>", "type":"SCIM", "receiverJwkUri":"<receiver's public key url>"}
It is assumed, but may not always be true. that the POLLING receiver can simply use their SCIM credential to perform HTTP GETs to the polling endpoint. Additional parameters will liekly need to be defined to control polling rate, number of events in a message, etc.

Note, in the stream configuration there is likely a definition as to what types of events (event families) and which subjects constitute the feed.  In SCIM this will likely be a group of objects, or filter condition such as “roles” eq ”CRM_Users”.  This is likely based on the relationship between parties that determines which entities are provisioned between domains.

Upon successful creation of the stream, the transmitter responds to the receiver with:
HTTP/1.1 201 Created
Location: https://events.bighost.com/Streams/2819c223-7f76-453a
{ "receiverId":"<client-id>","method”:"POLLING", "receiverUri":"https://set.bighost.com/Events/2819c223-7f76-453a", "aud":"<client-id>", "type":"SCIM", "receiverJwkUri":"<receiver's public key url>”,”status”:”on"}

Note that in the above response, the transmitter has indicated to the receiver where to poll for events by setting a value for “receiverUri”. This endpoint does not need to be SCIM compliant and can be a generic (e.g. shared by all polliers) endpoint such as https://events.bighost.com.

Stream Verification:
During the initial stream creation request and at any point the transmitter deems appropriate (e.g. as a ping), the transmitter verifies configuration by sending a verification event to the receiver that requires the receiver to prove that the receiver:
* is willing pick-up the event
* is able to parse the event - especially if encrypted

If the receiver does not pick up and acknowledge the event proprerly, the Stream configuration “status” is set to “failed” with an appropriate error condition to assist in diagnosis.

If the verify succeeds, the stream state is set to “on” and the receiver may then use HTTP GET to poll for events based on the feed/stream definition. 

Delivery:
Delivery is accomplished by a receiver periodically performing an HTTP GET to the endpoint returned in the Stream registration response. The response type is application/json or applications/secevents+json and looks something like:

{
"sets":{
"4d3559ec67504aaba65d40b0363faad8":
  "eyJhbGciOiJub25lIn0
   .
   e3sgIAogICJqdGkiOiAiNGQzNTU5ZWM2NzUwNGFhYmE2NWQ0MGIwMzYzZmFhZDgiLAog
   ICJpYXQiOiAxNDU4NDk2NDA0LAogICJpc3MiOiAiaHR0cHM6Ly9zY2ltLmV4YW1wbGUu
   Y29tIiwgIAogICJhdWQiOiBbCiAgICJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vRmVl
   ZHMvOThkNTI0NjFmYTViYmM4Nzk1OTNiNzc1NCIsCiAgICJodHRwczovL3NjaW0uZXhh
   bXBsZS5jb20vRmVlZHMvNWQ3NjA0NTE2YjFkMDg2NDFkNzY3NmVlNyIKICBdLCAgCiAg
   CiAgImV2ZW50cyI6IHsKICAgICJ1cm46aWV0ZjpwYXJhbXM6c2NpbTpldmVudDpjcmVh
   dGUiOiB7CiAgICAgICJyZWYiOgogICAgICAgICJodHRwczovL3NjaW0uZXhhbXBsZS5j
   b20vVXNlcnMvNDRmNjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsCiAgICAgICJhdHRyaWJ1
   dGVzIjpbImlkIiwgIm5hbWUiLCAidXNlck5hbWUiLCAicGFzc3dvcmQiLCAiZW1haWxz
   Il0KICAgIH0KICB9Cn0",
  "<nextJti>":"<nextJwt>"
 },
 "since":1458496025
}

In the above JSON object is a JSON attribute “sets” whose value is a JSON object that contains a set of JSON attributes that correspond to each event’s JTI value. the value for each attribute is the actual encoded SET.

In addition to the “sets” attribute, a “since” attribute indicates the timestamp of either the last event previously transmitted or potentially oldest event in the current payload (To be discussed).

In order to acknowledge receipt, the receiver must succesfully parse each message and respond by doing an HTTP POST back to the events endpoint the following JSON structure:
{
  “accepts”:[
    “39e48e70e9f84d90b5fdbf2fbd826219”,
    “8e1ed13b871547ffa332f7027a0fdd91”,
    “0a02c62529e34541a8b3c5c7941fa545”
  ]
  "setErrs":{
    "3d0c3cf797584bd193bd0fb1bd4e7d30":{
      "err":"dup",
      "description":"SET already received. Ignored."
    }
  }
} 

In the payload above the receiver indicates which SET event JTIs have been accepted, and which SETs had errors using “accepts” and “setErrs”.

It is expected that because most errors are due to JWT crypto configuration errors, that most responses will tend to be all errors or all accepts.  

If a transmitter receives what it deems an unrecoverable error, or a receiver fails to poll for events, the transmitter can set the stream state to “failed” with an appropriate error indicator.

Scenario 3[P2]: Cloud to Mobile Application PUSH

This scenario is a hybrid of scenario 1 and 2. The scenario uses mobile message delivery services (APNS, GMS, SMS) to deliver events.  Typically a stream has only one subject in its feed. The events are used to notify client applications about changes to entitlements, or other configuration (e.g. new tenancy endpoints)that might be useful to user experience. 

As in the polling method in Scenario 2, to acknowledge events, the mobile app will need to use the POST (as defined in Scenario 2) to acknowledge SET delivery.  To be discussed, this might not be necessary if assured delivery is not required.

Phil

Oracle Corporation, Identity Cloud Services Architect & Standards
@independentid
www.independentid.com <http://www.independentid.com/>[email-masked] <mailto:[email-masked]>

---

From: Dick Hardt <[email-masked]>
Date: Tue, 18 Apr 2017 11:36:11 -0700

Thanks Phil!

On Tue, Apr 18, 2017 at 11:27 AM, Phil Hunt <[email-masked]> wrote:

> All,
>
> Dick asked me if I would enumerate the SCIM use cases.  Here is the SCIM
> case. Happy to put these somewhere in a working group document.
>
> I mentioned some of this at the recent IETF98 Chicago meeting. See:
> https://www.ietf.org/proceedings/98/slides/slides-
> 98-secevent-use-cases-00.pdf
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_proceedings_98_slides_slides-2D98-2Dsecevent-2Duse-2Dcases-2D00.pdf&d=DwMFaQ&c=RoP1YumCXCgaWHvlZYR8PQcxBKCX5YTpkKY057SbK10&r=JBm5biRrKugCH0FkITSeGJxPEivzjWwlNKe4C_lLIGk&m=kg_cVvmAeJRx1Y7Kp0Shgl3O1MPg4EOwXIyEG0PqiyY&s=KKDUOQp8lUPGBHZ3rfGM38eYeZp7Qy0zEpxIGY8NgcE&e=>
>
> *Background Info on SCIM:*
>
> SCIM is an extensible provisioning protocol meant for provisioning of
> identities across security domains (such as an enterprise to a cloud
> provider). This can be to a cloud directory or direct to cloud host
> applications.  RFC7643 defines attribute types, mutability, format,
> composition etc and defines Users and Groups as core objects typically
> supported in most SCIM providers.  SCIM has an extension model that allows:
> * Extensions to existing objects -  e.g. allowing service providers to
> have domain specific attributes without fear of collision or inter-op
> issues with other service providers.
>
> In the real world, each security domain operates independently and a need
> arises to send signals back to a client domain known as triggers. See
> “triggers” definition in the SCIM Use Case specification (
> https://tools.ietf.org/html/rfc7642).  So for example if a change occurs
> within a cloud provider that may be of interest to an on-premise enterprise
> identity management system, an event trigger can be sent to the enterprise
> to allow it to reconcile the cloud based change with the on-premise
> information. This acts as a complement to REST by enabling to independent
> entities to both transfer and co-ordinate state across independently
> managed domains that have slightly differing information about shared
> subjects.
>
> Some other docs…
> https://tools.ietf.org/html/draft-mcmurtry-scim-polling-01
> * A somewhat out of date description of SCIM events is defined here:
> https://tools.ietf.org/html/draft-hunt-idevent-scim-00. This draft needs
> to be substantially re-written given the new secevent-token draft.
>
> When the SCIM WG was set to discuss re-chartering in Tokyo, there was
> significant interest shown to broaden the specification scope to include
> work from OpenID (e.g. Logout, RISC, and HEART).  This work was re-directed
> at the id-events mailing list was formed to explore a unified proposal. The
> current set-token and distribution drafts evolved from these discussions
> the scope was broadened to encompass RISC and other related initiatives to
> avoid defining even more pub-sub style protocols.
>
> *High-Level Network and Protocol Relationships Requirements:*
>
> In the SCIM WG we had discussed that transmission (now called data-plane
> or stream) can have much simpler semantics and error conditions and thus
> did not need specification of attribute types, defaulting, filters, etc.
> This was important because we had the following use cases for transmission:
> * PUSH delivery via messaging systems like APNS, GMS, SMS, etc - many of
> these had to do with provisioning and entitlement signals for mobile
> applications (e.g. WebEx). I’m not sure the nature of these, but they seem
> focused on auto provisioning of clients so they know how to connect to
> their service providers and gain correct entitlements (Morteza has more
> info on this).
>
> Provisioning and monitoring of status for Streams was intended as an
> extension to the SCIM specifications by defining the Stream resource type
> and any necessary resources needed to define contents of a feed (event
> types and subjects).
>
> *Directory and Application Provisioning Relationships*
>
> As I mentioned in the Chicago meeting, the organizational relationships
> for these types of connections can be seen as shown in the diagrams above:
> In the diagrams above, an enterprise directory is typically (but not
> always) legacy-LDAP.  In the cloud, a directory is non-specific and can
> mean any centralized profile store (e.g. Google Dir, Azure
> Directory/OpenGraph, SCIM Directory, etc). Important:  While LDAP remains
> the center of administrative control, it is important to note that cloud
> directories and applications hold significantly more PII than enterprise
> directories. There is a lot of intersectin, but informationally it is
> mainly the need for governance and control that links these systems.
>
> As with an enterprise directory, a cloud directory is often shared by
> multiple applications. Cloud directories not only contain entitlement
> information but now also contain CRM data, contact, credentials,
> personalization and localization data, social network data, etc (the list
> goes on). While some cloud providers centralize others are tenancy
> structured with different directory endpoints per tenancy (e.g. Oracle).
>
> *SCIM Security Model*
>
> SCIM follows normal authentication and authorization practices for HTTP
> (See Sections 2 and 7 of RFC7644). In typical deployed cases, access to
> SCIM endpoints is managed by OAuth authorization in both cross-domain
> provisioning, delegated administration, and self-service applications. Many
> integrators also support basic auth, and TLS mutual auth or even kerberos.
> SCIM is often access in a couple of ways:
> * Administrative - where an administrative credential has access to groups
> of objects they are entitled to administer.
>
> In SCIM use cases we expect to expose the Stream ResourceType
> configuration endpoints to be available administrators as well as to the
> delegated server clients that need to register and configure their data
> Streams.  The Streams themselves may be limited to the authorized entities
> assigned to exchange information. A single administrator managing multiple
> tenancies and multiple event family relationships (e.g. Logout, Token
> Revocation, Provisioning, and RISC) should be able to update and review the
> operational status of multiple Streams using GET calls to the Stream
> configuration endpoint via the control plane (SCIM).
>
> Note that while in many cases SCIM will exchange events with applications,
> it will more often tend to be directory to directory based. This means that
> SCIM events will likely have a different, though overlapping pattern of
> exchange as compared to logout or token revocations such as between an
> Identity Provider and its Relying Parties.
>
> *Control Plane Assumptions*
>
> *Security Considerations*
>
> PII confidentiality - Querying using PII information comes with some
> privacy concerns when using HTTP GET. The problem is that the HTTP
> specifications do not allow for payloads on an HTTP GET - thus GET based
> queries as to be passed as part of the URL. If queries contain PII (most
> will in the case of RISC, then there are security issues (e.g. leakage via
> audit logs and browser histories) relating to passing filter terms that
> contain PII in URLs. See RFC7642 Security Considerations, section 7.5.2.
>
> Scale - One of the concerns the SCIM WG had when developing SCIM was the
> notion that Groups (e.g. a group of users) will tend to get very big at
> Internet scale. The bigger a Group gets, the more expensive it is to
> enumerate. With a high change rate it quickly become impractical to do a
> simple PUT to replace an entire Group object due to the number of updaters.
> SCIM implementers often do a number of things:
> * Set access policy to allow search filters that confirm membership but
> avoid returning the members attribute (to avoid enumeration of all values).
> *Use HTTP PATCH (a derivative of JSON Patch) to remove or add specific
> subjects without having to know the entire contents (e.g. the group).
>
> *Use Case Scenarios*
>
> The following use cases are expressed in terms of the direction of flow of
> events.  In typical SCIM cases, there is only 1-way event exchange (see
> diagrams above). Typical usage of events is to act as a “trigger” (see
> RFC7642) to let a receiver know that an event has occurred in the
> transmitter's domain that may require action on the part of the receiver.
> Events can be simple resource changed events, to higher level account
> status and change events similar to RISC.
>
> *Scenario 1[P0]: Cloud to Enterprise PUSH and Cloud to Cloud PUSH*
>
> Pre-conditions:
> * The receiver already has SCIM access to the event transmitter. This
> includes HTTP credentials and an enpoint.
> * The receivers and transmitter will agree OOB on JWT security
> requirements including using of signing and encryption keys to be
> documented in Stream configuration
>
> Stream Creation Flow:
> 1.  Receiver using their SCIM credential accesses the transmitters SCIM
> endpoint and creates a Stream resource configuration e.g.:
>
> POST /Streams
>
> Host: scim.bighost.com
>
> { "receiverId":"<client-id>","method":"webCallBack", "receiverUri
> ":"https://set.example.com/events/", "aud":"<client-id>", "type":"SCIM", "
> receiverJwkUri":"<receiver's public key url>", "authorization":"<btoken|
> BasicAuth>"}
> If the Transmitter does not have an HTTP credential to send events, the
> receiver should include one in its registration POST request or negotiate
> one out-of-band.
>
> Note, in the stream configuration there is likely a definition as to what
> types of events (event families) and which subjects constitute the feed.
> In SCIM this will likely be a group of objects, or filter condition such as
> “roles” eq ”CRM_Users”.  This is likely based on the relationship between
> parties that determines which entities are provisioned between domains.
>
> { "receiverId":"<client-id>","method":"webCallBack", "receiverUri
> ":"https://set.example.com/events/", "aud":"<client-id>", "type":"SCIM", "
> receiverJwkUri":"<receiver's public key url>", "authorization":"<btoken|
> BasicAuth*>”,”status”:”on"*}
>
> Stream Verification:
> During the initial stream creation request and at any point the
> transmitter deems appropriate (e.g. as a ping), the transmitter verifies
> configuration by sending a verification event to the receiver that requires
> the receiver to prove that the receiver:
> If the receiver does not respond, returns an error or is unable to parse
> the message, the Stream configuration “status” is set to “failed” with an
> appropriate error condition to assist in diagnosis.
>
> If the verify succeeds, the stream state is set to “on” and the
> transmitter may then transmit events based on the feed/stream definition.
>
> Delivery:
> Delivery is accomplished by doing a simple HTTP POST to the registered
> endpoint of the receiver. The payload of the POST is application/jwt and
> contains a single JWT (which is actually a SET).
>
> Before responding with a 2xx success message, the receiver should ensure
> it was able to read and validate the SET. If the transmitter receives a 2xx
> response, the transmitter may assume the event was successfully delivered.
>
> A set of Status 400 error conditions are defined which the receiver can
> use to indicate various JWT validation conditions.
>
> *Scenario 2[P0]: Cloud to Enterprise via POLLING and Cloud to Cloud
> POLLING*
>
> Pre-conditions:
> * The receiver already has SCIM access to the event transmitter. This
> includes HTTP credentials and an enpoint.
> * The receivers and transmitter will agree OOB on JWT security
> requirements including using of signing and encryption keys to be
> documented in Stream configuration
>
> Stream Creation Flow:
> 1.  Receiver using their SCIM credential accesses the transmitters SCIM
> endpoint and creates a Stream resource configuration e.g.:
>
> POST /Streams
>
> Host: scim.bighost.com
>
> { "receiverId*":"<client-id>","method**”**:"*POLLING*”**, *"aud":"<client-id>",
> "type":"SCIM", "receiverJwkUri":"<receiver's public key url>"}
> It is assumed, but may not always be true. that the POLLING receiver can
> simply use their SCIM credential to perform HTTP GETs to the polling
> endpoint. Additional parameters will liekly need to be defined to control
> polling rate, number of events in a message, etc.
>
> Note, in the stream configuration there is likely a definition as to what
> types of events (event families) and which subjects constitute the feed.
> In SCIM this will likely be a group of objects, or filter condition such as
> “roles” eq ”CRM_Users”.  This is likely based on the relationship between
> parties that determines which entities are provisioned between domains.
>
> { "receiverId*":"<client-id>","method”:"*POLLING", "receiverUri":"https://
> set.bighost.com/Events/2819c223-7f76-453a", "aud":"<client-id>", "
> type":"SCIM", "receiverJwkUri":"<receiver's public key url*>”,*
> *”status”:”on"*}
>
> Note that in the above response, the transmitter has indicated to the
> receiver where to poll for events by setting a value for “receiverUri”.
> This endpoint does not need to be SCIM compliant and can be a generic (e.g.
> shared by all polliers) endpoint such as https://events.bighost.com.
>
> Stream Verification:
> During the initial stream creation request and at any point the
> transmitter deems appropriate (e.g. as a ping), the transmitter verifies
> configuration by sending a verification event to the receiver that requires
> the receiver to prove that the receiver:
> If the receiver does not pick up and acknowledge the event proprerly, the
> Stream configuration “status” is set to “failed” with an appropriate error
> condition to assist in diagnosis.
>
> If the verify succeeds, the stream state is set to “on” and the receiver
> may then use HTTP GET to poll for events based on the feed/stream
> definition.
>
> Delivery:
> Delivery is accomplished by a receiver periodically performing an HTTP GET
> to the endpoint returned in the Stream registration response. The response
> type is application/json or applications/secevents+json and looks something
> like:
>
> {
>
> "sets":{
>
> In the above JSON object is a JSON attribute “sets” whose value is a JSON
> object that contains a set of JSON attributes that correspond to each
> event’s JTI value. the value for each attribute is the actual encoded SET.
>
> In addition to the “sets” attribute, a “since” attribute indicates the
> timestamp of either the last event previously transmitted or potentially
> oldest event in the current payload (To be discussed).
>
> In order to acknowledge receipt, the receiver must succesfully parse each
> message and respond by doing an HTTP POST back to the events endpoint the
> following JSON structure:
>
> {
>
>   “accepts”:[
>
> In the payload above the receiver indicates which SET event JTIs have been
> accepted, and which SETs had errors using “accepts” and “setErrs”.
>
> It is expected that because most errors are due to JWT crypto
> configuration errors, that most responses will tend to be all errors or all
> accepts.
>
> If a transmitter receives what it deems an unrecoverable error, or a
> receiver fails to poll for events, the transmitter can set the stream state
> to “failed” with an appropriate error indicator.
>
> *Scenario 3[P2]: Cloud to Mobile Application PUSH*
>
> This scenario is a hybrid of scenario 1 and 2. The scenario uses mobile
> message delivery services (APNS, GMS, SMS) to deliver events.  Typically a
> stream has only one subject in its feed. The events are used to notify
> client applications about changes to entitlements, or other configuration
> (e.g. new tenancy endpoints)that might be useful to user experience.
>
> As in the polling method in Scenario 2, to acknowledge events, the mobile
> app will need to use the POST (as defined in Scenario 2) to acknowledge SET
> delivery.  To be discussed, this might not be necessary if assured delivery
> is not required.
>
> Phil
>
> www.independentid.com
> [email-masked]
> _______________________________________________
> Id-event mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/id-event
>
>

-- 
Subscribe to the HARDTWARE <http://hardtware.com/> mail list to learn about
projects I am working on!